log/show/whatchanged: introduce format.pretty configuration

diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index 5f66a7fcd5907b26ff6bdf94b53c2619c1eff509..fa161718dd33a0b4c3b58fb3898e74369bcc3d94 100644 (file)
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -9,17 +9,19 @@ git-config - Get and set repository or global options
 SYNOPSIS
 --------
 [verse]
-'git-config' [--system | --global] [type] [-z|--null] name [value [value_regex]]
-'git-config' [--system | --global] [type] --add name value
-'git-config' [--system | --global] [type] --replace-all name [value [value_regex]]
-'git-config' [--system | --global] [type] [-z|--null] --get name [value_regex]
-'git-config' [--system | --global] [type] [-z|--null] --get-all name [value_regex]
-'git-config' [--system | --global] [type] [-z|--null] --get-regexp name_regex [value_regex]
-'git-config' [--system | --global] --unset name [value_regex]
-'git-config' [--system | --global] --unset-all name [value_regex]
-'git-config' [--system | --global] --rename-section old_name new_name
-'git-config' [--system | --global] --remove-section name
-'git-config' [--system | --global] [-z|--null] -l | --list
+'git-config' [<file-option>] [type] [-z|--null] name [value [value_regex]]
+'git-config' [<file-option>] [type] --add name value
+'git-config' [<file-option>] [type] --replace-all name [value [value_regex]]
+'git-config' [<file-option>] [type] [-z|--null] --get name [value_regex]
+'git-config' [<file-option>] [type] [-z|--null] --get-all name [value_regex]
+'git-config' [<file-option>] [type] [-z|--null] --get-regexp name_regex [value_regex]
+'git-config' [<file-option>] --unset name [value_regex]
+'git-config' [<file-option>] --unset-all name [value_regex]
+'git-config' [<file-option>] --rename-section old_name new_name
+'git-config' [<file-option>] --remove-section name
+'git-config' [<file-option>] [-z|--null] -l | --list
+'git-config' [<file-option>] --get-color name [default]
+'git-config' [<file-option>] --get-colorbool name [stdout-is-tty]
 
 DESCRIPTION
 -----------
@@ -40,10 +42,16 @@ convert the value to the canonical form (simple decimal number for int,
 a "true" or "false" string for bool).  If no type specifier is passed,
 no checks or transformations are performed on the value.
 
+The file-option can be one of '--system', '--global' or '--file'
+which specify where the values will be read from or written to.
+The default is to assume the config file of the current repository,
+.git/config unless defined otherwise with GIT_DIR and GIT_CONFIG
+(see <<FILES>>).
+
 This command will fail if:
 
-. The .git/config file is invalid,
-. Can not write to .git/config,
+. The config file is invalid,
+. Can not write to the config file,
 . no section was provided,
 . the section or key is invalid,
 . you try to unset an option which does not exist,
@@ -93,6 +101,9 @@ rather than from all available files.
 +
 See also <<FILES>>.
 
+-f config-file, --file config-file::
+       Use the given config file instead of the one specified by GIT_CONFIG.
+
 --remove-section::
        Remove the given section from the configuration file.
 
@@ -119,21 +130,36 @@ See also <<FILES>>.
 
 -z, --null::
        For all options that output values and/or keys, always
-       end values with with the null character (instead of a
+       end values with the null character (instead of a
        newline). Use newline instead as a delimiter between
        key and value. This allows for secure parsing of the
        output without getting confused e.g. by values that
        contain line breaks.
 
+--get-colorbool name [stdout-is-tty]::
+
+       Find the color setting for `name` (e.g. `color.diff`) and output
+       "true" or "false".  `stdout-is-tty` should be either "true" or
+       "false", and is taken into account when configuration says
+       "auto".  If `stdout-is-tty` is missing, then checks the standard
+       output of the command itself, and exits with status 0 if color
+       is to be used, or exits with status 1 otherwise.
+
+--get-color name default::
+
+       Find the color configured for `name` (e.g. `color.diff.new`) and
+       output it as the ANSI color escape sequence to the standard
+       output.  The optional `default` parameter is used instead, if
+       there is no color configured for `name`.
 
 [[FILES]]
 FILES
 -----
 
-There are three files where git-config will search for configuration
-options:
+If not set explicitly with '--file', there are three files where
+git-config will search for configuration options:
 
-.git/config::
+$GIT_DIR/config::
        Repository specific configuration file. (The filename is
        of course relative to the repository root, not the working
        directory.)
@@ -205,9 +231,7 @@ Given a .git/config like this:
 
        ; Proxy settings
        [core]
-               gitproxy="ssh" for "ssh://kernel.org/"
                gitproxy="proxy-command" for kernel.org
-               gitproxy="myprotocol-command" for "my://"
                gitproxy=default-proxy ; for all the rest
 
 you can set the filemode to true with
@@ -282,9 +306,18 @@ To actually match only values with an exclamation mark, you have to
 To add a new proxy, without altering any of the existing ones, use
 
 ------------
-% git config core.gitproxy '"proxy" for example.com'
+% git config core.gitproxy '"proxy-command" for example.com'
 ------------
 
+An example to use customized color from the configuration in your
+script:
+
+------------
+#!/bin/sh
+WS=$(git config --get-color color.diff.whitespace "blue reverse")
+RESET=$(git config --get-color "" "reset")
+echo "${WS}your whitespace color or blue reverse${RESET}"
+------------
 
 include::config.txt[]
 
@@ -299,4 +332,4 @@ Documentation by Johannes Schindelin, Petr Baudis and the git-list <git@vger.ker
 
 GIT
 ---
-Part of the gitlink:git[7] suite
+Part of the linkgit:git[7] suite