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

From: Carlos Martín Nieto <cmn@elego.de>
Date: Dec 1, 2011, 14:30 UTC
Message-ID: <20111201143016.GC2386@beez.lab.cmartin.tk>
In-Reply-To: <CAEUMa-fhqS-dJUePznZrEsKVSMDiAs=-JX93XTXZEm71Oix-1Q@mail.gmail.com>

On Wed, Nov 30, 2011 at 11:13:20AM -0800, John Twilley wrote:

Show 26 quoted lines

> On Wed, Nov 30, 2011 at 10:22, Carlos Martín Nieto <cmn@elego.de> wrote:
> > 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.

And as Junio said, git devs have never considered the case where you want to run git from a directory, but have git look for the worktree + repo in a different place. Since what you want to do is solved trivially by cd'ing in a subshell "(cd blah && git status)" it's not surprising that this hasn't come up.

Show 30 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.

You hardly ever need to use git directly on a bare repo, but when you do, you can just it from inside the repo, but most of the time git expects to be run from the place where the repo+worktree combination is to be found. Anything else is a low-level configuration and is just not expected to be used by people who aren't familiar with git's usage of "worktree".

Show 19 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.

It's not just about it being a critical feature. Yes it would break many scripts, but what you want to do is meant to be done with a subshell and I fail to see why git should go out of its way to support such a usercase.

Show 13 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.

The documentation now thankfully doesn't talk about working copy anymore, so it should be fairly consistent. The gitglossary definition of worktree should also explain what a worktree is.

Show 14 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.

The reason for --work-tree (and the earlier GIT_WORKTREE) is to allow you to temporarily set the worktree somewhere else. It's meant to tell git to pretend $PWD is something else.

Show 5 quoted lines

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

This subshell method is exactly how everyone's always written this kind of thing, and the way that you're supposed to (and I don't mean for git, I mean for any tool). Adding the option explicitly to git would introduce an further potential source of bugs and is unnecessary.

> 
> >> wish to refer to the current directory or some other directory

for

Show 16 quoted lines

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

That would connect unrelated code, I doubt it's reasonable.

cmn