doc: git.txt-Fix inconsistency param description
PATCH 1/1 doc: git.txt-Fix inconsistency param description
From: =?UTF-8?q?=E7=A7=83=E5=A4=B4=E7=81=AF=E7=AC=BC=E9=B1=BC?=
<[email protected]>
---
Fix the inconsistency in the description of the namespace option's parameter
Since the parameter of the --namespace option can contain path separators \ and can be correctly parsed, I believe that --namespace=<name> in the SYNOPSIS section should be changed to --namespace=<path> to match the description in the OPTIONS section.
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1669%2Fttdly%2Fdoc%2Fgit.txt-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1669/ttdly/doc/git.txt-v1
Pull-Request: https://github.com/git/git/pull/1669
Documentation/git.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git.txt +1 -1
@@ -12,7 +12,7 @@ SYNOPSIS 'git' [-v | --version] [-h | --help] [-C <path>] [-c <name>=<value>] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path] [-p|--paginate|-P|--no-pager] [--no-replace-objects] [--bare] - [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>] + [--git-dir=<path>] [--work-tree=<path>] [--namespace=<path>] [--config-env=<name>=<envvar>] <command> [<args>] DESCRIPTION
base-commit: 5216f8f5c4089ec29ce49afa147434c23e0f0163
Signature · 1 line
gitgitgadget
v2 cover Fix the inconsistency in the description of the namespace option's parameter
Since the parameter of the --namespace option can contain path separators \
and can be correctly parsed, I believe that --namespace=<name> in the SYNOPSIS section should be changed to --namespace=<path> to match the description in the OPTIONS section.
秃头灯笼鱼 (2):
doc: git.txt-Fix inconsistency param description
doc: git.txt-Change "--user-formats" to "--user-interfaces"
Documentation/git.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
base-commit: 5216f8f5c4089ec29ce49afa147434c23e0f0163
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1669%2Fttdly%2Fdoc%2Fgit.txt-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1669/ttdly/doc/git.txt-v2
Pull-Request: https://github.com/git/git/pull/1669
Range-diff vs v1:
1: 28a5625f32c = 1: 28a5625f32c doc: git.txt-Fix inconsistency param description -: ----------- > 2: af548abd004 doc: git.txt-Change "--user-formats" to "--user-interfaces"
Signature · 1 line
gitgitgadget
PATCH v2 1/2 doc: git.txt-Fix inconsistency param description
From: =?UTF-8?q?=E7=A7=83=E5=A4=B4=E7=81=AF=E7=AC=BC=E9=B1=BC?=
<[email protected]>
--- Documentation/git.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git.txt +1 -1
@@ -12,7 +12,7 @@ SYNOPSIS 'git' [-v | --version] [-h | --help] [-C <path>] [-c <name>=<value>] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path] [-p|--paginate|-P|--no-pager] [--no-replace-objects] [--bare] - [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>] + [--git-dir=<path>] [--work-tree=<path>] [--namespace=<path>] [--config-env=<name>=<envvar>] <command> [<args>] DESCRIPTION
Signature · 1 line
gitgitgadget
Documentation/git.txt SYNOPSIS · line 15
Quoted 8 lines · 秃头灯笼鱼 via GitGitGadget
From: =?UTF-8?q?=E7=A7=83=E5=A4=B4=E7=81=AF=E7=AC=BC=E9=B1=BC?=
<[email protected]>Signed-off-by 秃头灯笼鱼 <[email protected]>Documentation/git.txt +1
-1- [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>] + [--git-dir=<path>] [--work-tree=<path>] [--namespace=<path>]
This makes it consistent with the instance later in the document, where it already says "--namespace=<path>". Ok.
However, this is documented as "equivalent to setting the GIT_NAMESPACE environment variable". And gitnamespaces(7) says "GIT_NAMESPACE=<namespace>", so that is still inconsistent. I also see this:
Note that namespaces which include a / will expand to a hierarchy of namespaces; for example, GIT_NAMESPACE=foo/bar will store refs under refs/namespaces/foo/refs/namespaces/bar/
So foo/bar isn't a file path. gitnamespaces(7) uses "path", "namespace" and "namespace path" sort of interchangeably. Even so, I think it could be a good idea to avoid "path" since it could give the wrong kind of ideas.
I wonder if this patch should instead change both --namespace=<name> and --namespace=<path> to --namespace=<namespace> and give some motivation such as "Make the placeholder consistent with the gitnamespaces document." What do you think?
Martin
Quoted 4 lines · Martin Ågren
I wonder if this patch should instead change both --namespace=<name> and --namespace=<path> to --namespace=<namespace> and give some motivation such as "Make the placeholder consistent with the gitnamespaces document." What do you think?
Sounds sensible to me.
That makes sense. I think what you said is very reasonable, and I hadn’t considered it thoroughly.
I've recently been working on the Chinese translation of the gitmanpages, and when I came across this inconsistency, I discussed it with the maintainers of the git-manpages-l10n repository. Clearly, neither of us had considered the description in gitnamespaces(7).
And thank you for your reply. If possible, could you please correct the description in git.txt? I am not very familiar with the process of submitting patches.
Yu Jian
(I'm not sure if you've seen the message on GitHub, so I'm sending you an email specifically. I apologize if I'm bothering you.)
Quoted 34 lines · Martin Ågren
Documentation/git.txt SYNOPSIS · line 15
Quoted 8 lines · 秃头灯笼鱼 via GitGitGadget
From: =?UTF-8?q?=E7=A7=83=E5=A4=B4=E7=81=AF=E7=AC=BC=E9=B1=BC?=
<[email protected]>Signed-off-by 秃头灯笼鱼 <[email protected]>Documentation/git.txt +1
-1- [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>] + [--git-dir=<path>] [--work-tree=<path>] [--namespace=<path>]This makes it consistent with the instance later in the document, where it already says "--namespace=<path>". Ok.
However, this is documented as "equivalent to setting the
GIT_NAMESPACEenvironment variable". And gitnamespaces(7) says "GIT_NAMESPACE=<namespace>", so that is still inconsistent. I also see this:Note that namespaces which include a / will expand to a hierarchy of namespaces; for example, GIT_NAMESPACE=foo/bar will store refs under refs/namespaces/foo/refs/namespaces/bar/
So foo/bar isn't a file path. gitnamespaces(7) uses "path", "namespace" and "namespace path" sort of interchangeably. Even so, I think it could be a good idea to avoid "path" since it could give the wrong kind of ideas.
I wonder if this patch should instead change both --namespace=<name> and --namespace=<path> to --namespace=<namespace> and give some motivation such as "Make the placeholder consistent with the gitnamespaces document." What do you think?
Martin
PATCH v2 2/2 doc: git.txt-Change "--user-formats" to "--user-interfaces"
In reply to 秃头灯笼鱼 via GitGitGadgetFrom: =?UTF-8?q?=E7=A7=83=E5=A4=B4=E7=81=AF=E7=AC=BC=E9=B1=BC?=
<[email protected]>
--- Documentation/git.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git.txt +1 -1
@@ -342,7 +342,7 @@ Repository, command and file interfaces --------------------------------------- This documentation discusses repository and command interfaces which -users are expected to interact with directly. See `--user-formats` in +users are expected to interact with directly. See `--user-interfaces` in linkgit:git-help[1] for more details on the criteria. include::cmds-userinterfaces.txt[]
Signature · 1 line
gitgitgadget
Re: [PATCH v2 2/2] doc: git.txt-Change "--user-formats" to "--user-interfaces"
Quoted 4 lines · 秃头灯笼鱼 via GitGitGadget
From: =?UTF-8?q?=E7=A7=83=E5=A4=B4=E7=81=AF=E7=AC=BC=E9=B1=BC?=
<[email protected]>Signed-off-by 秃头灯笼鱼 <[email protected]>
Have you followed Documentation/SubmittingPatches document, especially the part marked with [[real-name]]?
Just double checking.
Re:Re: [PATCH v2 2/2] doc: git.txt-Change "--user-formats" to "--user-interfaces"
Sorry, to be honest, I haven’t read this document carefully before, I will find time to read it carefully.
I sent several emails previously using Thunderbird, and I'm not sure if you have received them. However, I didn't see the emails I sent at
https://lore.kernel.org/git/af548abd00485e161c2e409b0b9fa80a3a061cc8.1712822221.git.gitgitgadget@gmail.com/.
Now I have switched to a different email client, and I hope you will receive this email.
Quoted 11 lines · 在 2024-04-12 02:11:11，"Junio C Hamano" <[email protected]> 写道：
Quoted 4 lines · 秃头灯笼鱼 via GitGitGadget
From: =?UTF-8?q?=E7=A7=83=E5=A4=B4=E7=81=AF=E7=AC=BC=E9=B1=BC?=
<[email protected]>Signed-off-by 秃头灯笼鱼 <[email protected]>Have you followed
Documentation/SubmittingPatchesdocument, especially the part marked with [[real-name]]?Just double checking.
Re: [PATCH v2 2/2] doc: git.txt-Change "--user-formats" to "--user-interfaces"
Quoted 2 lines · ttdlyu
Sorry, to be honest, I haven’t read this document carefully before, I will find time to read it carefully.
Thanks.