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

Commit Message

ttdlyu April 11, 2024, 7:57 a.m. UTC

From: =?UTF-8?q?=E7=A7=83=E5=A4=B4=E7=81=AF=E7=AC=BC=E9=B1=BC?=
 <[e-mail]>

Signed-off-by: 秃头灯笼鱼 <[e-mail]>
---
 Documentation/git.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Comments

Martin Ågren April 11, 2024, 10:39 a.m. UTC | #1

On Thu, 11 Apr 2024 at 10:20, 秃头灯笼鱼 via GitGitGadget
<[e-mail]> wrote:
>
> From: =?UTF-8?q?=E7=A7=83=E5=A4=B4=E7=81=AF=E7=AC=BC=E9=B1=BC?=
>  <[e-mail]>
>
> Signed-off-by: 秃头灯笼鱼 <[e-mail]>

> -    [--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 April 11, 2024, 6:09 p.m. UTC | #2

Martin Ågren <[e-mail]> 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 April 16, 2024, 6:02 a.m. UTC | #3

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" <[e-mail]> wrote:
>On Thu, 11 Apr 2024 at 10:20, 秃头灯笼鱼 via GitGitGadget
><[e-mail]> wrote:
>>
>> From: =?UTF-8?q?=E7=A7=83=E5=A4=B4=E7=81=AF=E7=AC=BC=E9=B1=BC?=
>>  <[e-mail]>
>>
>> Signed-off-by: 秃头灯笼鱼 <[e-mail]>
>
>> -    [--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

Patch

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