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

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