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

From: Liu Yubao <yubao.liu@gmail.com>
Date: Apr 28, 2008, 20:09 UTC
Message-ID: <48162EF0.6050705@gmail.com>

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(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 7a24f6e..307e089 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -234,7 +234,14 @@ core.worktree::
 	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.
+	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.
+
 
 core.logAllRefUpdates::
 	Enable the reflog. Updates to a ref <ref> is logged to the file
diff --git a/Documentation/git.txt b/Documentation/git.txt
index a070e07..5b41e16 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -143,7 +143,8 @@ help ...'.
 
 --git-dir=<path>::
 	Set the path to the repository. This can also be controlled by
-	setting the GIT_DIR environment variable.
+	setting the GIT_DIR environment variable. It can be an absolute
+	path or relative path to current working directory.
 
 --work-tree=<path>::
 	Set the path to the working tree.  The value will not be
@@ -151,7 +152,12 @@ help ...'.
 	a .git directory (i.e. $GIT_DIR is not set).
 	This can also be controlled by setting the GIT_WORK_TREE
 	environment variable and the core.worktree configuration
-	variable.
+	variable. It can be an 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.
 
 --bare::
 	Treat the repository as a bare repository.  If GIT_DIR

-- 
1.5.5