confusing GIT_DIR behavior case

I'm noob so wanted to see 'git_repo' instead of invisible '.git'. I tried GIT_DIR=git_repo after looking at

       GIT_DIR
              If the GIT_DIR environment variable is set then it
              specifies a
              path to use instead of the default .git for the base of
              the
              repository.

in the man page plus the usual mantra of 
 
       git init 
       git add .
       git commit

in many git noob docs.

But it fails like this:

       rhino$ mkdir test
       rhino$ cd test
       rhino$ export GIT_DIR=git_repo
       rhino$ git init
       Initialized empty Git repository in git_repo/
       rhino$ git add .
       fatal: This operation must be run in a work tree

I had to irc to hear that git_repo must be added to info/exclude (even though '.git' isnt in there :).

Confusingly I was able to grope up a GIT_WORK_TREE setting (I forget exactly what) that made 'git add .' work but then 'git commit' failed.

It seems to me that at least one of these options should be useful (I doubt I know enought to know which):

   1.  GIT_DIR (and --git-dir) should make git behave exactly as if git
   was 
       wired to look for $GIT_DIR rather than '.git'.  The occurence of
       the
       GIT_DIR description in the top-level man page (for 'man git')
       seems to
       suggest that this is how things work.

   2.  The above man page section should be changed, and --git-dir
   option
       description should be expanded a bit, or referred to the section
       describing GIT_DIR.

   3.  The above diagnostic should be changed.  It looks to me like its
   running
       some test to determine that its in the repo directory and then
       giving
       up, presumably because it believes it was erroneously invoked
       there.  The
       error is the first thing that shows up in the above case probably
       because
       the git_repo is the first directory in a recursive traversal
       where there is
       a problem.  If this is the case it would be a nice clue if it
       would spit out
       the name of the offending directory.

   4.  The noob docs should make some mention of this issue.

Cheers, Britton

"Britton Kerin" <bkerin@fastmail.fm> writes:

That's underdescribing things. Presense of GIT_DIR means much more than that (e.g. you are at the top-level of the repository unless you have WORK_TREE).

Which "noob docs" did you look at (and do you think other people would most likely to look at)? I think the most important description they need is not to mess with these environment variables. It might sometimes be needed to move .git away from its default place (and I haven't been in that situation yet, so you have to be more advanced than me ;-)), but if you are doing such a non-default thing, you are certainly no longer "noob".