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

2021-01-02 22:12 GMT+03:00, Felipe Contreras [off-list ref]:

Yaroslav Nikitenko wrote:

quoted

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.

quoted

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

quoted

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.

quoted

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

Yaroslav Nikitenko wrote:

2021-01-02 22:12 GMT+03:00, Felipe Contreras [off-list ref]:

quoted

Yaroslav Nikitenko wrote:

quoted

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.

quoted

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

quoted

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

2021-01-03 1:02 GMT+03:00, Felipe Contreras [off-list ref]:

Yaroslav Nikitenko wrote:

quoted

2021-01-02 22:12 GMT+03:00, Felipe Contreras
[off-list ref]:

quoted

Yaroslav Nikitenko wrote:

quoted

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.

quoted

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.

quoted

quoted

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

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

Yaroslav Nikitenko [off-list ref] 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>`.