Re: [PATCH] doc: Fix specification of default (auto) for --color

From: Jeff King <peff@peff.net>
Date: Dec 20, 2017, 13:23 UTC
Message-ID: <20171220132335.GE17569@sigill.intra.peff.net>
In-Reply-To: <CAJPQ5Na1Z5QpgqS+wUVPGq-E+wOgsW5m4NzGEUcAnmDnRz+9DA@mail.gmail.com>

On Wed, Dec 20, 2017 at 05:14:02AM -0800, William Pursell wrote:

Show 7 quoted lines

> Current documentation for branch, show-branch, and grep contain the following:
> 
> --color[=<when>]
>            Show colored matches. The value must be always (the
> default), never, or auto.
> 
> This is incorrect, as the default is "auto".

I think what this is trying to say is that if you specify "--color" but not "<when>", then "<when>" defaults to "always". I.e., this is talking about a different default than if you didn't specify "--color" at all (and that default relies on the config, which in turn defaults to "auto").

The wording is quite confusing, though. Maybe we could clarify that and mention both "defaults":

  --color[=<when>]
	Show colored matches. The value of `<when>` must be `always`,
	`never`, or `auto`. If `<when>` is omitted (i.e., just
	`--color`), behave as if `--color=always` was specified. If no
	`--color` option is given, defaults, to the value of the
	`color.grep` config variable.

There may be a less clunky way of saying all that, though.

-Peff