git-dir requires work-tree; documentation improvements for working directory

git-dir requires work-tree; documentation improvements for working directory

[Yaroslav Nikitenko]

Dear git users and maintainers,

I use git to manage my dotfiles with this command:

    git --git-dir=/home/yaroslav/.cfg/ --work-tree=/home/yaroslav

When reading documentation, I noticed two issues.

1) The command doesn't work without --work-tree (even from the top
level directory, which is my home directory).

    [~]$ git --git-dir=/home/yaroslav/.cfg/ status
    fatal: this operation must be run in a work tree

I don't have any configuration or environment variables for work-tree
(as warned here,
https://lore.kernel.org/git/CAPig+cRqkzPzNX8UN4OcgEOOKbtZRLCjNNiZsOVkGBy0pvsEkQ@mail.gmail.com/).

In `man git` for git-dir it says "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" ("If"), the same is quoted in a recent thread
(https://lore.kernel.org/git/88D2A179-806F-4321-828A-359692E646B1@gmail.com/)

I'm using git version 2.30.0 on the most recent Arch Linux.

2) In the man documentation for git > git-dir it's written
"It can be an absolute path or relative path to current working directory."
I think this can be confused with work-tree. I suggest removing the
word 'working' (and probably add an article 'the' before the
'current', but I'm not a native speaker).

I can see that the expression "working directory" is used throughout
the man page of git, and it is used ambiguously (sometimes it means
the current directory, sometimes git working directory).

I don't subscribe to the mailing list but hope that I'll receive the replies.

Thank you and Happy New Year!

Best regards,
Yaroslav Nikitenko

RE: git-dir requires work-tree; documentation improvements for working directory

[Felipe Contreras]

Yaroslav Nikitenko wrote:
> I use git to manage my dotfiles with this command:
> 
>     git --git-dir=/home/yaroslav/.cfg/ --work-tree=/home/yaroslav

I do precisely the same thing.

> When reading documentation, I noticed two issues.
> 
> 1) The command doesn't work without --work-tree (even from the top
> level directory, which is my home directory).
> 
>     [~]$ git --git-dir=/home/yaroslav/.cfg/ status
>     fatal: this operation must be run in a work tree

That's weird. It works fine here (although I don't see why I would want
that).

If you remove all your configuration does it still fail?

> 2) In the man documentation for git > git-dir it's written
> "It can be an absolute path or relative path to current working directory."
> I think this can be confused with work-tree. I suggest removing the
> word 'working' (and probably add an article 'the' before the
> 'current', but I'm not a native speaker).

Yes, the article is missing, as for the rest I have no opinion.

> I don't subscribe to the mailing list but hope that I'll receive the replies.

Don't worry. The git mailing list doesn't munge the Reply-To header, so
any decent MUA will keep you in Cc.

Cheers.

-- 
Felipe Contreras

Re: git-dir requires work-tree; documentation improvements for working directory

[Yaroslav Nikitenko]

2021-01-02 22:12 GMT+03:00, Felipe Contreras <felipe.contreras@gmail.com>:
> Yaroslav Nikitenko wrote:
>> I use git to manage my dotfiles with this command:
>>
>>     git --git-dir=/home/yaroslav/.cfg/ --work-tree=/home/yaroslav
>
> I do precisely the same thing.
>
>> When reading documentation, I noticed two issues.
>>
>> 1) The command doesn't work without --work-tree (even from the top
>> level directory, which is my home directory).
>>
>>     [~]$ git --git-dir=/home/yaroslav/.cfg/ status
>>     fatal: this operation must be run in a work tree
>
> That's weird. It works fine here (although I don't see why I would want
> that).

BTW, how do you do that in your case?

> If you remove all your configuration does it still fail?

It starts to work when I remove my .cfg/config. I've no idea why it
happens. Here is its contents:

$ more .cfg/config
[core]
	repositoryformatversion = 0
	filemode = true
	bare = true
[remote "origin"]
	url = me@myserver:my_working_path
[branch "master"]
	remote = origin
	merge = refs/heads/master


>> 2) In the man documentation for git > git-dir it's written
>> "It can be an absolute path or relative path to current working
>> directory."
>> I think this can be confused with work-tree. I suggest removing the
>> word 'working' (and probably add an article 'the' before the
>> 'current', but I'm not a native speaker).
>
> Yes, the article is missing, as for the rest I have no opinion.
>
>> I don't subscribe to the mailing list but hope that I'll receive the
>> replies.
>
> Don't worry. The git mailing list doesn't munge the Reply-To header, so
> any decent MUA will keep you in Cc.

I noted that, thanks.

> Cheers.
>
> --
> Felipe Contreras
>

Re: git-dir requires work-tree; documentation improvements for working directory

[Felipe Contreras]

Yaroslav Nikitenko wrote:
> 2021-01-02 22:12 GMT+03:00, Felipe Contreras <felipe.contreras@gmail.com>:
> > Yaroslav Nikitenko wrote:
> >> I use git to manage my dotfiles with this command:
> >>
> >>     git --git-dir=/home/yaroslav/.cfg/ --work-tree=/home/yaroslav
> >
> > I do precisely the same thing.
> >
> >> When reading documentation, I noticed two issues.
> >>
> >> 1) The command doesn't work without --work-tree (even from the top
> >> level directory, which is my home directory).
> >>
> >>     [~]$ git --git-dir=/home/yaroslav/.cfg/ status
> >>     fatal: this operation must be run in a work tree
> >
> > That's weird. It works fine here (although I don't see why I would want
> > that).
> 
> BTW, how do you do that in your case?

