doc: replace mentions of deprecated git config --list
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
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
@@ -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
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
@@ -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
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
@@ -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
@@ -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
@@ -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
@@ -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
Re: [PATCH 2/3] doc: gitcvs-migration: replace config -l and rephrase
In reply to [email protected]Documentation/gitcvs-migration.adoc them first before running git pull. · line 53
Quoted 12 lines · [email protected] writes:
Documentation/gitcvs-migration.adoc +1
-2@@ -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.
Re: [PATCH 3/3] doc: replace the rest of git config --list with `list`
In reply to [email protected]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@@ -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@@ -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 theDocumentation/technical/api-trace2.adoc +1
-1@@ -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=autoDocumentation/user-manual.adoc +0
-0
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.
Re: [PATCH 1/3] doc: var: link -l to git config list
In reply to [email protected]Quoted 19 lines · [email protected] writes:
From: Kristoffer Haugsbakk <[email protected]>
The option
-lis deprecated and links togit config -las the replacement—which is also deprecated. Break the deprecation chain by linking togit config list, the command which has supersededgit config -l.Also promote this part from a parenthetical to a warning admonition.
Signed-off-by Kristoffer Haugsbakk <[email protected]>--- Documentation/git-var.adoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)Documentation/git-var.adoc +0
-0
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.
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 ofgit 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_NAMEenvironment variable set and exported or your name configured correctly in GECOS field. We can ask what the value ofGIT_AUTHOR_IDENTis, 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 listrewrite 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.
Re: [PATCH 2/3] doc: gitcvs-migration: replace config -l and rephrase
In reply to Junio C HamanoQuoted 12 lines · Junio C Hamano
Quoted 10 lines · [email protected] writes:
Documentation/gitcvs-migration.adoc +0
-2@@ -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!
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
@@ -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
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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
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
@@ -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
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
linkgitwhile 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 listin 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)Signed-off-by Kristoffer Haugsbakk <[email protected]>---
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@@ -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