threads / patch / 63715

patch, 5 partsdoc: config: update for the ps/config-subcommands series

Subject: [PATCH 0/5] doc: config: update for the ps/config-subcommands series

## tl;dr

22 messages between Jun 30, 2025 and Jul 1, 2025. Diffs are folded; open one to read it.

replies: 21people: 5as markdown or json

kristofferhaugsbakk@fastmail.com· Jun 30, 2025, 19:10 UTC · lore
From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Update git-config(1) according to the ps/config-subcommands series (fe3ccc7aab (Merge branch 'ps/config-subcommands', 2024-05-15)):

1. Document `--show-names`
2. Document `--value`
3. Mention `--value` throughout instead of the deprecated
   `value-pattern`
4. Mention `--url` in the synopsis
Kristoffer Haugsbakk (5):
  doc: config: document --[no-]show-names
  doc: config: use --value=<pattern> consistently
  doc: config: document --[no-]value
  doc: config: use --value instead of value-pattern
  doc: config: mention --url in the synopsis
 Documentation/git-config.adoc | 28 +++++++++++++++++++++-------
 1 file changed, 21 insertions(+), 7 deletions(-)
base-commit: cf6f63ea6bf35173e02e18bdc6a4ba41288acff9
-- 
2.50.0.138.gf67de2ec4e7
kristofferhaugsbakk@fastmail.com· Jun 30, 2025, 19:10 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH 1/5] doc: config: document --[no-]show-names

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

These options were introduced in 4e513890008 (builtin/config: introduce "get" subcommand, 2024-05-06) but not documented here. Use the description from the source code.

Document this option and the negated form according to the current convention.[1]

`--show-names` is also the default when `--get-regexp` is given. But don’t mention it here since all the deprecated modes are quarantined in the “Deprecated Modes” section.

[1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
    >The default is `--no-show-names` unless `--url` is given and there are
    > no subsections in _<name>_.
    
    See: d4770964d50 (config: "git config --get-urlmatch" parses
    section.<url>.key, 2013-07-31)
 Documentation/git-config.adoc | 6 ++++++
 1 file changed, 6 insertions(+)
Show changes to Documentation/git-config.adoc +6 −0
diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index 936e0c5130f..e05bf813d46 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -259,6 +259,12 @@ Valid `<type>`'s include:
 	Output only the names of config variables for `list` or
 	`get`.
 
+`--show-names`::
+`--no-show-names`::
+	With `get`, show config keys in addition to their values. The
+	default is `--no-show-names` unless `--url` is given and there
+	are no subsections in _<name>_.
+
 --show-origin::
 	Augment the output of all queried config options with the
 	origin type (file, standard input, blob, command line) and

-- 
2.50.0.138.gf67de2ec4e7
kristofferhaugsbakk@fastmail.com· Jun 30, 2025, 19:10 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH 2/5] doc: config: use --value=<pattern> consistently

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This option was introduced in a series of commits from fe3ccc7aab (Merge branch 'ps/config-subcommands', 2024-05-15). But two styles were used for the value provided to the option:

1. Synopsis: `--value=<value>`
2. Deprecated Modes: `--value=<pattern>`
(2) is also used in the synopsis on the command.

Use (2) consistently throughout since it’s a pattern in the general case (`value` sounds more generic).

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-config.adoc | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
Show changes to Documentation/git-config.adoc +3 −3
diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index e05bf813d46..d3ddc538555 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -10,9 +10,9 @@ SYNOPSIS
 --------
 [verse]
 'git config list' [<file-option>] [<display-option>] [--includes]
-'git config get' [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<value>] [--fixed-value] [--default=<default>] <name>
-'git config set' [<file-option>] [--type=<type>] [--all] [--value=<value>] [--fixed-value] <name> <value>
-'git config unset' [<file-option>] [--all] [--value=<value>] [--fixed-value] <name>
+'git config get' [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<pattern>] [--fixed-value] [--default=<default>] <name>
+'git config set' [<file-option>] [--type=<type>] [--all] [--value=<pattern>] [--fixed-value] <name> <value>
+'git config unset' [<file-option>] [--all] [--value=<pattern>] [--fixed-value] <name>
 'git config rename-section' [<file-option>] <old-name> <new-name>
 'git config remove-section' [<file-option>] <name>
 'git config edit' [<file-option>]

-- 
2.50.0.138.gf67de2ec4e7
Kristoffer Haugsbakk· Jul 1, 2025, 07:27 UTC · re: kristofferhaugsbakk@fastmail.com · lore

Re: [PATCH 2/5] doc: config: use --value=<pattern> consistently

On Mon, Jun 30, 2025, at 21:10, kristofferhaugsbakk@fastmail.com wrote:
Show 15 quoted lines
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> This option was introduced in a series of commits from fe3ccc7aab (Merge
> branch 'ps/config-subcommands', 2024-05-15).  But two styles were used
> for the value provided to the option:
>
> 1. Synopsis: `--value=<value>`
> 2. Deprecated Modes: `--value=<pattern>`
>
> (2) is also used in the synopsis on the command.
>
> Use (2) consistently throughout since it’s a pattern in the general
> case (`value` sounds more generic).
>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
This missed some `--value=<value>`.
Kristoffer Haugsbakk· Jul 1, 2025, 08:00 UTC · re: kristofferhaugsbakk@fastmail.com · lore

