From: Martin Nicolay <m.nicolay@osm-ag.de>
Date: Mon, 01 Mar 2021 08:08:31 GMT
Subject: Re: bug: setting GIT_DIR to $(git rev-parse --git-dir) changes behavior
Message-ID: <alpine.LSU.2.20.2103010847410.20742@cpza.bfz-tzou.qr>

On Saturday 2021-02-27 22:06, Junio C Hamano wrote:
> Martin Nicolay <m.nicolay@osm-ag.de> writes:
>> *facepalm* The part about GIT_DIR setting the work-tree in addition to
>>  the repository I hadn't read. How embarrasing.
>>
>> I apoligize for my bad reading skills and wasting you time.
>
> We would love to hear observations on which part of the
> documentation was misleading and suggestions on how to make it
> harder to misinterpret it.

There are multiple explanations regarding $DIR_DIR or --git-dir.

From git(1) two parts:

1)
        --git-dir=<path>
            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 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)

2)
        GIT_DIR
            If the GIT_DIR environment variable is set then it specifies a path
            to use instead of the default .git for the base of the repository.
            The --git-dir command-line option also sets this value.

The first part mentions the dual effect of setting git-dir, the second 
not so.

As I had used GIT_DIR described in the second part, I feel vindicated ;-)
Hooray, instead of a software-bug I've found a documentation-bug.

My suggestion is to ammend the first sentence to something like "If the 
GIT_DIR environment variable is set then it specifies a path to use 
instead of the default .git for the base of the repository and also the 
top-level directory of the working tree."