From: Heba Waly <heba.waly@xxxxxxxxx>
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@xxxxxxxxx>
Helped-by: Junio C Hamano <gitster@xxxxxxxxx>
---
[Outreachy] git: update documentation for --git-dir
git --git-dir 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 not
be able to figure out the work tree path on its own and will assign the
work tree to the user's current work directory. When this assignment is
wrong, then the output will not match the user's expectations.
This patch updates the documentation to make it clearer.
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-537%2FHebaWaly%2Fgit_dir_doc-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-537/HebaWaly/git_dir_doc-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/537
Range-diff vs v1:
1: 3ac4b85cdb ! 1: 8a69eecb97 git: update documentation for --git-dir
@@ -6,14 +6,15 @@
the user would expect it to.
For example, if the user runs `git --git-dir=<path> status`, git
- will not be able to figure out the work tree path on its own and
- will assign the work tree to the user's current work directory.
- When this assignment is wrong, then the output will not match the
- user's expectations.
+ 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@xxxxxxxxx>
+ Helped-by: Junio C Hamano <gitster@xxxxxxxxx>
diff --git a/Documentation/git.txt b/Documentation/git.txt
--- a/Documentation/git.txt
@@ -25,16 +26,23 @@
- Set the path to the repository. This can also be controlled by
- setting the `GIT_DIR` environment variable. It can be an absolute
- path or relative path to current working directory.
--
-+ Set the path to the repository (i.e. the .git folder). This can also be
++ Set the path to the repository (".git" directory). This can also be
+ controlled by setting the `GIT_DIR` environment variable. It can be
+ an absolute path or relative path to current working directory.
+
-+ Note that --git-dir=<path> is not the same as -C=<path>.
-+ It's preferrable to set --work-tree=<path> as well when setting
-+ --git-dir to make sure Git will run your command across the correct
-+ work tree.
-+
++ Specifying the location of the ".git" directory using this
++ option (or GIT_DIR environment variable) turns off the
++ repository discovery that tries to find a directory with
++ ".git" subdirectory (which is how the repository and the
++ top-level of the working tree are discovered), and tells Git
++ that you are at the top level of the working tree. If you
++ are not at the top-level directory of the working tree, you
++ should tell Git where the top-level of the working tree is,
++ with the --work-tree=<path> option (or GIT_WORK_TREE
++ environment variable)
++
++ If you just want to run git as if it was started in <path> then use
++ git -C.
+
--work-tree=<path>::
Set the path to the working tree. It can be an absolute path
- or a path relative to the current working directory.
Documentation/git.txt | 20 +++++++++++++++++---
1 file changed, 17 insertions(+), 3 deletions(-)
diff --git a/Documentation/git.txt b/Documentation/git.txt
index b1597ac002..cf73f501b6 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -110,9 +110,23 @@ foo.bar= ...`) sets `foo.bar` to the empty string which `git config
Do not pipe Git output into a pager.
--git-dir=<path>::
- Set the path to the repository. This can also be controlled by
- setting the `GIT_DIR` environment variable. It can be an absolute
- path or relative path to current working directory.
+ Set the path to the repository (".git" directory). This can also be
+ controlled by setting the `GIT_DIR` environment variable. It can be
+ an absolute path or relative path to current working directory.
+
+ Specifying the location of the ".git" directory using this
+ option (or GIT_DIR environment variable) turns off the
+ repository discovery that tries to find a directory with
+ ".git" subdirectory (which is how the repository and the
+ top-level of the working tree are discovered), and tells Git
+ that you are at the top level of the working tree. If you
+ are not at the top-level directory of the working tree, you
+ should tell Git where the top-level of the working tree is,
+ with the --work-tree=<path> option (or GIT_WORK_TREE
+ environment variable)
+
+ If you just want to run git as if it was started in <path> then use
+ git -C.
--work-tree=<path>::
Set the path to the working tree. It can be an absolute path
base-commit: 232378479ee6c66206d47a9be175e3a39682aea6
--
gitgitgadget