Re: [PATCH 2/5] doc: config: use --value=<pattern> consistently

On Mon, Jun 30, 2025, at 21:10, kristofferhaugsbakk@fastmail.com wrote:
Show 15 quoted lines
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> This option was introduced in a series of commits from fe3ccc7aab (Merge
> branch 'ps/config-subcommands', 2024-05-15).  But two styles were used
> for the value provided to the option:
>
> 1. Synopsis: `--value=<value>`
> 2. Deprecated Modes: `--value=<pattern>`
>
> (2) is also used in the synopsis on the command.
>
> Use (2) consistently throughout since it’s a pattern in the general
> case (`value` sounds more generic).
>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
This also breaks t/t0450-txt-doc-vs-help.sh
kristofferhaugsbakk@fastmail.com· Jun 30, 2025, 19:10 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH 3/5] doc: config: document --[no-]value

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

These options were introduced in a series of commits from fe3ccc7aab (Merge branch 'ps/config-subcommands', 2024-05-15).[1] But they were not documented here.

Document this option and the negated form according to the current convention.[2]

† 1: `--value` is a replacement for the `value-pattern`
    positional argument
[2]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-config.adoc | 8 ++++++++
 1 file changed, 8 insertions(+)
Show changes to Documentation/git-config.adoc +8 −0
diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index d3ddc538555..03808b18d3e 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -200,6 +200,14 @@ See also <<FILES>>.
 	section in linkgit:gitrevisions[7] for a more complete list of
 	ways to spell blob names.
 
+`--value=<pattern>`::
+`--no-value`::
+	With `get`, `set`, and `unset`, match only against
+	_<pattern>_. The pattern is an extended regular expression unless
+	`--fixed-value` is given.
++
+Use `--no-value` to unset _<pattern>_.
+
 --fixed-value::
 	When used with the `value-pattern` argument, treat `value-pattern` as
 	an exact string instead of a regular expression. This will restrict

-- 
2.50.0.138.gf67de2ec4e7
Eric Sunshine· Jun 30, 2025, 19:26 UTC · re: kristofferhaugsbakk@fastmail.com · lore

Re: [PATCH 3/5] doc: config: document --[no-]value

On Mon, Jun 30, 2025 at 3:13 PM <kristofferhaugsbakk@fastmail.com> wrote:
Show 10 quoted lines
> These options were introduced in a series of commits from
> fe3ccc7aab (Merge branch 'ps/config-subcommands', 2024-05-15).[1]
> But they were not documented here.
>
> Document this option and the negated form according to the current
> convention.[2]
>
> † 1: `--value` is a replacement for the `value-pattern`
>     positional argument
> [2]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
s/† 1/[1]/
(Not itself worth a reroll.)
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
kristofferhaugsbakk@fastmail.com· Jun 30, 2025, 19:10 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH 4/5] doc: config: use --value instead of value-pattern

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This option was introduced in a series of commits from fe3ccc7aab (Merge branch 'ps/config-subcommands', 2024-05-15) and deprecated `value-pattern`. But `value-pattern` is still used throughout the doc.

The deprecated modes have been quarantined in the “Deprecated Modes” section. So let’s only use `--value=<pattern>` in the rest of the doc.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-config.adoc | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Show changes to Documentation/git-config.adoc +4 −4
diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index 03808b18d3e..9d8f9bb04e5 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -26,7 +26,7 @@ escaped.
 
 Multiple lines can be added to an option by using the `--append` option.
 If you want to update or unset an option which can occur on multiple
-lines, a `value-pattern` (which is an extended regular expression,
+lines, `--value=<pattern>` (which is an extended regular expression,
 unless the `--fixed-value` option is given) needs to be given.  Only the
 existing values that match the pattern are updated or unset.  If
 you want to handle the lines that do *not* match the pattern, just
@@ -109,7 +109,7 @@ OPTIONS
 
 --replace-all::
 	Default behavior is to replace at most one line. This replaces
-	all lines matching the key (and optionally the `value-pattern`).
+	all lines matching the key (and optionally `--value=<pattern>`).
 
 --append::
 	Adds a new line to the option without altering any existing
@@ -209,10 +209,10 @@ See also <<FILES>>.
 Use `--no-value` to unset _<pattern>_.
 
 --fixed-value::
-	When used with the `value-pattern` argument, treat `value-pattern` as
+	When used with `--value=<pattern>`, treat _<pattern>_ as
 	an exact string instead of a regular expression. This will restrict
 	the name/value pairs that are matched to only those where the value
-	is exactly equal to the `value-pattern`.
+	is exactly equal to _<pattern>_.
 
 --type <type>::
   'git config' will ensure that any input or output is valid under the given

-- 
2.50.0.138.gf67de2ec4e7
kristofferhaugsbakk@fastmail.com· Jun 30, 2025, 19:10 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH 5/5] doc: config: mention --url in the synopsis

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

