Re: [PATCH v3] git: update documentation for --git-dir

From: Heba Waly <heba.waly@gmail.com>
Date: Jan 29, 2020, 12:10 UTC
Message-ID: <CACg5j26EEMYkbp4F0AoVSKE5BWwYXvxRqJSovRdzNitqbHzzqQ@mail.gmail.com>
In-Reply-To: <xmqq7e1b8jyq.fsf@gitster-ct.c.googlers.com>

On Wed, Jan 29, 2020 at 8:22 AM Junio C Hamano <gitster@pobox.com> wrote:

Show 16 quoted lines

>
> "Heba Waly via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> >  --git-dir=<path>::
> > -     Set the path to the repository. This can also be controlled by
> > -     setting the `GIT_DIR` environment variable. It can be an absolute
> > -     path or relative path to current working directory.
> > +     Set the path to the repository (".git" directory). This can also be
> > +     controlled by setting the `GIT_DIR` environment variable. It can be
> > +     an absolute path or relative path to current working directory.
> > ++
> > +Specifying the location of the ".git" directory using this
> > +option (or GIT_DIR environment variable) turns off the
>
> Consistently quote, like `GIT_DIR`, here?
>

Ok

Show 11 quoted lines

> > +repository discovery that tries to find a directory with
> > +".git" subdirectory (which is how the repository and the
> > +top-level of the working tree are discovered), and tells Git
> > +that you are at the top level of the working tree.  If you
> > +are not at the top-level directory of the working tree, you
> > +should tell Git where the top-level of the working tree is,
> > +with the --work-tree=<path> option (or GIT_WORK_TREE
>
> Likewise.  We may probably want to say `--work-tree=<path>` inside a
> bq pair, and definitely `GIT_WORK_TREE` inside a bq pair.
>

Ok

Show 10 quoted lines

> > +environment variable)
> > ++
> > +If you just want to run git as if it was started in <path> then use
> > +git -C.
>
> This is the best part of this patch, I would think.  But you said
> <path> in the "if" part of this "if--then", so (unless your Git
> magically can read users' minds some magic), I'd expect to see the
> same <path> to appear somewhere in the "then" part.
>

By <path> here I'm referring to the path parameter of git --git-dir=<path>. And by mentioning `git -C` without any parameters, my intention is to point the user to scroll up and read about git -C and its parameters. Given that was confusing to you, I don't mind stating the command in its simplest form as you suggested: `git -C <path>`

>         If you just want to run git as if it was started in `<path>`
>         then use `git -C <path>`.
>
> perhaps?

Thanks, Heba