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

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

[Liu Yubao]

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

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

[Michael J Gruber]

Liu Yubao venit, vidit, dixit 28.04.2008 22:09:
> 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.

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.

> And here is my supplement to the documentation.

> +	variable and the '--work-tree' command line option. It can be
> +	a absolute path or relative path to the directory specified by

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

> +	--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,

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

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

[しらいしななこ]

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

> 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!

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.

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

----------------------------------------------------------------------
Finally - A spam blocker that actually works.
http://www.bluebottle.com/tag/4