Skip to contentSkip to conversation

doc: replace mentions of deprecated git config --list

PATCH Superseded [email protected] 2 participants 13 messages Mar 31 – Apr 6 Documentation

lore
Share & tools
lore
#0 lore raw

cover doc: replace mentions of deprecated git config --list

From: Kristoffer Haugsbakk <[email protected]>

Topic name: kh/doc-config-no-deprecated-list-opt

Topic summary: Replace uses of deprecated git config --list with its replacement git config list from topic ps/config-subcommands.

I found git config -l in git-var(1) and searched for other occurrences. I have not considered the other deprecated options.

[1/3] doc: var: link -l to git config list
[2/3] doc: gitcvs-migration: replace config -l and rephrase [3/3] doc: replace the rest of git config --list with list

 Documentation/git-var.adoc              | 5 +++--
 Documentation/gitcvs-migration.adoc     | 3 +--
 Documentation/gitprotocol-v2.adoc       | 2 +-
 Documentation/gittutorial.adoc          | 2 +-
 Documentation/technical/api-trace2.adoc | 2 +-
 Documentation/user-manual.adoc          | 2 +-
 6 files changed, 8 insertions(+), 8 deletions(-)

base-commit: 67ad42147a7acc2af6074753ebd03d904476118f

Signature · 1 line
2.53.0.32.gf6228eaf9cc
#1 lore raw

PATCH 1/3 doc: var: link -l to git config list

From: Kristoffer Haugsbakk <[email protected]>

The option -l is deprecated and links to git config -l as the replacement—which is also deprecated. Break the deprecation chain by linking to git config list, the command which has superseded git config -l.

Also promote this part from a parenthetical to a warning admonition.

---
 Documentation/git-var.adoc | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
Documentation/git-var.adoc +3 -2
index b606c2d6499..98f4dc1a479 100644
@@ -21,8 +21,9 @@ OPTIONS
 `-l`::
 	Display the logical variables. In addition, all the
 	variables of the Git configuration file .git/config are listed
-	as well. (However, the configuration variables listing functionality
-	is deprecated in favor of `git config -l`.)
+	as well.
++
+WARNING: Deprecated in favor of `git config list`.
 
 EXAMPLES
 --------
Signature · 1 line
2.53.0.32.gf6228eaf9cc
#2 lore raw

Re: [PATCH 1/3] doc: var: link -l to git config list

Quoted 19 lines · [email protected] writes:

From: Kristoffer Haugsbakk <[email protected]>

The option -l is deprecated and links to git config -l as the replacement—which is also deprecated. Break the deprecation chain by linking to git config list, the command which has superseded git config -l.

Also promote this part from a parenthetical to a warning admonition.

---
 Documentation/git-var.adoc | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
Documentation/git-var.adoc +0 -0
index b606c2d6499..98f4dc1a479 100644

Documentation/git-var.adoc OPTIONS · line 26

Quoted 8 lines
Documentation/git-var.adoc +3 -2
@@ -21,8 +21,9 @@ OPTIONS
 `-l`::
 	Display the logical variables. In addition, all the
 	variables of the Git configuration file .git/config are listed
-	as well. (However, the configuration variables listing functionality
-	is deprecated in favor of `git config -l`.)
+	as well.
++
+WARNING: Deprecated in favor of `git config list`.

This changes the meaning, and I am afraid in a bad way.

Use if "git var -l" to ask values of configuration variables is deprecated, as we would encourage use of "git config [-l | list]". "git var -l" is and will stay to be the way to ask about logical variables.

The new text, unlike the original, does not limit the deprecation only for asking about configuration variables.

The logical variables are called logical because their values are synthesized from information taken from different places (e.g., you might not have user.name configured but may have GIT_AUTHOR_NAME environment variable set and exported or your name configured correctly in GECOS field. We can ask what the value of GIT_AUTHOR_IDENT is, without knowing where that value comes from, and the source might be outside the usual Git configuration subsystem, which makes it "logical").

I'd prefer to see this step just stick to git config -l => git config list rewrite without the separate WARNING: style change.

#3 lore raw

Re: [PATCH 1/3] doc: var: link -l to git config list

Quoted 23 lines · Junio C Hamano
Quoted 3 lines

[snip]
++
+WARNING: Deprecated in favor of git config list.

This changes the meaning, and I am afraid in a bad way.

