Re: [PATCH v4] checkout: add --progress option

[Jeff King <peff@peff.net>]

On Sun, Nov 01, 2015 at 12:52:57PM -0500, Eric Sunshine wrote:

> > diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> > index e269fb1..93ba35a 100644
> > --- a/Documentation/git-checkout.txt
> > +++ b/Documentation/git-checkout.txt
> > @@ -107,6 +107,12 @@ OPTIONS
> >  --quiet::
> >         Quiet, suppress feedback messages.
> >
> > +--progress::
> > +       Progress status is reported on the standard error stream
> > +       by default when it is attached to a terminal, unless -q
> > +       is specified. This flag forces progress status even if the
> > +       standard error stream is not directed to a terminal.
> 
> What this kind of implies, but neglects to say explicitly, is that the
> logic implemented by this patch also overrides --quiet. It probably
> should say so explicitly.
> 
> I realize that this text was copied from elsewhere (likely from
> git-clone.txt), but git-checkout.txt does try to do a bit better job
> with formatting, so it might be a good idea to quote -q with backticks
> (`-q` or `--quiet`).

I was the one who suggested originally that --progress should override
--quiet[1]. However, that was just based on what I thought was
reasonable. I didn't look at what clone or other commands do.
Consistency between commands is probably more important than any
particular behavior.

[1] To be honest, this is kind of a crazy corner case anyway. It was
more just that it has to do _something_.

> > +       /*
> > +        * Final processing of show_progress
> > +        * - User selected --progress: show progress
> > +        * - user selected --no-progress: skip progress
> > +        * - User didn't specify:
> > +        *     (check rules in order till finding the first matching one)
> > +        *     - user selected --quiet: skip progress
> > +        *     - stderr is connected to a terminal: show progress
> > +        *     - fallback: skip progress
> > +        */
> 
> It takes longer to read and digest this comment block than it does to
> comprehend the actual logic in code, which is pretty clear in its
> current form. Comment blocks which merely repeat easily digested code
> add little, if any, value, so it might be worthwhile to drop the
> comment altogether.

Yeah, I think I agree.

-Peff