4e513890008 (builtin/config: introduce "get" subcommand, 2024-05-06) introduced `get` and `--url` but didn’t add `--url` to the synopsis.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-config.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Show changes to Documentation/git-config.adoc +1 −1
diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index 9d8f9bb04e5..511b2e26bfb 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -10,7 +10,7 @@ SYNOPSIS
 --------
 [verse]
 'git config list' [<file-option>] [<display-option>] [--includes]
-'git config get' [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<pattern>] [--fixed-value] [--default=<default>] <name>
+'git config get' [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<pattern>] [--fixed-value] [--default=<default>] [--url=<url>] <name>
 'git config set' [<file-option>] [--type=<type>] [--all] [--value=<pattern>] [--fixed-value] <name> <value>
 'git config unset' [<file-option>] [--all] [--value=<pattern>] [--fixed-value] <name>
 'git config rename-section' [<file-option>] <old-name> <new-name>

-- 
2.50.0.138.gf67de2ec4e7
Kristoffer Haugsbakk· Jul 1, 2025, 07:09 UTC · re: kristofferhaugsbakk@fastmail.com · lore

Re: [PATCH 5/5] doc: config: mention --url in the synopsis

On Mon, Jun 30, 2025, at 21:10, kristofferhaugsbakk@fastmail.com wrote:
Show 6 quoted lines
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> 4e513890008 (builtin/config: introduce "get" subcommand, 2024-05-06)
> introduced `get` and `--url` but didn’t add `--url` to the synopsis.
>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
This makes `t/t0450-txt-doc-vs-help.sh` fail
https://lore.kernel.org/git/xmqqwm8sltbc.fsf@gitster.g/T/#m0e3ad91ded146f9c13f4ee52e4c37b15330c62a9
Junio C Hamano· Jun 30, 2025, 23:10 UTC · re: kristofferhaugsbakk@fastmail.com · lore

Re: [PATCH 0/5] doc: config: update for the ps/config-subcommands series

kristofferhaugsbakk@fastmail.com writes:
Show 23 quoted lines
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> Update git-config(1) according to the ps/config-subcommands series
> (fe3ccc7aab (Merge branch 'ps/config-subcommands', 2024-05-15)):
>
> 1. Document `--show-names`
> 2. Document `--value`
> 3. Mention `--value` throughout instead of the deprecated
>    `value-pattern`
> 4. Mention `--url` in the synopsis
>
> Kristoffer Haugsbakk (5):
>   doc: config: document --[no-]show-names
>   doc: config: use --value=<pattern> consistently
>   doc: config: document --[no-]value
>   doc: config: use --value instead of value-pattern
>   doc: config: mention --url in the synopsis
>
>  Documentation/git-config.adoc | 28 +++++++++++++++++++++-------
>  1 file changed, 21 insertions(+), 7 deletions(-)
>
>
> base-commit: cf6f63ea6bf35173e02e18bdc6a4ba41288acff9
Have you run tests with this series, especially t0450?
$ sh t0450-*.sh -i -v
...
expecting success of 0450.142 'config -h output and SYNOPSIS agree':
                t2s="$(adoc_to_synopsis "$builtin")" &&
                if test "$builtin" = "merge-tree"
                then
                        test_when_finished "rm -f t2s.new" &&
                        sed -e 's/ (deprecated)$//g' <"$t2s" >t2s.new
                        t2s=t2s.new
                fi &&
                h2s="$(help_to_synopsis "$builtin")" &&
                # The *.adoc and -h use different spacing for the
                # alignment of continued usage output, normalize it.
                align_after_nl "$builtin" <"$t2s" >adoc &&
                align_after_nl "$builtin" <"$h2s" >help &&
                test_cmp adoc help

--- adoc 2025-06-30 23:09:02.715600047 +0000 +++ help 2025-06-30 23:09:02.723600026 +0000

Show changes to diff +3 −3
@@ -1,7 +1,7 @@
 git config list [<file-option>] [<display-option>] [--includes]
-git config get [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<pattern>] [--fixed-value] [--default=<default>] [--url=<url>] <name>
-git config set [<file-option>] [--type=<type>] [--all] [--value=<pattern>] [--fixed-value] <name> <value>
-git config unset [<file-option>] [--all] [--value=<pattern>] [--fixed-value] <name>
+git config get [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<value>] [--fixed-value] [--default=<default>] <name>
+git config set [<file-option>] [--type=<type>] [--all] [--value=<value>] [--fixed-value] <name> <value>
+git config unset [<file-option>] [--all] [--value=<value>] [--fixed-value] <name>
 git config rename-section [<file-option>] <old-name> <new-name>
 git config remove-section [<file-option>] <name>
 git config edit [<file-option>]