Use if "git var -l" to ask values of configuration variables is deprecated, as we would encourage use of "git config [-l | list]". "git var -l" is and will stay to be the way to ask about logical variables.

The new text, unlike the original, does not limit the deprecation only for asking about configuration variables.

The logical variables are called logical because their values are synthesized from information taken from different places (e.g., you might not have user.name configured but may have GIT_AUTHOR_NAME environment variable set and exported or your name configured correctly in GECOS field. We can ask what the value of GIT_AUTHOR_IDENT is, without knowing where that value comes from, and the source might be outside the usual Git configuration subsystem, which makes it "logical").

Quoted 2 lines

I'd prefer to see this step just stick to git config -l => git config list rewrite without the separate WARNING: style change.

Aye! I missed that it was only talking about parts of the behavior.

I’ll drop the admonition change.

#4 lore raw

PATCH 2/3 doc: gitcvs-migration: replace config -l and rephrase

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

Replace git config -l with the subcommand list since -l is deprecated.

Let’s also change the phrasing around the linkgit while we’re visiting this file.

The Git documentation pages are both manual pages and HTML pages, and in any case we already use the section syntax to refer to them. So we don’t have to say “the _ man page”; we can be a bit more concise and only lean on the preposition “in”.

And in order to avoid this double “git”:

see git config list in git-config(1) ...

We can rephrase to the subcommand, which is a typical pattern (config or option followed by “in git-command(1)”).

---

Notes (series):
But this does make it more difficult to find back to later.

 Documentation/gitcvs-migration.adoc | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)
Documentation/gitcvs-migration.adoc +1 -2
index 1cd1283d0f8..905d08cd5f9 100644
@@ -49,8 +49,7 @@ them first before running git pull.
 ================================
 The 'pull' command knows where to get updates from because of certain
 configuration variables that were set by the first 'git clone'
-command; see `git config -l` and the linkgit:git-config[1] man
-page for details.
+command; see the subcommand `list` in linkgit:git-config[1] for details.
 ================================
 
 You can update the shared repository with your changes by first committing
Signature · 1 line
2.53.0.32.gf6228eaf9cc
#5 lore raw

Re: [PATCH 2/3] doc: gitcvs-migration: replace config -l and rephrase

Documentation/gitcvs-migration.adoc them first before running git pull. · line 53

Quoted 12 lines · [email protected] writes:
Documentation/gitcvs-migration.adoc +1 -2
index 1cd1283d0f8..905d08cd5f9 100644
@@ -49,8 +49,7 @@ them first before running git pull.
 ================================
 The 'pull' command knows where to get updates from because of certain
 configuration variables that were set by the first 'git clone'
-command; see `git config -l` and the linkgit:git-config[1] man
-page for details.
+command; see the subcommand `list` in linkgit:git-config[1] for details.
 ================================

OK. In this step, "while at it" change is also sensible, unlike the one in [1/3]. It wouldn't have been time-wasting if you sifted the patches into "genuinely, move away from -l and to 'list'" changes and everything else, as the former we do not have to think, while the latter we do.

#6 lore raw

Re: [PATCH 2/3] doc: gitcvs-migration: replace config -l and rephrase

Quoted 12 lines · Junio C Hamano
Quoted 10 lines · [email protected] writes:
Documentation/gitcvs-migration.adoc +0 -2
index 1cd1283d0f8..905d08cd5f9 100644
@@ -49,8 +49,7 @@ them first before running git pull.
 ================================
 The 'pull' command knows where to get updates from because of certain
 configuration variables that were set by the first 'git clone'
-command; see `git config -l` and the linkgit:git-config[1] man
-page for details.
Quoted 8 lines

Documentation/gitcvs-migration.adoc them first before running git pull. · line 53

Quoted 2 lines
Documentation/gitcvs-migration.adoc +1 -0
+command; see the subcommand `list` in linkgit:git-config[1] for details.
 ================================

OK. In this step, "while at it" change is also sensible, unlike the one in [1/3]. It wouldn't have been time-wasting if you sifted the patches into "genuinely, move away from -l and to 'list'" changes and everything else, as the former we do not have to think, while the latter we do.

Okay. That’s great. I am far to the side of separating changes in terms of personal inclination.

I’ll split the -l/--list change and the While At Its.

Thanks!

#7 lore raw

PATCH 3/3 doc: replace the rest of git config --list with `list`

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

Replace the rest of git config --list (short or long) with the subcommand list since --list is deprecated.

