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

From: Martin Ågren <martin.agren@gmail.com>
Date: Apr 11, 2024, 10:39 UTC
Message-ID: <CAN0heSpvKFKVnyve0wvcVJ3gvm5H8OggVTKpz2Se4je3iRHwCw@mail.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:

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