not ok 142 - config -h output and SYNOPSIS agree
#
#                       t2s="$(adoc_to_synopsis "$builtin")" &&
#                       if test "$builtin" = "merge-tree"
#                       then
#                               test_when_finished "rm -f t2s.new" &&
#                               sed -e 's/ (deprecated)$//g' <"$t2s" >t2s.new
#                               t2s=t2s.new
#                       fi &&
#                       h2s="$(help_to_synopsis "$builtin")" &&
#
#                       # The *.adoc and -h use different spacing for the
#                       # alignment of continued usage output, normalize it.
#                       align_after_nl "$builtin" <"$t2s" >adoc &&
#                       align_after_nl "$builtin" <"$h2s" >help &&
#                       test_cmp adoc help
#
1..142
Patrick Steinhardt· Jul 1, 2025, 10:01 UTC · re: kristofferhaugsbakk@fastmail.com · lore

Re: [PATCH 0/5] doc: config: update for the ps/config-subcommands series

On Mon, Jun 30, 2025 at 09:10:22PM +0200, kristofferhaugsbakk@fastmail.com wrote:
Show 23 quoted lines
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> 
> Update git-config(1) according to the ps/config-subcommands series
> (fe3ccc7aab (Merge branch 'ps/config-subcommands', 2024-05-15)):
> 
> 1. Document `--show-names`
> 2. Document `--value`
> 3. Mention `--value` throughout instead of the deprecated
>    `value-pattern`
> 4. Mention `--url` in the synopsis
> 
> Kristoffer Haugsbakk (5):
>   doc: config: document --[no-]show-names
>   doc: config: use --value=<pattern> consistently
>   doc: config: document --[no-]value
>   doc: config: use --value instead of value-pattern
>   doc: config: mention --url in the synopsis
> 
>  Documentation/git-config.adoc | 28 +++++++++++++++++++++-------
>  1 file changed, 21 insertions(+), 7 deletions(-)
> 
> 
> base-commit: cf6f63ea6bf35173e02e18bdc6a4ba41288acff9

Except for the issues mentioned by Eric and Junio the changes look sensible to me. Thanks for improving these docs!

Patrick
Kristoffer Haugsbakk· Jul 1, 2025, 10:15 UTC · re: Patrick Steinhardt · lore

Re: [PATCH 0/5] doc: config: update for the ps/config-subcommands series

On Tue, Jul 1, 2025, at 12:01, Patrick Steinhardt wrote:
> Except for the issues mentioned by Eric and Junio the changes look
> sensible to me. Thanks for improving these docs!
Thanks. I’ll add your Acks to the changes.
Junio C Hamano· Jul 1, 2025, 16:03 UTC · re: Kristoffer Haugsbakk · lore

Re: [PATCH 0/5] doc: config: update for the ps/config-subcommands series

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
Show 5 quoted lines
> On Tue, Jul 1, 2025, at 12:01, Patrick Steinhardt wrote:
>> Except for the issues mentioned by Eric and Junio the changes look
>> sensible to me. Thanks for improving these docs!
>
> Thanks. I’ll add your Acks to the changes.
Thanks.
kristofferhaugsbakk@fastmail.com· Jul 1, 2025, 15:14 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH v2 0/5] doc: config: update for the ps/config-subcommands series

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Update git-config(1) according to the ps/config-subcommands series (fe3ccc7aab (Merge branch 'ps/config-subcommands', 2024-05-15)):

1. Document `--show-names`
2. Document `--value`
3. Mention `--value` throughout instead of the deprecated
   `value-pattern`
4. Mention `--url` in the synopsis
§ Changes in v2
• Unbreak t/t0450-txt-doc-vs-help.sh caused by source/doc synopsis being
  out of synch
• I missed some `--value=<value>` in patch 2/5
• Add acks from Patrick
  • Link: https://lore.kernel.org/git/aGOx3C7-9NNi7h8Z@pks.im/
• Use area=config for patches that touch both the source code (builtin)
  and the doc
Kristoffer Haugsbakk (5):
  doc: config: document --[no-]show-names
  config: use --value=<pattern> consistently
  doc: config: document --[no-]value
  doc: config: use --value instead of value-pattern
  config: mention --url in the synopsis
 Documentation/git-config.adoc | 28 +++++++++++++++++++++-------
 builtin/config.c              | 12 ++++++------
 2 files changed, 27 insertions(+), 13 deletions(-)
Interdiff against v1:
Show changes to builtin/config.c +6 −6
diff --git a/builtin/config.c b/builtin/config.c
index f70d6354772..5efe2730106 100644
--- a/builtin/config.c
+++ b/builtin/config.c
@@ -17,9 +17,9 @@
 
 static const char *const builtin_config_usage[] = {
 	N_("git config list [<file-option>] [<display-option>] [--includes]"),
-	N_("git config get [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<value>] [--fixed-value] [--default=<default>] <name>"),
-	N_("git config set [<file-option>] [--type=<type>] [--all] [--value=<value>] [--fixed-value] <name> <value>"),
-	N_("git config unset [<file-option>] [--all] [--value=<value>] [--fixed-value] <name>"),
+	N_("git config get [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<pattern>] [--fixed-value] [--default=<default>] [--url=<url>] <name>"),
+	N_("git config set [<file-option>] [--type=<type>] [--all] [--value=<pattern>] [--fixed-value] <name> <value>"),
+	N_("git config unset [<file-option>] [--all] [--value=<pattern>] [--fixed-value] <name>"),
 	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>]"),
