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

William Pursell· Dec 20, 2017, 13:14 UTC · lore

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

Signed-off-by: William Pursell <william.r.pursell@gmail.com>
---
 Documentation/git-branch.txt      | 2 +-
 Documentation/git-grep.txt        | 2 +-
 Documentation/git-show-branch.txt | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

Show changes to 3 files +3 −3

Documentation/git-branch.txt, Documentation/git-grep.txt, Documentation/git-show-branch.txt

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index b3084c99c..1e4dc3d91 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -128,7 +128,7 @@ OPTIONS
 --color[=<when>]::
  Color branches to highlight current, local, and
  remote-tracking branches.
- The value must be always (the default), never, or auto.
+ The value must be always, never, or auto (the default).

 --no-color::
  Turn off branch colors, even when the configuration file gives the
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 18b494731..cb62fa30e 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -201,7 +201,7 @@ providing this option will cause it to die.

 --color[=<when>]::
  Show colored matches.
- The value must be always (the default), never, or auto.
+ The value must be always, never, or auto (the default).

 --no-color::
  Turn off match highlighting, even when the configuration file
diff --git a/Documentation/git-show-branch.txt
b/Documentation/git-show-branch.txt
index 7818e0f09..4a7be5f0c 100644
--- a/Documentation/git-show-branch.txt
+++ b/Documentation/git-show-branch.txt
@@ -119,7 +119,7 @@ OPTIONS
 --color[=<when>]::
  Color the status sign (one of these: `*` `!` `+` `-`) of each commit
  corresponding to the branch it's in.
- The value must be always (the default), never, or auto.
+ The value must be always, never, or auto (the default).

 --no-color::
  Turn off colored output, even when the configuration file gives the

Jeff King· Dec 20, 2017, 13:23 UTC · re: William Pursell · lore

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

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

patchdoc: Fix specification of default (auto) for --color