threads / patch / 60881

patchdoc: git.txt-Fix inconsistency param description

Subject: [PATCH] doc: git.txt-Fix inconsistency param description

## tl;dr

10 messages between Feb 9, 2024 and Apr 16, 2024. Diffs are folded; open one to read it.

replies: 9people: 4as markdown or json

秃头灯笼鱼 via GitGitGadget· Feb 9, 2024, 11:51 UTC · lore
From: =?UTF-8?q?=E7=A7=83=E5=A4=B4=E7=81=AF=E7=AC=BC=E9=B1=BC?=
 <ttdlyu@163.com>
Signed-off-by: 秃头灯笼鱼 <ttdlyu@163.com>
---
    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(-)
Show changes to Documentation/git.txt +1 −1
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 0d25224c969..eee277495bd 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -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

-- 
gitgitgadget
秃头灯笼鱼 via GitGitGadget· Apr 11, 2024, 07:56 UTC · re: 秃头灯笼鱼 via GitGitGadget · lore

[PATCH v2 0/2] 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"
-- 
gitgitgadget
秃头灯笼鱼 via GitGitGadget· Apr 11, 2024, 07:57 UTC · re: 秃头灯笼鱼 via GitGitGadget · lore

[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?=
 <ttdlyu@163.com>
Signed-off-by: 秃头灯笼鱼 <ttdlyu@163.com>
---
 Documentation/git.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Show changes to Documentation/git.txt +1 −1
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 0d25224c969..eee277495bd 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -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

-- 
gitgitgadget
Martin Ågren· Apr 11, 2024, 10:39 UTC · re: 秃头灯笼鱼 via GitGitGadget · lore

Re: [PATCH v2 1/2] doc: git.txt-Fix inconsistency param description

On Thu, 11 Apr 2024 at 10:20, 秃头灯笼鱼 via GitGitGadget <gitgitgadget@gmail.com> wrote:

Show 5 quoted lines
>
> From: =?UTF-8?q?=E7=A7=83=E5=A4=B4=E7=81=AF=E7=AC=BC=E9=B1=BC?=
>  <ttdlyu@163.com>
>
> Signed-off-by: 秃头灯笼鱼 <ttdlyu@163.com>
> -    [--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
Junio C Hamano· Apr 11, 2024, 18:09 UTC · re: Martin Ågren · lore

Re: [PATCH v2 1/2] doc: git.txt-Fix inconsistency param description

Martin Ågren <martin.agren@gmail.com> writes:
> 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.
ttdlyu· Apr 16, 2024, 06:02 UTC · re: Martin Ågren · lore

Re:Re: [PATCH v2 1/2] doc: git.txt-Fix inconsistency param description

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.)
At 2024-04-11 18:39:59, "Martin Ågren" <martin.agren@gmail.com> wrote:
Show 34 quoted lines
>On Thu, 11 Apr 2024 at 10:20, 秃头灯笼鱼 via GitGitGadget
><gitgitgadget@gmail.com> wrote:
>>
>> From: =?UTF-8?q?=E7=A7=83=E5=A4=B4=E7=81=AF=E7=AC=BC=E9=B1=BC?=
>>  <ttdlyu@163.com>
>>
>> Signed-off-by: 秃头灯笼鱼 <ttdlyu@163.com>
>
>> -    [--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
秃头灯笼鱼 via GitGitGadget· Apr 11, 2024, 07:57 UTC · re: 秃头灯笼鱼 via GitGitGadget · lore

[PATCH v2 2/2] doc: git.txt-Change "--user-formats" to "--user-interfaces"

From: =?UTF-8?q?=E7=A7=83=E5=A4=B4=E7=81=AF=E7=AC=BC=E9=B1=BC?=
 <ttdlyu@163.com>
Signed-off-by: 秃头灯笼鱼 <ttdlyu@163.com>
---
 Documentation/git.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Show changes to Documentation/git.txt +1 −1
diff --git a/Documentation/git.txt b/Documentation/git.txt
index eee277495bd..2bd4b9f06ca 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -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[]

-- 
gitgitgadget
Junio C Hamano· Apr 11, 2024, 18:11 UTC · re: 秃头灯笼鱼 via GitGitGadget · lore

Re: [PATCH v2 2/2] doc: git.txt-Change "--user-formats" to "--user-interfaces"

"秃头灯笼鱼 via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: =?UTF-8?q?=E7=A7=83=E5=A4=B4=E7=81=AF=E7=AC=BC=E9=B1=BC?=
>  <ttdlyu@163.com>
>
> Signed-off-by: 秃头灯笼鱼 <ttdlyu@163.com>

Have you followed Documentation/SubmittingPatches document, especially the part marked with [[real-name]]?

Just double checking.
ttdlyu· Apr 14, 2024, 02:49 UTC · re: Junio C Hamano · lore

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.

在 2024-04-12 02:11:11，"Junio C Hamano" <gitster@pobox.com> 写道：
Show 11 quoted lines
>"秃头灯笼鱼 via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: =?UTF-8?q?=E7=A7=83=E5=A4=B4=E7=81=AF=E7=AC=BC=E9=B1=BC?=
>>  <ttdlyu@163.com>
>>
>> Signed-off-by: 秃头灯笼鱼 <ttdlyu@163.com>
>
>Have you followed Documentation/SubmittingPatches document,
>especially the part marked with [[real-name]]?
>
>Just double checking.
Junio C Hamano· Apr 15, 2024, 17:10 UTC · re: ttdlyu · lore

Re: [PATCH v2 2/2] doc: git.txt-Change "--user-formats" to "--user-interfaces"

ttdlyu  <ttdlyu@163.com> writes:
> Sorry, to be honest, I haven’t read this document carefully before, I 
> will find time to read it carefully.
Thanks.

← back to recent threads