[DOC] more explanation about --git-dir and --work-tree options

Hi,

I find these two options bring me surprise:

   git init $HOME
   git add ~/.vimrc ~/.gvimrc ~/.vim
   cd $HOME/work/xxx
   ....do some work, then change ~/.vimrc without changing
       working directory
   git --git-dir $HOME/.git status

I use --git-dir because I have another .git in $HOME/work/xxx, the last command surprises me much, it tells me .vim* are all deleted!

After checking the code, I realize git thinks the current working directory as top directory of the working tree if --git-dir is specified without --work-tree option.

I try to modify this behaviour so that git thinks the parent directory of .git/ as the top directory of my working tree, but later I find many tests are broken and I realize many scripts and many(??) git users would like probably to work in the top directory of their working trees providing only one extra --git-dir option with separated git repositories without touching .git/config and environment variables, so I decide to give up my patch and accustom myself to the new lovely core.worktree configuration variable.

And here is my supplement to the documentation.

---
 Documentation/config.txt |    9 ++++++++-
 Documentation/git.txt    |   10 ++++++++--
 2 files changed, 16 insertions(+), 3 deletions(-)

Liu Yubao venit, vidit, dixit 28.04.2008 22:09:

Yes, I found this surprising at first, too. And I noticed later on why things are the way they are, just as you did. :)

More doc on this is certainly helpful.

"an absolute path or a relative...""

I would probably interchange "is" and "are" here.

Same changes in the following.

I often find myself wanting to operate on a repo without cd'ing to it. While

( cd repo && git command args)

is certainly an option I find the following shell functions helpful:

alias g=git
function gg ()
{
   local _gg="$1";
   shift;
   git --git-dir="${_gg}/.git" --work-tree="${_gg}" "$@"
}

That way,

gg repo command args

runs git in a different location while

g command args

works as usual (and is shorter).

Now I'm just waiting for the experts to tell me that cd'ing to repo is completely different from specifying --git-dir and --work-tree, and that either way is completely wrong. (I'm still stupid and ugly, but I want to become clever and smart.) ;)

Michael

Quoting Liu Yubao <yubao.liu@gmail.com>:

The behavior at the end user level was outlined earlier in the message http://marc.info/?l=git&m=120390208721287&w=2

A later message http://marc.info/?l=git&m=120445414611494&w=2 proposed an implementation change and described how the various pieces appear to programmers but it was lost when the code was scrapped.

I think it is a good idea to add a documentation like this to at least describe the behavior visible by the end users.