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

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

[kristofferhaugsbakk]

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

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

[kristofferhaugsbakk]

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(+)

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

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

[kristofferhaugsbakk]

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(-)

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

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

[Kristoffer Haugsbakk]

On Mon, Jun 30, 2025, at 21:10, kristofferhaugsbakk@fastmail.com wrote:
> 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>`.

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

[Kristoffer Haugsbakk]

On Mon, Jun 30, 2025, at 21:10, kristofferhaugsbakk@fastmail.com wrote:
> 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

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

[kristofferhaugsbakk]

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(+)

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

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

[Eric Sunshine]

On Mon, Jun 30, 2025 at 3:13 PM <kristofferhaugsbakk@fastmail.com> wrote:
> 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>

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

[kristofferhaugsbakk]

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(-)

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

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

[kristofferhaugsbakk]

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(-)

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

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

[Kristoffer Haugsbakk]

On Mon, Jun 30, 2025, at 21:10, kristofferhaugsbakk@fastmail.com wrote:
> 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

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

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> 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
@@ -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

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

[Kristoffer Haugsbakk]

On Tue, Jul 1, 2025, at 01:10, Junio C Hamano wrote:
> Have you run tests with this series, especially t0450?

No. Sorry about that.

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

[Patrick Steinhardt]

On Mon, Jun 30, 2025 at 09:10:22PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> 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

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

[Kristoffer Haugsbakk]

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.

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

[Junio C Hamano]

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

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

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

[kristofferhaugsbakk]

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:
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

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

[kristofferhaugsbakk]

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(+)

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

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

[kristofferhaugsbakk]

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(-)

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

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

[kristofferhaugsbakk]

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(+)

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

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

[kristofferhaugsbakk]

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(-)

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

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

[kristofferhaugsbakk]

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(-)

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

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

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

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