Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix the inconsistency in the description of the namespace option's parameter #1669

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Fix the inconsistency in the description of the namespace option's parameter #1669

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
28a5625
doc: git.txt-Fix inconsistency param description
ttdly Feb 9, 2024
af548ab
doc: git.txt-Change "--user-formats" to "--user-interfaces"
ttdly Mar 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
4 changes: 2 additions & 2 deletions Documentation/git.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ SYNOPSIS
'git' [-v | --version] [-h | --help] [-C <path>] [-c <name>=<value>]
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Martin Ågren wrote (reply to this):

On Thu, 11 Apr 2024 at 10:20, 秃头灯笼鱼 via GitGitGadget
<[email protected]> wrote:
>
> 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]>

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

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

Martin Ågren <[email protected]> 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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, ttdlyu wrote (reply to this):

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" <[email protected]> wrote:
>On Thu, 11 Apr 2024 at 10:20, 秃头灯笼鱼 via GitGitGadget
><[email protected]> wrote:
>>
>> 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]>
>
>> -    [--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

[--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
Expand Down Expand Up @@ -342,7 +342,7 @@ Repository, command and file interfaces
---------------------------------------
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

"秃头灯笼鱼 via GitGitGadget" <[email protected]> writes:

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I didn’t notice this document before. I will take a careful look at it later.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I didn’t notice this document before. I will take a careful look at it later.

Please reply on the list, otherwise Junio won't see your reply. (Follow the "reply to this" link in this comment to find out more.)

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I didn’t notice this document before. I will take a careful look at it later.

Please reply on the list, otherwise Junio won't see your reply. (Follow the "reply to this" link in this comment to find out more.)

Thank you for the reminder. I'm having issues with my email account today and am unable to log in using a third-party client. I will try to reply to this message tomorrow.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you have a way to import mbox files into your email account, that's another option. For example, appending /raw to https://lore.kernel.org/git/[email protected]/ (like so) will give you that mbox file with all the information your mail program should require to reply.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for your reply. I have replied to that message via Thunderbird, and I hope Junio can receive it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not yet see it here: https://lore.kernel.org/git/[email protected]/. Sometimes mails get delayed, but it could also be the very, very common issue that the Git mailing list silently drops HTML mails! So unless you have configured your Thunderbird to send plain-text-only mails, it might have fallen prey to this issue. Git has a section on configuring Thunderbird that might, or might not, be totally outdated.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, ttdlyu wrote (reply to this):

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" <[email protected]> 写道：
>"秃头灯笼鱼 via GitGitGadget" <[email protected]> writes:
>
>> 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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not yet see it here: https://lore.kernel.org/git/[email protected]/. Sometimes mails get delayed, but it could also be the very, very common issue that the Git mailing list silently drops HTML mails! So unless you have configured your Thunderbird to send plain-text-only mails, it might have fallen prey to this issue. Git has a section on configuring Thunderbird that might, or might not, be totally outdated.

It seems I've succeeded. Do I need to reply to Martin Ågren via email again?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

ttdlyu  <[email protected]> writes:

> Sorry, to be honest, I haven’t read this document carefully before, I 
> will find time to read it carefully.

Thanks.


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[]
Expand Down