Note that we leave the “man page” phrasing alone in the Git tutorial since it’s a tutorial and not a manual page. We can be more wordy in a tutorial context.

---
 Documentation/gitprotocol-v2.adoc       | 2 +-
 Documentation/gittutorial.adoc          | 2 +-
 Documentation/technical/api-trace2.adoc | 2 +-
 Documentation/user-manual.adoc          | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)
Documentation/gitprotocol-v2.adoc +1 -1
index c7db103299a..ec2562fb0a1 100644
@@ -659,7 +659,7 @@ use by the client, MUST indicate prerequisites (in any) with standard
 applicable.
 +
 The advertised URI may alternatively contain a plaintext file that `git
-config --list` would accept (with the `--file` option). The key-value
+config list` would accept (with the `--file` option). The key-value
 pairs in this list are in the `bundle.*` namespace (see
 linkgit:git-config[1]).
 
Documentation/gittutorial.adoc +1 -1
index f89ad30cf65..519b8d8be2c 100644
@@ -432,7 +432,7 @@ bob$ git config --get remote.origin.url
 -------------------------------------
 
 (The complete configuration created by `git clone` is visible using
-`git config -l`, and the linkgit:git-config[1] man page
+`git config list`, and the linkgit:git-config[1] man page
 explains the meaning of each option.)
 
 Git also keeps a pristine copy of Alice's `master` branch under the
Documentation/technical/api-trace2.adoc +1 -1
index cf493dae03f..918e517c2e6 100644
@@ -1253,7 +1253,7 @@ it.
 $ git config --system color.ui never
 $ git config --global color.ui always
 $ git config --local color.ui auto
-$ git config --list --show-scope | grep 'color.ui'
+$ git config list --show-scope | grep 'color.ui'
 system  color.ui=never
 global  color.ui=always
 local   color.ui=auto
Documentation/user-manual.adoc +1 -1
index 76969871176..3cd94c7afa1 100644
@@ -2865,7 +2865,7 @@ stored in Git configuration variables, which you can see using
 linkgit:git-config[1]:
 
 -------------------------------------------------
-$ git config -l
+$ git config list
 core.repositoryformatversion=0
 core.filemode=true
 core.logallrefupdates=true
Signature · 1 line
2.53.0.32.gf6228eaf9cc
#8 lore raw

Re: [PATCH 3/3] doc: replace the rest of git config --list with `list`

Documentation/gitprotocol-v2.adoc use by the client, MUST indicate prerequisites (in any) with standard · line 664

Quoted 12 lines · [email protected] writes:
Documentation/gitprotocol-v2.adoc +1 -1
index c7db103299a..ec2562fb0a1 100644
@@ -659,7 +659,7 @@ use by the client, MUST indicate prerequisites (in any) with standard
 applicable.
 +
 The advertised URI may alternatively contain a plaintext file that `git
-config --list` would accept (with the `--file` option). The key-value
+config list` would accept (with the `--file` option). The key-value
 pairs in this list are in the `bundle.*` namespace (see
 linkgit:git-config[1]).

OK.

Quoted 31 lines
Documentation/gittutorial.adoc +1 -1
index f89ad30cf65..519b8d8be2c 100644
@@ -432,7 +432,7 @@ bob$ git config --get remote.origin.url
 -------------------------------------
 
 (The complete configuration created by `git clone` is visible using
-`git config -l`, and the linkgit:git-config[1] man page
+`git config list`, and the linkgit:git-config[1] man page
 explains the meaning of each option.)
 
 Git also keeps a pristine copy of Alice's `master` branch under the
Documentation/technical/api-trace2.adoc +1 -1
index cf493dae03f..918e517c2e6 100644
@@ -1253,7 +1253,7 @@ it.
 $ git config --system color.ui never
 $ git config --global color.ui always
 $ git config --local color.ui auto
-$ git config --list --show-scope | grep 'color.ui'
+$ git config list --show-scope | grep 'color.ui'
 system  color.ui=never
 global  color.ui=always
 local   color.ui=auto
Documentation/user-manual.adoc +0 -0
index 76969871176..3cd94c7afa1 100644

Documentation/user-manual.adoc stored in Git configuration variables, which you can see using · line 2871

Quoted 8 lines
Documentation/user-manual.adoc +1 -1
@@ -2865,7 +2865,7 @@ stored in Git configuration variables, which you can see using
 linkgit:git-config[1]:
 
 -------------------------------------------------
