[PATCH] git: update documentation for --git-dir

From: Heba Waly via GitGitGadget <gitgitgadget@gmail.com>
Date: Jan 23, 2020, 02:16 UTC
Message-ID: <pull.537.git.1579745811615.gitgitgadget@gmail.com>

From: Heba Waly <heba.waly@gmail.com>

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

Signed-off-by: Heba Waly <heba.waly@gmail.com>
---
    [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-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-537/HebaWaly/git_dir_doc-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/537

 Documentation/git.txt | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index b1597ac002..3b9402c742 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -110,10 +110,15 @@ 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 (i.e. the .git folder). 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.
+	
 --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.

base-commit: 232378479ee6c66206d47a9be175e3a39682aea6

-- 
gitgitgadget