Update our documentation of git-config(1) to stop mentioning the old
syntax while starting to mention the new syntax. Remove the help
mismatch in t0450 so that we start to ensure that the manpage and
builtin synopsis match.
Note that there will still be lots of mentions of the old style syntax
of git-config(1) throughout our documentation. This documentation will
be updated over time.
Signed-off-by: Patrick Steinhardt <ps@xxxxxx>
---
Documentation/git-config.txt | 204 ++++++++++++++++++-----------------
builtin/config.c | 46 +++++---
t/t0450/txt-help-mismatches | 1 -
3 files changed, 137 insertions(+), 114 deletions(-)
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index dff39093b5..edf67c85f7 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -9,21 +9,22 @@ git-config - Get and set repository or global options
SYNOPSIS
--------
[verse]
-'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] <name> [<value> [<value-pattern>]]
-'git config' [<file-option>] [--type=<type>] --add <name> <value>
-'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all <name> <value> [<value-pattern>]
-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get <name> [<value-pattern>]
-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all <name> [<value-pattern>]
-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp <name-regex> [<value-pattern>]
-'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch <name> <URL>
-'git config' [<file-option>] [--fixed-value] --unset <name> [<value-pattern>]
-'git config' [<file-option>] [--fixed-value] --unset-all <name> [<value-pattern>]
-'git config' [<file-option>] --rename-section <old-name> <new-name>
-'git config' [<file-option>] --remove-section <name>
-'git config' [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list
-'git config' [<file-option>] --get-color <name> [<default>]
-'git config' [<file-option>] --get-colorbool <name> [<stdout-is-tty>]
-'git config' [<file-option>] -e | --edit
+'git config list' [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only]
+'git config get' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] <name> [<value-pattern>]
+'git config get-all' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] <name> [<value-pattern>]
+'git config get-color' [<file-option>] <name> [<default>]
+'git config get-colorbool' [<file-option>] <name> [<stdout-is-tty>]
+'git config get-regexp' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] <name-regex> [<value-pattern>]
+'git config get-urlmatch' [<file-option>] [--type=<type>] [-z|--null] <name> <URL>
+'git config add' [<file-option>] [--type=<type>] <name> <value>
+'git config set' [<file-option>] [--type=<type>] <name> <value>
+'git config set-all' [<file-option>] [--type=<type>] [--fixed-value] <name> <value> [<value-pattern>]
+'git config unset' [<file-option>] [--fixed-value] <name> [<value-pattern>]
+'git config unset-all' [<file-option>] [--fixed-value] <name> [<value-pattern>]
+'git config replace-all' [<file-option>] [--type=<type>] [--fixed-value] <name> <value> [<value-pattern>]
+'git config rename-section' [<file-option>] <old-name> <new-name>
+'git config remove-section' [<file-option>] <name>
+'git config edit' [<file-option>]
DESCRIPTION
-----------
@@ -74,35 +75,50 @@ On success, the command returns the exit code 0.
A list of all available configuration variables can be obtained using the
`git help --config` command.
-[[OPTIONS]]
-OPTIONS
--------
-
---replace-all::
- Default behavior is to replace at most one line. This replaces
- all lines matching the key (and optionally the `value-pattern`).
+COMMANDS
+--------
---add::
- Adds a new line to the option without altering any existing
- values. This is the same as providing '^$' as the `value-pattern`
- in `--replace-all`.
+list::
+ List all variables set in config file, along with their values.
---get::
+get <name> [<value-pattern>]::
Get the value for a given key (optionally filtered by a regex
matching the value). Returns error code 1 if the key was not
found and the last value if multiple key values were found.
---get-all::
+get-all <name> [<value-pattern>]::
Like get, but returns all values for a multi-valued key.
---get-regexp::
- Like --get-all, but interprets the name as a regular expression and
+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`.
++
+`--type=color [--default=<default>]` is preferred over `get-color`
+(but note that `get-color` will omit the trailing newline printed by
+`--type=color`).
+
+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.
+ When the color setting for `name` is undefined, the command uses
+ `color.ui` as fallback.
+
+get-regex <name-regex> [<value-pattern>]::
+ Like `get-all`, but interprets the name as a regular expression and
writes out the key names. Regular expression matching is currently
case-sensitive and done against a canonicalized version of the key
in which section and variable names are lowercased, but subsection
names are not.
---get-urlmatch <name> <URL>::
+get-urlmatch <name> <URL>::
When given a two-part <name> as <section>.<key>, the value for
<section>.<URL>.<key> whose <URL> part matches the best to the
given URL is returned (if no such key exists, the value for
@@ -110,6 +126,43 @@ OPTIONS
<section> as name, do so for all the keys in the section and
list them. Returns error code 1 if no value is found.
+add <name> <value>::
+ Adds a new line to the option without altering any existing
+ values. This is the same as providing '^$' as the `value-pattern`
+ in `--replace-all`.
+
+set <name> <value>::
+ Set the config key to the given value. Adds a new key to the
+ configuration in case it does not yet exist. This subcommand fails when
+ the key has multiple values.
+
+set-all <name> <value> [<value-pattern>]::
+ Set all config keys to the given value.
+
+unset <name> [<value-pattern>]::
+ Remove the line matching the key from config file.
+
+unset-all <name> [<value-pattern>]::
+ Remove all lines matching the key from config file.
+
+replace-all <name> <value> [<value-pattern>]::
+ Default behavior is to replace at most one line. This replaces
+ all lines matching the key (and optionally the `value-pattern`).
+
+remove-section <name>::
+ Remove the given section from the configuration file.
+
+rename-section <old-name> <new-name>::
+ Rename the given section to a new name.
+
+edit::
+ Opens an editor to modify the specified config file; either
+ `--system`, `--global`, or repository (default).
+
+[[OPTIONS]]
+OPTIONS
+-------
+
--global::
For writing options: write to global `~/.gitconfig` file
rather than the repository `.git/config`, write to
@@ -166,22 +219,6 @@ See also <<FILES>>.
section in linkgit:gitrevisions[7] for a more complete list of
ways to spell blob names.
---remove-section::
- Remove the given section from the configuration file.
-
---rename-section::
- Rename the given section to a new name.
-
---unset::
- Remove the line matching the key from config file.
-
---unset-all::
- Remove all lines matching the key from config file.
-
--l::
---list::
- List all variables set in config file, along with their values.
-
--fixed-value::
When used with the `value-pattern` argument, treat `value-pattern` as
an exact string instead of a regular expression. This will restrict
@@ -236,8 +273,8 @@ Valid `<type>`'s include:
contain line breaks.
--name-only::
- Output only the names of config variables for `--list` or
- `--get-regexp`.
+ Output only the names of config variables for `list` or
+ `get-regexp`.
--show-origin::
Augment the output of all queried config options with the
@@ -250,33 +287,6 @@ Valid `<type>`'s include:
all queried config options with the scope of that value
(worktree, local, global, system, command).
---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.
- When the color setting for `name` is undefined, the command uses
- `color.ui` as fallback.
-
---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`.
-+
-`--type=color [--default=<default>]` is preferred over `--get-color`
-(but note that `--get-color` will omit the trailing newline printed by
-`--type=color`).
-
--e::
---edit::
- Opens an editor to modify the specified config file; either
- `--system`, `--global`, or repository (default).
-
--[no-]includes::
Respect `include.*` directives in config files when looking up
values. Defaults to `off` when a specific file is given (e.g.,
@@ -284,13 +294,13 @@ Valid `<type>`'s include:
config files.
--default <value>::
- When using `--get`, and the requested variable is not found, behave as if
+ When using `get`, and the requested variable is not found, behave as if
<value> were the value assigned to the that variable.
CONFIGURATION
-------------
`pager.config` is only respected when listing configuration, i.e., when
-using `--list` or any of the `--get-*` which may return multiple results.
+using `list` or any of the `get-*` subcommands which may return multiple results.
The default is to use a pager.
[[FILES]]
@@ -333,8 +343,8 @@ precedence over values read earlier. When multiple values are taken then all
values of a key from all files will be used.
By default, options are only written to the repository specific
-configuration file. Note that this also affects options like `--replace-all`
-and `--unset`. *'git config' will only ever change one file at a time*.
+configuration file. Note that this also affects subcommands like `replace-all`
+and `unset`. *'git config' will only ever change one file at a time*.
You can limit which configuration sources are read from or written to by
specifying the path of a file with the `--file` option, or by specifying a
@@ -469,7 +479,7 @@ Given a .git/config like this:
you can set the filemode to true with
------------
-% git config core.filemode true
+% git config set core.filemode true
------------
The hypothetical proxy command entries actually have a postfix to discern
@@ -477,7 +487,7 @@ what URL they apply to. Here is how to change the entry for kernel.org
to "ssh".
------------
-% git config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$'
+% git config set core.gitproxy '"ssh" for kernel.org' 'for kernel.org$'
------------
This makes sure that only the key/value pair for kernel.org is replaced.
@@ -485,7 +495,7 @@ This makes sure that only the key/value pair for kernel.org is replaced.
To delete the entry for renames, do
------------
-% git config --unset diff.renames
+% git config unset diff.renames
------------
If you want to delete an entry for a multivar (like core.gitproxy above),
@@ -494,51 +504,51 @@ you have to provide a regex matching the value of exactly one line.
To query the value for a given key, do
------------
-% git config --get core.filemode
+% git config get core.filemode
------------
or
------------
-% git config core.filemode
+% git config get core.filemode
------------
or, to query a multivar:
------------
-% git config --get core.gitproxy "for kernel.org$"
+% git config get core.gitproxy "for kernel.org$"
------------
If you want to know all the values for a multivar, do:
------------
-% git config --get-all core.gitproxy
+% git config get-all core.gitproxy
------------
If you like to live dangerously, you can replace *all* core.gitproxy by a
new one with
------------
-% git config --replace-all core.gitproxy ssh
+% git config replace-all core.gitproxy ssh
------------
However, if you really only want to replace the line for the default proxy,
i.e. the one without a "for ..." postfix, do something like this:
------------
-% git config core.gitproxy ssh '! for '
+% git config get core.gitproxy ssh '! for '
------------
To actually match only values with an exclamation mark, you have to
------------
-% git config section.key value '[!]'
+% git config get section.key value '[!]'
------------
To add a new proxy, without altering any of the existing ones, use
------------
-% git config --add core.gitproxy '"proxy-command" for example.com'
+% git config add core.gitproxy '"proxy-command" for example.com'
------------
An example to use customized color from the configuration in your
@@ -546,8 +556,8 @@ script:
------------
#!/bin/sh
-WS=$(git config --get-color color.diff.whitespace "blue reverse")
-RESET=$(git config --get-color "" "reset")
+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}"
------------
@@ -555,11 +565,11 @@ For URLs in `https://weak.example.com`, `http.sslVerify` is set to
false, while it is set to `true` for all others:
------------
-% git config --type=bool --get-urlmatch http.sslverify https://good.example.com
+% git config get-urlmatch --type=bool http.sslverify https://good.example.com
true
-% git config --type=bool --get-urlmatch http.sslverify https://weak.example.com
+% git config get-urlmatch --type=bool http.sslverify https://weak.example.com
false
-% git config --get-urlmatch http https://weak.example.com
+% git config get-urlmatch http https://weak.example.com
http.cookieFile /tmp/cookie.txt
http.sslverify false
------------
@@ -578,7 +588,7 @@ looks like
key = value1
--------
-and running `git config section.Subsection.key value2` will result in
+and running `git config add section.Subsection.key value2` will result in
--------
[section.subsection]
diff --git a/builtin/config.c b/builtin/config.c
index 10fa933931..61a9ad3eaa 100644
--- a/builtin/config.c
+++ b/builtin/config.c
@@ -16,7 +16,22 @@
#include "worktree.h"
static const char *const builtin_config_usage[] = {
- N_("git config [<options>]"),
+ N_("git config list [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only]"),
+ N_("git config get [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] <name> [<value-pattern>]"),
+ N_("git config get-all [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] <name> [<value-pattern>]"),
+ N_("git config get-color [<file-option>] <name> [<default>]"),
+ N_("git config get-colorbool [<file-option>] <name> [<stdout-is-tty>]"),
+ N_("git config get-regexp [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] <name-regex> [<value-pattern>]"),
+ N_("git config get-urlmatch [<file-option>] [--type=<type>] [-z|--null] <name> <URL>"),
+ N_("git config add [<file-option>] [--type=<type>] <name> <value>"),
+ N_("git config set [<file-option>] [--type=<type>] <name> <value>"),
+ N_("git config set-all [<file-option>] [--type=<type>] [--fixed-value] <name> <value> [<value-pattern>]"),
+ N_("git config unset [<file-option>] [--fixed-value] <name> [<value-pattern>]"),
+ N_("git config unset-all [<file-option>] [--fixed-value] <name> [<value-pattern>]"),
+ N_("git config replace-all [<file-option>] [--type=<type>] [--fixed-value] <name> <value> [<value-pattern>]"),
+ N_("git config rename-section [<file-option>] <old-name> <new-name>"),
+ N_("git config remove-section [<file-option>] <name>"),
+ N_("git config edit [<file-option>]"),
NULL
};
@@ -887,21 +902,20 @@ static struct option builtin_config_options[] = {
OPT_BOOL(0, "worktree", &use_worktree_config, N_("use per-worktree config file")),
OPT_STRING('f', "file", &given_config_source.file, N_("file"), N_("use given config file")),
OPT_STRING(0, "blob", &given_config_source.blob, N_("blob-id"), N_("read config from given blob object")),
- OPT_GROUP(N_("Action")),
- OPT_CMDMODE(0, "get", &action, N_("get value: name [value-pattern]"), ACTION_GET),
- OPT_CMDMODE(0, "get-all", &action, N_("get all values: key [value-pattern]"), ACTION_GET_ALL),
- OPT_CMDMODE(0, "get-regexp", &action, N_("get values for regexp: name-regex [value-pattern]"), ACTION_GET_REGEXP),
- OPT_CMDMODE(0, "get-urlmatch", &action, N_("get value specific for the URL: section[.var] URL"), ACTION_GET_URLMATCH),
- OPT_CMDMODE(0, "replace-all", &action, N_("replace all matching variables: name value [value-pattern]"), ACTION_REPLACE_ALL),
- OPT_CMDMODE(0, "add", &action, N_("add a new variable: name value"), ACTION_ADD),
- OPT_CMDMODE(0, "unset", &action, N_("remove a variable: name [value-pattern]"), ACTION_UNSET),
- OPT_CMDMODE(0, "unset-all", &action, N_("remove all matches: name [value-pattern]"), ACTION_UNSET_ALL),
- OPT_CMDMODE(0, "rename-section", &action, N_("rename section: old-name new-name"), ACTION_RENAME_SECTION),
- OPT_CMDMODE(0, "remove-section", &action, N_("remove a section: name"), ACTION_REMOVE_SECTION),
- OPT_CMDMODE('l', "list", &action, N_("list all"), ACTION_LIST),
- OPT_CMDMODE('e', "edit", &action, N_("open an editor"), ACTION_EDIT),
- OPT_CMDMODE(0, "get-color", &action, N_("find the color configured: slot [default]"), ACTION_GET_COLOR),
- OPT_CMDMODE(0, "get-colorbool", &action, N_("find the color setting: slot [stdout-is-tty]"), ACTION_GET_COLORBOOL),
+ OPT_CMDMODE_F(0, "get", &action, N_("get value: name [value-pattern]"), ACTION_GET, PARSE_OPT_HIDDEN),
+ OPT_CMDMODE_F(0, "get-all", &action, N_("get all values: key [value-pattern]"), ACTION_GET_ALL, PARSE_OPT_HIDDEN),
+ OPT_CMDMODE_F(0, "get-regexp", &action, N_("get values for regexp: name-regex [value-pattern]"), ACTION_GET_REGEXP, PARSE_OPT_HIDDEN),
+ OPT_CMDMODE_F(0, "get-urlmatch", &action, N_("get value specific for the URL: section[.var] URL"), ACTION_GET_URLMATCH, PARSE_OPT_HIDDEN),
+ OPT_CMDMODE_F(0, "replace-all", &action, N_("replace all matching variables: name value [value-pattern]"), ACTION_REPLACE_ALL, PARSE_OPT_HIDDEN),
+ OPT_CMDMODE_F(0, "add", &action, N_("add a new variable: name value"), ACTION_ADD, PARSE_OPT_HIDDEN),
+ OPT_CMDMODE_F(0, "unset", &action, N_("remove a variable: name [value-pattern]"), ACTION_UNSET, PARSE_OPT_HIDDEN),
+ OPT_CMDMODE_F(0, "unset-all", &action, N_("remove all matches: name [value-pattern]"), ACTION_UNSET_ALL, PARSE_OPT_HIDDEN),
+ OPT_CMDMODE_F(0, "rename-section", &action, N_("rename section: old-name new-name"), ACTION_RENAME_SECTION, PARSE_OPT_HIDDEN),
+ OPT_CMDMODE_F(0, "remove-section", &action, N_("remove a section: name"), ACTION_REMOVE_SECTION, PARSE_OPT_HIDDEN),
+ OPT_CMDMODE_F('l', "list", &action, N_("list all"), ACTION_LIST, PARSE_OPT_HIDDEN),
+ OPT_CMDMODE_F('e', "edit", &action, N_("open an editor"), ACTION_EDIT, PARSE_OPT_HIDDEN),
+ OPT_CMDMODE_F(0, "get-color", &action, N_("find the color configured: slot [default]"), ACTION_GET_COLOR, PARSE_OPT_HIDDEN),
+ OPT_CMDMODE_F(0, "get-colorbool", &action, N_("find the color setting: slot [stdout-is-tty]"), ACTION_GET_COLORBOOL, PARSE_OPT_HIDDEN),
OPT_GROUP(N_("Type")),
OPT_CALLBACK('t', "type", &type, N_("type"), N_("value is given this type"), option_parse_type),
OPT_CALLBACK_VALUE(0, "bool", &type, N_("value is \"true\" or \"false\""), TYPE_BOOL),
diff --git a/t/t0450/txt-help-mismatches b/t/t0450/txt-help-mismatches
index a0777acd66..28003f18c9 100644
--- a/t/t0450/txt-help-mismatches
+++ b/t/t0450/txt-help-mismatches
@@ -10,7 +10,6 @@ checkout
checkout-index
clone
column
-config
credential
credential-cache
credential-store
--
2.44.0
Attachment:
signature.asc
Description: PGP signature
