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

From: Heba Waly <heba.waly@gmail.com>
Date: Jan 27, 2020, 02:22 UTC
Message-ID: <CACg5j260t0Q1=5i_The5ARN0qRTDKiwmH-KYN5KqHye+Y_9gig@mail.gmail.com>
In-Reply-To: <xmqq1rrq65ed.fsf@gitster-ct.c.googlers.com>

On Thu, Jan 23, 2020 at 7:41 PM Junio C Hamano <gitster@pobox.com> wrote:

Show 11 quoted lines

>
> "Heba Waly via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> It is not "not be able to figure out".  Specifying GIT_DIR (either
> with environment or the --git-dir option) tells Git that the $cwd is
> the top of the working tree unless otherwise specified (e.g. with
> GIT_WORK_TREE environment).  If you have to say something, saying
> "When GIT_DIR is specified, the usual repository discovery is
> skipped and the current directory is taken as the top level of the
> working tree unless otherwise speciffied" is probably OK.
>

Ok, I didn't understand it as intentional before, will update that.

Show 6 quoted lines

> > +     Set the path to the repository (i.e. the .git folder). This can also be
>
> I suspect (i.e. ".git") may be clear enough, but if you must, say
> ".git directory", not ".git folder", as you mention "current working
> directory" later.
>

Fair enough.

Show 7 quoted lines

> > +     It's preferrable to set --work-tree=<path> as well when setting
> > +     --git-dir to make sure Git will run your command across the correct
> > +     work tree.
>
> It does not help the readers that much to say "It's preferrable"
> without saying what negative implications there are if they don't
> use it, or what positive effect they would observe if they do.

I agree, I couldn't find enough information on the matter to elaborate more.

Show 15 quoted lines

> If I were writing it, I'd drop "Note that..." and rewrite the three
> lines more like...
>
>         Specifying the location of the ".git" directory using this
>         option (or GIT_DIR environment variable) turns off the
>         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
>         environment variable)
>
> perhaps.

That helped me understand it better also, will use this, thanks.

Show 9 quoted lines

>
> >  --work-tree=<path>::
> >       Set the path to the working tree. It can be an absolute path
> >       or a path relative to the current working directory.
> >
> > base-commit: 232378479ee6c66206d47a9be175e3a39682aea6
>
> I do not know if GGG users have control over this, but I'd prefer to
> see a "-- " divider before this "base-commit: ..." footer material.

No I don't think I can change this one.

Thanks, Heba