@@ -33,17 +33,17 @@ static const char *const builtin_config_list_usage[] = {
 };
 
 static const char *const builtin_config_get_usage[] = {
-	N_("git config get [<file-option>] [<display-option>] [--includes] [--all] [--regexp=<regexp>] [--value=<value>] [--fixed-value] [--default=<default>] <name>"),
+	N_("git config get [<file-option>] [<display-option>] [--includes] [--all] [--regexp=<regexp>] [--value=<pattern>] [--fixed-value] [--default=<default>] <name>"),
 	NULL
 };
 
 static const char *const builtin_config_set_usage[] = {
-	N_("git config set [<file-option>] [--type=<type>] [--comment=<message>] [--all] [--value=<value>] [--fixed-value] <name> <value>"),
+	N_("git config set [<file-option>] [--type=<type>] [--comment=<message>] [--all] [--value=<pattern>] [--fixed-value] <name> <value>"),
 	NULL
 };
 
 static const char *const builtin_config_unset_usage[] = {
-	N_("git config unset [<file-option>] [--all] [--value=<value>] [--fixed-value] <name>"),
+	N_("git config unset [<file-option>] [--all] [--value=<pattern>] [--fixed-value] <name>"),
 	NULL
 };
 
Range-diff against v1:
1:  7d66a5403b3 ! 1:  3c90ec17459 doc: config: document --[no-]show-names
    @@ Commit message
     
         [1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
     
    +    Acked-by: Patrick Steinhardt <ps@pks.im>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
     
2:  a52322528da ! 2:  fa183e470c5 doc: config: use --value=<pattern> consistently
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    doc: config: use --value=<pattern> consistently
    +    config: use --value=<pattern> consistently
     
         This option was introduced in a series of commits from fe3ccc7aab (Merge
         branch 'ps/config-subcommands', 2024-05-15).  But two styles were used
    @@ Commit message
         Use (2) consistently throughout since it’s a pattern in the general
         case (`value` sounds more generic).
     
    +    Acked-by: Patrick Steinhardt <ps@pks.im>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
    +
    + ## Notes (series) ##
    +    v2:
    +    • Unbreak t/t0450-txt-doc-vs-help.sh caused by source/doc synopsis being
    +      out of synch
    +    • Replaced the rest that I missed
    +
      ## Documentation/git-config.adoc ##
     @@ Documentation/git-config.adoc: SYNOPSIS
      --------
    @@ Documentation/git-config.adoc: SYNOPSIS
      'git config rename-section' [<file-option>] <old-name> <new-name>
      'git config remove-section' [<file-option>] <name>
      'git config edit' [<file-option>]
    +
    + ## builtin/config.c ##
    +@@
    + 
    + static const char *const builtin_config_usage[] = {
    + 	N_("git config list [<file-option>] [<display-option>] [--includes]"),
    +-	N_("git config get [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<value>] [--fixed-value] [--default=<default>] <name>"),
    +-	N_("git config set [<file-option>] [--type=<type>] [--all] [--value=<value>] [--fixed-value] <name> <value>"),
    +-	N_("git config unset [<file-option>] [--all] [--value=<value>] [--fixed-value] <name>"),
    ++	N_("git config get [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<pattern>] [--fixed-value] [--default=<default>] <name>"),
    ++	N_("git config set [<file-option>] [--type=<type>] [--all] [--value=<pattern>] [--fixed-value] <name> <value>"),
    ++	N_("git config unset [<file-option>] [--all] [--value=<pattern>] [--fixed-value] <name>"),
    + 	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>]"),
    +@@ builtin/config.c: static const char *const builtin_config_list_usage[] = {
    + };
    + 
    + static const char *const builtin_config_get_usage[] = {
    +-	N_("git config get [<file-option>] [<display-option>] [--includes] [--all] [--regexp=<regexp>] [--value=<value>] [--fixed-value] [--default=<default>] <name>"),
    ++	N_("git config get [<file-option>] [<display-option>] [--includes] [--all] [--regexp=<regexp>] [--value=<pattern>] [--fixed-value] [--default=<default>] <name>"),
    + 	NULL
    + };
    + 
    + static const char *const builtin_config_set_usage[] = {
    +-	N_("git config set [<file-option>] [--type=<type>] [--comment=<message>] [--all] [--value=<value>] [--fixed-value] <name> <value>"),
    ++	N_("git config set [<file-option>] [--type=<type>] [--comment=<message>] [--all] [--value=<pattern>] [--fixed-value] <name> <value>"),
    + 	NULL
    + };
    + 
    + static const char *const builtin_config_unset_usage[] = {
    +-	N_("git config unset [<file-option>] [--all] [--value=<value>] [--fixed-value] <name>"),
    ++	N_("git config unset [<file-option>] [--all] [--value=<pattern>] [--fixed-value] <name>"),
    + 	NULL
    + };
    + 
3:  f8407f331e0 ! 3:  c85b42e3331 doc: config: document --[no-]value
    @@ Commit message
         Document this option and the negated form according to the current
         convention.[2]
     
    -    † 1: `--value` is a replacement for the `value-pattern`
    +    [1]: `--value` is a replacement for the `value-pattern`
             positional argument
         [2]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
     
    +    Acked-by: Patrick Steinhardt <ps@pks.im>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Documentation/git-config.adoc ##
4:  e895215e0cd ! 4:  e5eee1a0541 doc: config: use --value instead of value-pattern
    @@ Commit message
         The deprecated modes have been quarantined in the “Deprecated Modes”
         section.  So let’s only use `--value=<pattern>` in the rest of the doc.
     
    +    Acked-by: Patrick Steinhardt <ps@pks.im>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Documentation/git-config.adoc ##
5:  ac3257a934d ! 5:  8300e0fc349 doc: config: mention --url in the synopsis
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    doc: config: mention --url in the synopsis
    +    config: mention --url in the synopsis
     
         4e513890008 (builtin/config: introduce "get" subcommand, 2024-05-06)
         introduced `get` and `--url` but didn’t add `--url` to the synopsis.
     
    +    Acked-by: Patrick Steinhardt <ps@pks.im>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
    +
    + ## Notes (series) ##
    +    v2:
    +    • Unbreak t/t0450-txt-doc-vs-help.sh caused by source/doc synopsis being
    +      out of synch
    +
      ## Documentation/git-config.adoc ##
     @@ Documentation/git-config.adoc: SYNOPSIS
      --------
    @@ Documentation/git-config.adoc: SYNOPSIS
      'git config set' [<file-option>] [--type=<type>] [--all] [--value=<pattern>] [--fixed-value] <name> <value>
      'git config unset' [<file-option>] [--all] [--value=<pattern>] [--fixed-value] <name>
      'git config rename-section' [<file-option>] <old-name> <new-name>
    +
    + ## builtin/config.c ##
    +@@
    + 
    + static const char *const builtin_config_usage[] = {
    + 	N_("git config list [<file-option>] [<display-option>] [--includes]"),
    +-	N_("git config get [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<pattern>] [--fixed-value] [--default=<default>] <name>"),
    ++	N_("git config get [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<pattern>] [--fixed-value] [--default=<default>] [--url=<url>] <name>"),
    + 	N_("git config set [<file-option>] [--type=<type>] [--all] [--value=<pattern>] [--fixed-value] <name> <value>"),
    + 	N_("git config unset [<file-option>] [--all] [--value=<pattern>] [--fixed-value] <name>"),
    + 	N_("git config rename-section [<file-option>] <old-name> <new-name>"),

base-commit: cf6f63ea6bf35173e02e18bdc6a4ba41288acff9

-- 
2.50.0.136.g303b50f9132
kristofferhaugsbakk@fastmail.com· Jul 1, 2025, 15:14 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH v2 1/5] doc: config: document --[no-]show-names

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

These options were introduced in 4e513890008 (builtin/config: introduce "get" subcommand, 2024-05-06) but not documented here. Use the description from the source code.

Document this option and the negated form according to the current convention.[1]

`--show-names` is also the default when `--get-regexp` is given. But don’t mention it here since all the deprecated modes are quarantined in the “Deprecated Modes” section.

[1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
Acked-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
    >The default is `--no-show-names` unless `--url` is given and there are
    > no subsections in _<name>_.
    
    See: d4770964d50 (config: "git config --get-urlmatch" parses
    section.<url>.key, 2013-07-31)
 Documentation/git-config.adoc | 6 ++++++
 1 file changed, 6 insertions(+)
Show changes to Documentation/git-config.adoc +6 −0
diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index 936e0c5130f..e05bf813d46 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -259,6 +259,12 @@ Valid `<type>`'s include:
 	Output only the names of config variables for `list` or
 	`get`.
 
+`--show-names`::
+`--no-show-names`::
+	With `get`, show config keys in addition to their values. The
+	default is `--no-show-names` unless `--url` is given and there
+	are no subsections in _<name>_.
+
 --show-origin::
 	Augment the output of all queried config options with the
 	origin type (file, standard input, blob, command line) and

-- 
2.50.0.136.g303b50f9132
kristofferhaugsbakk@fastmail.com· Jul 1, 2025, 15:14 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH v2 2/5] config: use --value=<pattern> consistently

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This option was introduced in a series of commits from fe3ccc7aab (Merge branch 'ps/config-subcommands', 2024-05-15). But two styles were used for the value provided to the option:

1. Synopsis: `--value=<value>`
2. Deprecated Modes: `--value=<pattern>`
(2) is also used in the synopsis on the command.

Use (2) consistently throughout since it’s a pattern in the general case (`value` sounds more generic).

Acked-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
    v2:
    • Unbreak t/t0450-txt-doc-vs-help.sh caused by source/doc synopsis being
      out of synch
    • Replaced the rest that I missed
 Documentation/git-config.adoc |  6 +++---
 builtin/config.c              | 12 ++++++------
 2 files changed, 9 insertions(+), 9 deletions(-)
Show changes to 2 files +9 −9

Documentation/git-config.adoc, builtin/config.c

diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index e05bf813d46..d3ddc538555 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -10,9 +10,9 @@ SYNOPSIS
 --------
 [verse]
 'git config list' [<file-option>] [<display-option>] [--includes]
-'git config get' [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<value>] [--fixed-value] [--default=<default>] <name>
-'git config set' [<file-option>] [--type=<type>] [--all] [--value=<value>] [--fixed-value] <name> <value>
-'git config unset' [<file-option>] [--all] [--value=<value>] [--fixed-value] <name>
+'git config get' [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<pattern>] [--fixed-value] [--default=<default>] <name>
+'git config set' [<file-option>] [--type=<type>] [--all] [--value=<pattern>] [--fixed-value] <name> <value>
+'git config unset' [<file-option>] [--all] [--value=<pattern>] [--fixed-value] <name>
 'git config rename-section' [<file-option>] <old-name> <new-name>
 'git config remove-section' [<file-option>] <name>
 'git config edit' [<file-option>]
diff --git a/builtin/config.c b/builtin/config.c
index f70d6354772..706269647e5 100644
--- a/builtin/config.c
+++ b/builtin/config.c
@@ -17,9 +17,9 @@
 
 static const char *const builtin_config_usage[] = {
 	N_("git config list [<file-option>] [<display-option>] [--includes]"),
-	N_("git config get [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<value>] [--fixed-value] [--default=<default>] <name>"),
-	N_("git config set [<file-option>] [--type=<type>] [--all] [--value=<value>] [--fixed-value] <name> <value>"),
-	N_("git config unset [<file-option>] [--all] [--value=<value>] [--fixed-value] <name>"),
+	N_("git config get [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<pattern>] [--fixed-value] [--default=<default>] <name>"),
+	N_("git config set [<file-option>] [--type=<type>] [--all] [--value=<pattern>] [--fixed-value] <name> <value>"),
+	N_("git config unset [<file-option>] [--all] [--value=<pattern>] [--fixed-value] <name>"),
 	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>]"),
@@ -33,17 +33,17 @@ static const char *const builtin_config_list_usage[] = {
 };
 
 static const char *const builtin_config_get_usage[] = {
-	N_("git config get [<file-option>] [<display-option>] [--includes] [--all] [--regexp=<regexp>] [--value=<value>] [--fixed-value] [--default=<default>] <name>"),
+	N_("git config get [<file-option>] [<display-option>] [--includes] [--all] [--regexp=<regexp>] [--value=<pattern>] [--fixed-value] [--default=<default>] <name>"),
 	NULL
 };
 
 static const char *const builtin_config_set_usage[] = {
-	N_("git config set [<file-option>] [--type=<type>] [--comment=<message>] [--all] [--value=<value>] [--fixed-value] <name> <value>"),
+	N_("git config set [<file-option>] [--type=<type>] [--comment=<message>] [--all] [--value=<pattern>] [--fixed-value] <name> <value>"),
 	NULL
 };
 
 static const char *const builtin_config_unset_usage[] = {
-	N_("git config unset [<file-option>] [--all] [--value=<value>] [--fixed-value] <name>"),
+	N_("git config unset [<file-option>] [--all] [--value=<pattern>] [--fixed-value] <name>"),
 	NULL
 };
 

-- 
2.50.0.136.g303b50f9132
kristofferhaugsbakk@fastmail.com· Jul 1, 2025, 15:14 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH v2 3/5] doc: config: document --[no-]value

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

