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

From: Jeff King <peff@peff.net>
Date: Nov 1, 2015, 19:19 UTC
Message-ID: <20151101191902.GA19594@sigill.intra.peff.net>
In-Reply-To: <CAPig+cSLC_xkpXEznzPQdA=FE6GV5VSuwSrFy62Nzybv7jQf1g@mail.gmail.com>

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

Show 22 quoted lines

> > 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_.

Show 16 quoted lines

> > +       /*
> > +        * 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