Re: BUG: "--work-tree blah" does not imply "--git-dir blah/.git" or fix misleading error message

From: John Twilley <mathuin@gmail.com>
Date: Nov 30, 2011, 19:13 UTC
Message-ID: <CAEUMa-fhqS-dJUePznZrEsKVSMDiAs=-JX93XTXZEm71Oix-1Q@mail.gmail.com>
In-Reply-To: <20111130182230.GC12096@centaur.lab.cmartin.tk>

On Wed, Nov 30, 2011 at 10:22, Carlos Martín Nieto <cmn@elego.de> wrote:

Show 19 quoted lines

> On Wed, Nov 30, 2011 at 09:43:08AM -0800, John Twilley wrote:
>> Today someone asked me if there was a way to run git against a
>> directory other than the current directory.  I looked at the output of
>> --help and ran this:
>>
>> $ git --work-tree blah status
>>
>> I got the following output:
>>
>> fatal: Not a git repository (or any parent up to mount parent /home)
>> Stopping at filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not set).
>>
>> I mistakenly thought the error message meant that blah was not a git
>> repository.  What it meant was that there was no .git in the current
>> directory or any parent directory up to /home.
>
> Yes, git looks at the current directory and .git/ to see if there's a
> git repository there. This is what happens unless you tell git to look
> for it somewhere else.

This makes perfect sense, because nearly every time I run git commands, I am somewhere within the working tree. The point of my post was that I was using --work-tree to tell git to look for the git repository somewhere else (the root of the specified working tree) which is not what git expected.

Show 18 quoted lines

>> This command worked as expected:
>>
>> $ git --work-tree blah --git-dir blah/.git status
>>
>> The documentation is somewhat fuzzy about what constitutes a git
>> repository.  The gittutorial describes the git repository as .git when
>> talking about "git init" while the Git User's Manual describes the git
>> repository as the working tree and the special top-level directory
>> named .git when talking about "git clone".
>
> A git repository is what's under .git/ (or in foo.git/ for bare
> repos). Non-bare repositories have a working tree associated with
> them, which by default lives just above the repository, because it'd
> be silly to have it somewhere else by default. Often you can think of
> both as the repository, as they're both. When you tell git to look for
> the worktree somewhere else, you're only overriding that particular
> variable, as git expects to be run from the repository (or just above,
> in the worktree).

And it's exactly this issue -- that sometimes the repository is just the git directory, and sometimes the repository is the working tree which contains the git directory at its root -- that caused the confusion and unexpected behavior. If I were to use a bare repository directly (something I've never done), I guess I might use --git-dir since the repository may not be named .git but instead something like proj.git. When I accessed a repository from outside its working tree, I expected --work-tree to cover the whole shebang. Obviously this discussion is exposing my relatively limited experience with git, but these assumptions do not seem unreasonable on their face.

Show 11 quoted lines

>> It's clear (to me at least) that --work-tree should be used to
>> identify the root of the working tree when not inside the working
>> tree.  I expected that the git directory would be automatically set to
>> .git in the root of the working tree, as that would match the
>> documentation.  Instead, the current directory and its parents were
>> checked -- which could provide dangerously misleading information to
>> the user.
>
> What part of the documentation exactly? --work-tree tells git to look
> for the working tree somewhere else. This option exists in order to
> support a multiple-workdir workflow.

What you mention above was what I was thinking about when I mentioned the possibility of this being a critical and significant feature. If it is important to support a workflow with one git directory and multiple working trees, and that case is more common/important than the one I experienced, then changing the behavior of --git-dir is obviously not the right thing to do.

Show 7 quoted lines

>> I think that one of two things should be done:  either the --git-dir
>> default should be changed when the --work-tree option is set, or the
>> error message cited above should be changed to explicitly identify the
>> directory being tested as a potential git repository.  I personally
>
> Git does tell you explicitly, but only when you specify a gitdir (via
> GIT_DIR or --git-dir), otherwise it looks at the current directory.

This is misleading if you don't know that the specification of a working tree does not also implicitly specify a git directory. Whether that lack of knowledge is the user's problem or the software/documentation's problem is a separate question.

Show 9 quoted lines

>> believe the first option is superior because it fulfills the
>> expectations of average users (folks who read git's documentation
>> instead of its source code) while permitting flexibility to those who
>
> It's not likely that it will get changed because that would break
> backwards-compatability in a very big way. If your concern is for
> "average user", she shouldn't be using that option, but changing to
> that directory instead. If you want your working tree to be ./foo/ and
> your gitdir to be ./foo/.git, why don't you just cd to ./foo/?

From that perspective, why have --work-tree at all? Without that option, either the git directory is in the root of your current working tree, or it's not -- in which case --git-dir is all you need. If you're going to keep the option, it's helpful to provide the diagnostic output. My suggestion would be more compelling if I could provide a valid use case, but all I can come up with off the top of my head are scripts and something like "(cd $worktree && git status)" would probably work fine.

Show 13 quoted lines

>> wish to refer to the current directory or some other directory for
>> their --git-dir value.  If the current behavior is somehow not a bug
>> but instead a critical and significant feature which if changed would
>> cause more harm than good, please consider the second option.
>
> You get two different messages depending on how git is looking for the
> repository. The message you mentioned gets printed when git tries to
> find it automatically. A "fatal: Not a git repository: '/tmp'" gets
> printed if you've told git to look for it in a specific place. The
> information is already there, though I guess you do have to know about
> the difference. Adding the current directory to the "default" message
> probably wouldn't hurt, as it's unlikely that a script is parsing
> that, and might be useful.

Fewer scripts would be broken if the additional output is only displayed when --work-tree is used, but that might be too special-case for this situation.

>   cmn

Jack. -- mathuin at gmail dot com