bug: setting GIT_DIR to $(git rev-parse --git-dir) changes behavior

bug: setting GIT_DIR to $(git rev-parse --git-dir) changes behavior

[Martin Nicolay]

Thank you for filling out a Git bug report!
Please answer the following questions to help us understand your issue.

What did you do before the bug happened? (Steps to reproduce your issue)

$ env | grep GIT
$ git --version
git version 2.30.1
$ git init t
Initialized empty Git repository in /tmp/t/.git/
$ mkdir t/foo
$ cd t/foo
$ git rev-parse --show-toplevel
/tmp/t
$ GIT_DIR=$(git rev-parse --git-dir) git rev-parse --show-toplevel
/tmp/t/foo
$ git rev-parse --git-dir
/tmp/t/.git

What did you expect to happen? (Expected behavior)

"git rev-parse --show-toplevel" should be the same in both invocation.

What happened instead? (Actual behavior)

"git rev-parse --show-toplevel" shows the current working directory if GIT_DIR is set.

What's different between what you expected and what actually happened?

Setting GIT_DIR to $(git rev-parse --git-dir) should not change anything.

Anything else you want to add:

Please review the rest of the bug report below.
You can delete any lines you don't wish to share.


[System Info]
git version:
git version 2.30.1
cpu: x86_64
no commit associated with this build
sizeof-long: 8
sizeof-size_t: 8
shell-path: /bin/sh
uname: Linux 5.3.18-22-default #1 SMP Wed Jun 3 12:16:43 UTC 2020 (720aeba) x86_64
compiler info: gnuc: 9.1
libc info: glibc: 2.26
$SHELL (typically, interactive shell): /opt/local/bin/bash


[Enabled Hooks]

Re: bug: setting GIT_DIR to $(git rev-parse --git-dir) changes behavior

[Junio C Hamano]

Martin Nicolay <m.nicolay@osm-ag.de> writes:

> What did you do before the bug happened? (Steps to reproduce your issue)

Thanks for concise and clear descriptions for us to learn everything
you did.  I wish all the reports were written like this one.

> $ env | grep GIT
> $ git --version
> git version 2.30.1

Showed there is no funny environment variable involved and the
version.  Good.

> $ git init t
> Initialized empty Git repository in /tmp/t/.git/
> $ mkdir t/foo
> $ cd t/foo
> $ git rev-parse --show-toplevel
> /tmp/t

The root of the working tree is at /tmp/t/, the repository at
/tmp/t/.git/, and you are in the foo/ subdirectory.  When you ask
"where is the top level of the working tree in this state, because
you do not have GIT_DIR or GIT_WORK_TREE environment variables, you
are asking Git to "discover" both the .git/ directory and the top of
the working tree, by starting at the current directory,
i.e. /tmp/t/foo, which is where you are.

First Git looks to see /tmp/t/foo/.git/ exists and is a repository;
it is not.  So it goes one level up and does so for /tmp/t/.git/ and
it finds that it is the repository.  The directory in which the
repository was discovered is the top of the working tree, hence you
get /tmp/t back.

> $ GIT_DIR=$(git rev-parse --git-dir) git rev-parse --show-toplevel
> /tmp/t/foo

When you give the GIT_DIR environment variable, you are telling Git
not to perform the repository discovery, AND also you are telling
Git that you are at the top-level of the working tree.  So this is
quite expected (it is a feature that is used by folks who want to
have their repository data in a distant and unrelated directory from
their working tree).

In other words, this is 100% expected behaviour.

If you want to also tell Git where the top-level of your working
tree is, you can export GIT_WORK_TREE at the same time.

    Side note: the latter environment variable was invented for this
    exact reason.  Back when only GIT_DIR existed as a way to tell
    Git where the distant repository is, those who wanted to use the
    "split" layout had to stay at the top-level of their working
    tree, and they got tired of not being able to work from a
    subdirectory.  GIT_WORK_TREE was introduced to tell where the
    top-level is separately from GIT_DIR when GIT_DIR environment
    variable is in use.

> $ git rev-parse --git-dir
> /tmp/t/.git

Re: bug: setting GIT_DIR to $(git rev-parse --git-dir) changes behavior

[Martin Nicolay]

On Thursday 2021-02-25 19:29, Junio C Hamano wrote:
> The root of the working tree is at /tmp/t/, the repository at
> /tmp/t/.git/, and you are in the foo/ subdirectory.  When you ask
> "where is the top level of the working tree in this state, because
> you do not have GIT_DIR or GIT_WORK_TREE environment variables, you
> are asking Git to "discover" both the .git/ directory and the top of
> the working tree, by starting at the current directory,
> i.e. /tmp/t/foo, which is where you are.

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

Thanks
Martin

Re: bug: setting GIT_DIR to $(git rev-parse --git-dir) changes behavior

[Junio C Hamano]

Martin Nicolay <m.nicolay@osm-ag.de> writes:

> On Thursday 2021-02-25 19:29, Junio C Hamano wrote:
>> The root of the working tree is at /tmp/t/, the repository at
>> /tmp/t/.git/, and you are in the foo/ subdirectory.  When you ask
>> "where is the top level of the working tree in this state, because
>> you do not have GIT_DIR or GIT_WORK_TREE environment variables, you
>> are asking Git to "discover" both the .git/ directory and the top of
>> the working tree, by starting at the current directory,
>> i.e. /tmp/t/foo, which is where you are.
>
> *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.

No need to apologize, and thanks for reporting.

Re: bug: setting GIT_DIR to $(git rev-parse --git-dir) changes behavior

[Martin Nicolay]

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