-$ git config -l
+$ git config list
 core.repositoryformatversion=0
 core.filemode=true
 core.logallrefupdates=true

Looking good.

Thanks.

#9 lore raw

v2 cover doc: replace mentions of deprecated git config --list

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

Topic name: kh/doc-config-no-deprecated-list-opt

Topic summary: Replace uses of deprecated git config --list with its replacement git config list from topic ps/config-subcommands.

I found git config -l in git-var(1) and searched for other occurrences. I have not considered the other deprecated options.

CHANGES IN V2

Do all the straightforward deprecated-to-new transformations. Then do the “man page” change. Also drop the faulty admonission change.

See the notes on the patches for details.

[1/2] doc: replace git config --list/-l with list [2/2] doc: gitcvs-migration: rephrase “man page”

 Documentation/git-var.adoc              | 2 +-
 Documentation/gitcvs-migration.adoc     | 3 +--
 Documentation/gitprotocol-v2.adoc       | 2 +-
 Documentation/gittutorial.adoc          | 2 +-
 Documentation/technical/api-trace2.adoc | 2 +-
 Documentation/user-manual.adoc          | 2 +-
 6 files changed, 6 insertions(+), 7 deletions(-)

Interdiff against v1:

Documentation/git-var.adoc +2 -3
index 98f4dc1a479..697c10adedc 100644
@@ -21,9 +21,8 @@ OPTIONS
 `-l`::
 	Display the logical variables. In addition, all the
 	variables of the Git configuration file .git/config are listed
-	as well.
-+
-WARNING: Deprecated in favor of `git config list`.
+	as well. (However, the configuration variables listing functionality
+	is deprecated in favor of `git config list`.)
 
 EXAMPLES
 --------

base-commit: 67ad42147a7acc2af6074753ebd03d904476118f

Signature · 1 line
2.53.0.32.gf6228eaf9cc
#10 lore raw

PATCH v2 1/2 doc: replace git config --list/-l with `list`

From: Kristoffer Haugsbakk <[email protected]>

Replace uses of git config --list (short or long) with the subcommand list since --list is deprecated.

We will change the “man page” phrasing in gitcvs-migration(7) in the next commit, since we are already visiting that sentence. But note that we leave the “man page” phrasing in the sentence that we touch in gittutorial(7) since it’s a tutorial and not a manual page. We can be more wordy in a tutorial context.

---

Notes (series):
v2: Now do all the deprecated --list/-l changes in one step
v1: (was spread over the three patches)

 Documentation/git-var.adoc              | 2 +-
 Documentation/gitcvs-migration.adoc     | 2 +-
 Documentation/gitprotocol-v2.adoc       | 2 +-
 Documentation/gittutorial.adoc          | 2 +-
 Documentation/technical/api-trace2.adoc | 2 +-
 Documentation/user-manual.adoc          | 2 +-
 6 files changed, 6 insertions(+), 6 deletions(-)
Documentation/git-var.adoc +1 -1
index b606c2d6499..697c10adedc 100644
@@ -22,7 +22,7 @@ OPTIONS
 	Display the logical variables. In addition, all the
 	variables of the Git configuration file .git/config are listed
 	as well. (However, the configuration variables listing functionality
-	is deprecated in favor of `git config -l`.)
+	is deprecated in favor of `git config list`.)
 
 EXAMPLES
 --------
Documentation/gitcvs-migration.adoc +1 -1
index 1cd1283d0f8..2883834b714 100644
@@ -49,7 +49,7 @@ them first before running git pull.
 ================================
 The 'pull' command knows where to get updates from because of certain
 configuration variables that were set by the first 'git clone'
-command; see `git config -l` and the linkgit:git-config[1] man
+command; see `git config list` and the linkgit:git-config[1] man
 page for details.
 ================================
 
