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

10 messages from 2024-02-09 to 2024-04-16. Participants: 秃头灯笼鱼 via GitGitGadget, Martin Ågren, Junio C Hamano, ttdlyu.
Thread: https://gitlist.dev/t/60881

## 秃头灯笼鱼 via GitGitGadget, 2024-02-09 11:51

Subject: [PATCH] doc: git.txt-Fix inconsistency param description
Message-ID: <pull.1669.git.git.1707479467028.gitgitgadget@gmail.com>
URL: https://gitlist.dev/e/pull.1669.git.git.1707479467028.gitgitgadget%40gmail.com

```
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(-)

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, 2024-04-11 07:56

Subject: [PATCH v2 0/2] Fix the inconsistency in the description of the namespace option's parameter
Message-ID: <pull.1669.v2.git.git.1712822221.gitgitgadget@gmail.com>
URL: https://gitlist.dev/e/pull.1669.v2.git.git.1712822221.gitgitgadget%40gmail.com
In-Reply-To: <pull.1669.git.git.1707479467028.gitgitgadget@gmail.com>

```
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, 2024-04-11 07:57

Subject: [PATCH v2 1/2] doc: git.txt-Fix inconsistency param description
Message-ID: <28a5625f32cca6ef134a385fe9ba66962c40100f.1712822221.git.gitgitgadget@gmail.com>
URL: https://gitlist.dev/e/28a5625f32cca6ef134a385fe9ba66962c40100f.1712822221.git.gitgitgadget%40gmail.com
In-Reply-To: <pull.1669.v2.git.git.1712822221.gitgitgadget@gmail.com>

```
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(-)

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


```

## 秃头灯笼鱼 via GitGitGadget, 2024-04-11 07:57

Subject: [PATCH v2 2/2] doc: git.txt-Change "--user-formats" to "--user-interfaces"
Message-ID: <af548abd00485e161c2e409b0b9fa80a3a061cc8.1712822221.git.gitgitgadget@gmail.com>
URL: https://gitlist.dev/e/af548abd00485e161c2e409b0b9fa80a3a061cc8.1712822221.git.gitgitgadget%40gmail.com
In-Reply-To: <pull.1669.v2.git.git.1712822221.gitgitgadget@gmail.com>

```
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(-)

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

```

## Martin Ågren, 2024-04-11 10:39

Subject: Re: [PATCH v2 1/2] doc: git.txt-Fix inconsistency param description
Message-ID: <CAN0heSpvKFKVnyve0wvcVJ3gvm5H8OggVTKpz2Se4je3iRHwCw@mail.gmail.com>
URL: https://gitlist.dev/e/CAN0heSpvKFKVnyve0wvcVJ3gvm5H8OggVTKpz2Se4je3iRHwCw%40mail.gmail.com
In-Reply-To: <28a5625f32cca6ef134a385fe9ba66962c40100f.1712822221.git.gitgitgadget@gmail.com>

```
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

```

## Junio C Hamano, 2024-04-11 18:09

Subject: Re: [PATCH v2 1/2] doc: git.txt-Fix inconsistency param description
Message-ID: <xmqqttk7u5yr.fsf@gitster.g>
URL: https://gitlist.dev/e/xmqqttk7u5yr.fsf%40gitster.g
In-Reply-To: <CAN0heSpvKFKVnyve0wvcVJ3gvm5H8OggVTKpz2Se4je3iRHwCw@mail.gmail.com>

```
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.


```

## Junio C Hamano, 2024-04-11 18:11

Subject: Re: [PATCH v2 2/2] doc: git.txt-Change "--user-formats" to "--user-interfaces"
Message-ID: <xmqqpluvu5vk.fsf@gitster.g>
URL: https://gitlist.dev/e/xmqqpluvu5vk.fsf%40gitster.g
In-Reply-To: <af548abd00485e161c2e409b0b9fa80a3a061cc8.1712822221.git.gitgitgadget@gmail.com>

```
"秃头灯笼鱼 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, 2024-04-14 02:49

Subject: Re:Re: [PATCH v2 2/2] doc: git.txt-Change "--user-formats" to "--user-interfaces"
Message-ID: <1bd1d875.c81.18eda82e0cb.Coremail.ttdlyu@163.com>
URL: https://gitlist.dev/e/1bd1d875.c81.18eda82e0cb.Coremail.ttdlyu%40163.com
In-Reply-To: <xmqqpluvu5vk.fsf@gitster.g>

```
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> 写道：
>"秃头灯笼鱼 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, 2024-04-15 17:10

Subject: Re: [PATCH v2 2/2] doc: git.txt-Change "--user-formats" to "--user-interfaces"
Message-ID: <xmqqh6g2pn5f.fsf@gitster.g>
URL: https://gitlist.dev/e/xmqqh6g2pn5f.fsf%40gitster.g
In-Reply-To: <1bd1d875.c81.18eda82e0cb.Coremail.ttdlyu@163.com>

```
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.

```

## ttdlyu, 2024-04-16 06:02

Subject: Re:Re: [PATCH v2 1/2] doc: git.txt-Fix inconsistency param description
Message-ID: <2ee4f6e3.78c1.18ee57fda14.Coremail.ttdlyu@163.com>
URL: https://gitlist.dev/e/2ee4f6e3.78c1.18ee57fda14.Coremail.ttdlyu%40163.com
In-Reply-To: <CAN0heSpvKFKVnyve0wvcVJ3gvm5H8OggVTKpz2Se4je3iRHwCw@mail.gmail.com>

```

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:
>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

```