These options were introduced in a series of commits from fe3ccc7aab (Merge branch 'ps/config-subcommands', 2024-05-15).[1] But they were not documented here.

Document this option and the negated form according to the current convention.[2]

[1]: `--value` is a replacement for the `value-pattern`
    positional argument
[2]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/
Acked-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-config.adoc | 8 ++++++++
 1 file changed, 8 insertions(+)
Show changes to Documentation/git-config.adoc +8 −0
diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index d3ddc538555..03808b18d3e 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -200,6 +200,14 @@ See also <<FILES>>.
 	section in linkgit:gitrevisions[7] for a more complete list of
 	ways to spell blob names.
 
+`--value=<pattern>`::
+`--no-value`::
+	With `get`, `set`, and `unset`, match only against
+	_<pattern>_. The pattern is an extended regular expression unless
+	`--fixed-value` is given.
++
+Use `--no-value` to unset _<pattern>_.
+
 --fixed-value::
 	When used with the `value-pattern` argument, treat `value-pattern` as
 	an exact string instead of a regular expression. This will restrict

-- 
2.50.0.136.g303b50f9132
kristofferhaugsbakk@fastmail.com· Jul 1, 2025, 15:14 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH v2 4/5] doc: config: use --value instead of value-pattern

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This option was introduced in a series of commits from fe3ccc7aab (Merge branch 'ps/config-subcommands', 2024-05-15) and deprecated `value-pattern`. But `value-pattern` is still used throughout the doc.

