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

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

Yaroslav Nikitenko wrote:

I do precisely the same thing.

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?

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

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

Cheers.

2021-01-02 22:12 GMT+03:00, Felipe Contreras <felipe.contreras@gmail.com>:

BTW, how do you do that in your case?

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

I noted that, thanks.

Yaroslav Nikitenko wrote:

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

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.

2021-01-03 1:02 GMT+03:00, Felipe Contreras <felipe.contreras@gmail.com>:

Thanks.

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

Yaroslav Nikitenko wrote:

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

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.

Yaroslav Nikitenko <metst13@gmail.com> writes:

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(-)