I have an alias:

  alias config='git --git-dir=$HOME/.config/dotfiles/.git/ --work-tree=$HOME'

So, when I'm in my $HOME, I can do:

  config status

> > If you remove all your configuration does it still fail?
> 
> It starts to work when I remove my .cfg/config. I've no idea why it
> happens. Here is its contents:
> 
> $ more .cfg/config
> [core]
> 	repositoryformatversion = 0
> 	filemode = true
> 	bare = true

That's the difference: my core.bare is false.

I do have a checked out work-tree because that's the only way I could
get some commands to work, for example `git rebase`, even though I don't
use that work-tree.

I'm not sure if it makes sense to not assume '.' is the work-tree when
'core.bare=true', but I think it does make sense, so maybe just turn
that off.

Cheers.

-- 
Felipe Contreras

Re: git-dir requires work-tree; documentation improvements for working directory

[Yaroslav Nikitenko]

2021-01-03 1:02 GMT+03:00, Felipe Contreras <felipe.contreras@gmail.com>:
> Yaroslav Nikitenko wrote:
>> 2021-01-02 22:12 GMT+03:00, Felipe Contreras
>> <felipe.contreras@gmail.com>:
>> > Yaroslav Nikitenko wrote:
>> >> I use git to manage my dotfiles with this command:
>> >>
>> >>     git --git-dir=/home/yaroslav/.cfg/ --work-tree=/home/yaroslav
>> >
>> > I do precisely the same thing.
>> >
>> >> When reading documentation, I noticed two issues.
>> >>
>> >> 1) The command doesn't work without --work-tree (even from the top
>> >> level directory, which is my home directory).
>> >>
>> >>     [~]$ git --git-dir=/home/yaroslav/.cfg/ status
>> >>     fatal: this operation must be run in a work tree
>> >
>> > That's weird. It works fine here (although I don't see why I would want
>> > that).
>>
>> BTW, how do you do that in your case?
>
> I have an alias:
>
>   alias config='git --git-dir=$HOME/.config/dotfiles/.git/
> --work-tree=$HOME'
>
> So, when I'm in my $HOME, I can do:
>
>   config status

Thanks.

>> > If you remove all your configuration does it still fail?
>>
>> It starts to work when I remove my .cfg/config. I've no idea why it
>> happens. Here is its contents:
>>
>> $ more .cfg/config
>> [core]
>> 	repositoryformatversion = 0
>> 	filemode = true
>> 	bare = true
>
> That's the difference: my core.bare is false.
>
> I do have a checked out work-tree because that's the only way I could
> get some commands to work, for example `git rebase`, even though I don't
> use that work-tree.
>
> I'm not sure if it makes sense to not assume '.' is the work-tree when
> 'core.bare=true', but I think it does make sense, so maybe just turn
> that off.
>
> Cheers.
>
> --
> Felipe Contreras
>

Thanks for the suggestion. I'd rather not change my config at the
moment. It's not difficult to provide work-tree in the alias.

However, I think that this is a bug in the implementation or the
documentation. It's not highlighted anywhere that the repository must
be non-bare for git-dir to work without explicit work-tree (an
opposite is stated in general).

Should I write a letter with [BUG] in its header for that to be noticed?
I'm surprised why there is no issue tracker for git.

Cheers,
Yaroslav Nikitenko

Re: git-dir requires work-tree; documentation improvements for working directory

[Felipe Contreras]

Yaroslav Nikitenko wrote:
> However, I think that this is a bug in the implementation or the
> documentation. It's not highlighted anywhere that the repository must
> be non-bare for git-dir to work without explicit work-tree (an
> opposite is stated in general).

core.bare=true means no work-tree, so to me that behavior follows from
the documentation. But others might disagree.

> Should I write a letter with [BUG] in its header for that to be noticed?

The mailing list is a little more quite than usual, probably due to the
holidays.

If nobody else responds in a week, try again.

Cheers.

-- 
Felipe Contreras

Re: git-dir requires work-tree; documentation improvements for working directory

[Junio C Hamano]

Yaroslav Nikitenko <metst13@gmail.com> writes:

> It starts to work when I remove my .cfg/config. I've no idea why it
> happens. Here is its contents:
>
> $ more .cfg/config
> [core]
> 	repositoryformatversion = 0
> 	filemode = true
> 	bare = true

As Felipe notes downthread, with "core.bare=true", the repository is
telling Git that it does not have a worktree.  The "assume that $CWD
is the top of the worktree" default would have no room to kick in.

With --worktree=<there> option or GIT_WORK_TREE environment
variable, you can tell Git to pretend that there is a worktree there
at the specified location.  Or perhaps "git -c core.bare=false", you
may be able to force the "assume that $CWD is the top of the worktree"
default to kick in.

"git help git" has this in --git-dir=<path>

    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)

but apparently the description forgets that there are repositories
with core.bare explicitly set to true.  There is a room for doc
improvement here.

Perhaps something like this?

 Documentation/git.txt | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git c/Documentation/git.txt w/Documentation/git.txt
index c463b937a8..6f8225e3ef 100644
--- c/Documentation/git.txt
+++ w/Documentation/git.txt
@@ -118,12 +118,15 @@ 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,
+top-level of the working tree are discovered), and if the
+repository has a working tree, i.e. `core.bare` is `false`,
+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, or
+if `core.bare` is set to `true` and you are trying to pretend
+there is a working tree associated with the repository, you
+can tell Git where the top-level of the working tree is,
 with the `--work-tree=<path>` option (or `GIT_WORK_TREE`
-environment variable)
+environment variable).
 +
 If you just want to run git as if it was started in `<path>` then use
 `git -C <path>`.