git: update documentation for --git-dir
git --git-dir <path> is a bit confusing and sometimes doesn't work as the user would expect it to. For example, if the user runs `git --git-dir=<path> status`, git will skip the repository discovery algorithm and will assign the work tree to the user's current work directory unless otherwise specified. When this assignment is wrong, the output will not match the user's expectations. This patch updates the documentation to make it clearer. Signed-off-by: Heba Waly <heba.waly@gmail.com> Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Heba Waly committed
Jan 30, 2020 at 01:14 UTC
d82ad54945be557f9c70550842ffc568b25cd16a
1 file changed
+17
-3
Documentation/git.txt
+17
-3
@@ -110,9 +110,23 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config
110
Do not pipe Git output into a pager.
111
112
--git-dir=<path>::
113
- Set the path to the repository. This can also be controlled by
114
- setting the `GIT_DIR` environment variable. It can be an absolute
115
- path or relative path to current working directory.
113
+ Set the path to the repository (".git" directory). This can also be
114
+ controlled by setting the `GIT_DIR` environment variable. It can be
115
+ an absolute path or relative path to current working directory.
116
++
117
+Specifying the location of the ".git" directory using this
118
+option (or `GIT_DIR` environment variable) turns off the
119
+repository discovery that tries to find a directory with
120
+".git" subdirectory (which is how the repository and the
121
+top-level of the working tree are discovered), and tells Git
122
+that you are at the top level of the working tree. If you
123
+are not at the top-level directory of the working tree, you
124
+should tell Git where the top-level of the working tree is,
125
+with the `--work-tree=<path>` option (or `GIT_WORK_TREE`
126
+environment variable)
127
++
128
+If you just want to run git as if it was started in `<path>` then use
129
+`git -C <path>`.
130
131
--work-tree=<path>::
132
Set the path to the working tree. It can be an absolute path