The deprecated modes have been quarantined in the “Deprecated Modes” section. So let’s only use `--value=<pattern>` in the rest of the doc.

Acked-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-config.adoc | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Show changes to Documentation/git-config.adoc +4 −4
diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index 03808b18d3e..9d8f9bb04e5 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -26,7 +26,7 @@ escaped.
 
 Multiple lines can be added to an option by using the `--append` option.
 If you want to update or unset an option which can occur on multiple
-lines, a `value-pattern` (which is an extended regular expression,
+lines, `--value=<pattern>` (which is an extended regular expression,
 unless the `--fixed-value` option is given) needs to be given.  Only the
 existing values that match the pattern are updated or unset.  If
 you want to handle the lines that do *not* match the pattern, just
@@ -109,7 +109,7 @@ OPTIONS
 
 --replace-all::
 	Default behavior is to replace at most one line. This replaces
-	all lines matching the key (and optionally the `value-pattern`).
+	all lines matching the key (and optionally `--value=<pattern>`).
 
 --append::
 	Adds a new line to the option without altering any existing
@@ -209,10 +209,10 @@ See also <<FILES>>.
 Use `--no-value` to unset _<pattern>_.
 
 --fixed-value::
-	When used with the `value-pattern` argument, treat `value-pattern` as
+	When used with `--value=<pattern>`, treat _<pattern>_ as
 	an exact string instead of a regular expression. This will restrict
 	the name/value pairs that are matched to only those where the value
-	is exactly equal to the `value-pattern`.
+	is exactly equal to _<pattern>_.
 
 --type <type>::
   'git config' will ensure that any input or output is valid under the given

-- 
2.50.0.136.g303b50f9132
kristofferhaugsbakk@fastmail.com· Jul 1, 2025, 15:14 UTC · re: kristofferhaugsbakk@fastmail.com · lore

[PATCH v2 5/5] config: mention --url in the synopsis

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

4e513890008 (builtin/config: introduce "get" subcommand, 2024-05-06) introduced `get` and `--url` but didn’t add `--url` to the synopsis.

Acked-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
    v2:
    • Unbreak t/t0450-txt-doc-vs-help.sh caused by source/doc synopsis being
      out of synch
 Documentation/git-config.adoc | 2 +-
 builtin/config.c              | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
Show changes to 2 files +2 −2

Documentation/git-config.adoc, builtin/config.c

diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index 9d8f9bb04e5..511b2e26bfb 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -10,7 +10,7 @@ SYNOPSIS
 --------
 [verse]
 'git config list' [<file-option>] [<display-option>] [--includes]
-'git config get' [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<pattern>] [--fixed-value] [--default=<default>] <name>
+'git config get' [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<pattern>] [--fixed-value] [--default=<default>] [--url=<url>] <name>
 'git config set' [<file-option>] [--type=<type>] [--all] [--value=<pattern>] [--fixed-value] <name> <value>
 'git config unset' [<file-option>] [--all] [--value=<pattern>] [--fixed-value] <name>
 'git config rename-section' [<file-option>] <old-name> <new-name>
diff --git a/builtin/config.c b/builtin/config.c
index 706269647e5..5efe2730106 100644
--- a/builtin/config.c
+++ b/builtin/config.c
@@ -17,7 +17,7 @@
 
 static const char *const builtin_config_usage[] = {
 	N_("git config list [<file-option>] [<display-option>] [--includes]"),
-	N_("git config get [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<pattern>] [--fixed-value] [--default=<default>] <name>"),
+	N_("git config get [<file-option>] [<display-option>] [--includes] [--all] [--regexp] [--value=<pattern>] [--fixed-value] [--default=<default>] [--url=<url>] <name>"),
 	N_("git config set [<file-option>] [--type=<type>] [--all] [--value=<pattern>] [--fixed-value] <name> <value>"),
 	N_("git config unset [<file-option>] [--all] [--value=<pattern>] [--fixed-value] <name>"),
 	N_("git config rename-section [<file-option>] <old-name> <new-name>"),

-- 
2.50.0.136.g303b50f9132
Junio C Hamano· Jul 1, 2025, 17:32 UTC · re: kristofferhaugsbakk@fastmail.com · lore

Re: [PATCH v2 0/5] doc: config: update for the ps/config-subcommands series

kristofferhaugsbakk@fastmail.com writes:
Show 10 quoted lines
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> Update git-config(1) according to the ps/config-subcommands series
> (fe3ccc7aab (Merge branch 'ps/config-subcommands', 2024-05-15)):
>
> 1. Document `--show-names`
> 2. Document `--value`
> 3. Mention `--value` throughout instead of the deprecated
>    `value-pattern`
> 4. Mention `--url` in the synopsis
The result of getting rid of "value-pattern' looks really nice.

This round looked great; I haven't run tests yet, but I know this time you already did ;-), so I won't until I finish today's (1st) integration cycle.

Thanks.

← back to recent threads