[PATCH 8/8] Documentation/git-config: update to new-style syntax

From

Patrick Steinhardt <ps@pks.im>

Date

Mar 6, 2024, 11:32 UTC

Message-ID

<5ff2bf4a2286431a3b3048e0ea04d6551006d0d7.1709724089.git.ps@pks.im>

In-Reply-To

<cover.1709724089.git.ps@pks.im>

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 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