Documentation/gitprotocol-v2.adoc +1 -1
index c7db103299a..ec2562fb0a1 100644
@@ -659,7 +659,7 @@ use by the client, MUST indicate prerequisites (in any) with standard
 applicable.
 +
 The advertised URI may alternatively contain a plaintext file that `git
-config --list` would accept (with the `--file` option). The key-value
+config list` would accept (with the `--file` option). The key-value
 pairs in this list are in the `bundle.*` namespace (see
 linkgit:git-config[1]).
 
Documentation/gittutorial.adoc +1 -1
index f89ad30cf65..519b8d8be2c 100644
@@ -432,7 +432,7 @@ bob$ git config --get remote.origin.url
 -------------------------------------
 
 (The complete configuration created by `git clone` is visible using
-`git config -l`, and the linkgit:git-config[1] man page
+`git config list`, and the linkgit:git-config[1] man page
 explains the meaning of each option.)
 
 Git also keeps a pristine copy of Alice's `master` branch under the
Documentation/technical/api-trace2.adoc +1 -1
index cf493dae03f..918e517c2e6 100644
@@ -1253,7 +1253,7 @@ it.
 $ git config --system color.ui never
 $ git config --global color.ui always
 $ git config --local color.ui auto
-$ git config --list --show-scope | grep 'color.ui'
+$ git config list --show-scope | grep 'color.ui'
 system  color.ui=never
 global  color.ui=always
 local   color.ui=auto
Documentation/user-manual.adoc +1 -1
index 76969871176..3cd94c7afa1 100644
@@ -2865,7 +2865,7 @@ stored in Git configuration variables, which you can see using
 linkgit:git-config[1]:
 
 -------------------------------------------------
-$ git config -l
+$ git config list
 core.repositoryformatversion=0
 core.filemode=true
 core.logallrefupdates=true
Signature · 1 line
2.53.0.32.gf6228eaf9cc
#11 lore raw

PATCH v2 2/2 doc: gitcvs-migration: rephrase “man page”

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

Let’s change the phrasing around the linkgit while we’re visiting this file (see previous commit[1]).

We use the section syntax to refer to man pages, so writing “man page” next to it is a bit redundant. We can be more concise and just lean on the preposition “in”.

And in order to avoid this double “git”:

see git config list in git-config(1) ...

We can rephrase to the subcommand, which is a typical pattern (config or option followed by “in git-command(1)”).

† 1: Which also discusses why we do not change a similar phrasing
in gittutorial(7)

---

Notes (series):
v2:
• Just the “man page” change, which now comes after the --list/-l change
• Restructure commit message paragraph so that it leads with “section syntax” and has a simpler structure.
• Footnote to remind what was discussed on the previous commit
v1: (combined --list/-l change and “man page” change)

 Documentation/gitcvs-migration.adoc | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)
Documentation/gitcvs-migration.adoc +1 -2
index 2883834b714..905d08cd5f9 100644
@@ -49,8 +49,7 @@ them first before running git pull.
 ================================
 The 'pull' command knows where to get updates from because of certain
 configuration variables that were set by the first 'git clone'
-command; see `git config list` and the linkgit:git-config[1] man
-page for details.
+command; see the subcommand `list` in linkgit:git-config[1] for details.
 ================================
 
 You can update the shared repository with your changes by first committing
Signature · 1 line
2.53.0.32.gf6228eaf9cc
#12 lore raw

Re: [PATCH v2 2/2] doc: gitcvs-migration: rephrase “man page”

Quoted 8 lines · [email protected] writes:

From: Kristoffer Haugsbakk <[email protected]>

Let’s change the phrasing around the linkgit while we’re visiting this file (see previous commit[1]).

We use the section syntax to refer to man pages, so writing “man page” next to it is a bit redundant. We can be more concise and just lean on the preposition “in”.

Being succinct is better ;-).

Quoted 6 lines

And in order to avoid this double “git”:

see git config list in git-config(1) ...

We can rephrase to the subcommand, which is a typical pattern (config or option followed by “in git-command(1)”).

Again, being succinct is very good.

Quoted 31 lines

† 1: Which also discusses why we do not change a similar phrasing
in gittutorial(7)

---

Notes (series):
v2:
• Just the “man page” change, which now comes after the --list/-l change
• Restructure commit message paragraph so that it leads with “section syntax” and has a simpler structure.
• Footnote to remind what was discussed on the previous commit
v1: (combined --list/-l change and “man page” change)

 Documentation/gitcvs-migration.adoc | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)
Documentation/gitcvs-migration.adoc +1 -2
index 2883834b714..905d08cd5f9 100644
@@ -49,8 +49,7 @@ them first before running git pull.
 ================================
 The 'pull' command knows where to get updates from because of certain
 configuration variables that were set by the first 'git clone'
-command; see `git config list` and the linkgit:git-config[1] man
-page for details.
+command; see the subcommand `list` in linkgit:git-config[1] for details.
 ================================
 
 You can update the shared repository with your changes by first committing