# git-dir requires work-tree; documentation improvements for working directory 7 messages from 2021-01-02 to 2021-01-04. Participants: Yaroslav Nikitenko, Felipe Contreras, Junio C Hamano. Thread: https://gitlist.dev/t/54918 ## Yaroslav Nikitenko, 2021-01-02 14:40 Subject: git-dir requires work-tree; documentation improvements for working directory Message-ID: URL: https://gitlist.dev/e/CA%2BRLzGCtp2T%3D8DG74geBs67X5vUvhwRP4FMZ6MJv%2BE%2BPj%3DYbWw%40mail.gmail.com ``` 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 ``` ## Felipe Contreras, 2021-01-02 19:12 Subject: RE: git-dir requires work-tree; documentation improvements for working directory Message-ID: <5ff0c58422038_90dc208ea@natae.notmuch> URL: https://gitlist.dev/e/5ff0c58422038_90dc208ea%40natae.notmuch In-Reply-To: ``` 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 ``` ## Yaroslav Nikitenko, 2021-01-02 19:44 Subject: Re: git-dir requires work-tree; documentation improvements for working directory Message-ID: URL: https://gitlist.dev/e/CA%2BRLzGArUrxC-Kbng3qGpRZUrZXKZj3zD3Hcut%3DXrUY-i-eYAw%40mail.gmail.com In-Reply-To: <5ff0c58422038_90dc208ea@natae.notmuch> ``` 2021-01-02 22:12 GMT+03:00, 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). 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 > ``` ## Felipe Contreras, 2021-01-02 22:02 Subject: Re: git-dir requires work-tree; documentation improvements for working directory Message-ID: <5ff0ed59489bd_a76d2082f@natae.notmuch> URL: https://gitlist.dev/e/5ff0ed59489bd_a76d2082f%40natae.notmuch In-Reply-To: ``` Yaroslav Nikitenko wrote: > 2021-01-02 22:12 GMT+03:00, 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). > > 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 ``` ## Yaroslav Nikitenko, 2021-01-03 09:12 Subject: Re: git-dir requires work-tree; documentation improvements for working directory Message-ID: URL: https://gitlist.dev/e/CA%2BRLzGCfqNdup1cmz3W4iBzbsxe9SD7E%2BJu4svNFvhe6ohJqjA%40mail.gmail.com In-Reply-To: <5ff0ed59489bd_a76d2082f@natae.notmuch> ``` 2021-01-03 1:02 GMT+03:00, Felipe Contreras : > Yaroslav Nikitenko wrote: >> 2021-01-02 22:12 GMT+03:00, 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). >> >> 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 ``` ## Felipe Contreras, 2021-01-03 11:57 Subject: Re: git-dir requires work-tree; documentation improvements for working directory Message-ID: <5ff1b137e3eab_1c01e208a5@natae.notmuch> URL: https://gitlist.dev/e/5ff1b137e3eab_1c01e208a5%40natae.notmuch In-Reply-To: ``` 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 ``` ## Junio C Hamano, 2021-01-04 23:47 Subject: Re: git-dir requires work-tree; documentation improvements for working directory Message-ID: URL: https://gitlist.dev/e/xmqqmtxo464l.fsf%40gitster.c.googlers.com In-Reply-To: ``` Yaroslav Nikitenko 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= 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= 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=` 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=` option (or `GIT_WORK_TREE` -environment variable) +environment variable). + If you just want to run git as if it was started in `` then use `git -C `. ```