core.worktree bug

According to git-config(1) 

       core.worktree
           Set the path to the working tree. The value will not be used in combination with repositories found automatically in a
           .git directory (i.e. $GIT_DIR is not set). This can be overridden by the GIT_WORK_TREE environment variable and the
           --work-tree command line option. It can be a absolute path or relative path to the directory specified by --git-dir or
           GIT_DIR. Note: If --git-dir or GIT_DIR are specified but none of --work-tree, GIT_WORK_TREE and core.worktree is
           specified, the current working directory is regarded as the top directory of your working tree.

this setting is not used if GIT_DIR is set. But when I try it out 

$ mkdir r1
$ mkdir r2
$ cd r2
$ git init
Initialized empty Git repository in /home/me/tmp/r2/.git/
$ date >f
$ git add f
$ git commit -m "f"
 f
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 f
$ git status
# On branch master
nothing to commit (working directory clean)

=> Nothing interesting here. It comes here:

$ git config core.worktree $(cd ../r1;pwd) $ git status # On branch master # Changed but not updated: # (use "git add/rm <file>..." to update what will be committed) # (use "git checkout -- <file>..." to discard changes in working directory) # # deleted: f # no changes added to commit (use "git add" and/or "git commit -a")

=> Seems the config is actually honored even though GIT_DIR is not set.

Bisect tells me 4f38f6b5bafb1f7f85c7b54d0bb0a0e977cd947c broke it. My main point is that I am implementing this in JGit so I want the same behaviour. Question: Should we try to fix this in git so it matches the documentation or fix the documentation to match behaviour.

The breakage appeared over a year ago and no one has complained.

-- robin

My bisection script:

#!/bin/bash

test_description="CEILING"

. ./test-lib.sh

test_expect_success \
    "ceiling" \
    "
     rm -rf r1 r2 &&
     mkdir r1 r2 &&
     (cd r2 &&
     git init &&
     date >f &&
     git add f &&
echo ADD &&
     git commit -m f &&
echo COMMIT &&
     git diff --exit-code f && 
echo DIFF &&
     git config core.worktree \$(cd ../r1/..;pwd) &&
echo CONFIG &&
     (unset GIT_DIR;git diff --exit-code -- f) &&
echo DIFF
     )
     "

test_don