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

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

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-537%2FHebaWaly%2Fgit_dir_doc-v4
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-537/HebaWaly/git_dir_doc-v4
Pull-Request: https://github.com/gitgitgadget/git/pull/537

Range-diff vs v3:

 1:  2a1404f1b3 ! 1:  e27f150c4b git: update documentation for --git-dir
     @@ -31,18 +31,18 @@
      +	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
     ++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
     ++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.
     ++If you just want to run git as if it was started in `<path>` then use
     ++`git -C <path>`.
       
       --work-tree=<path>::
       	Set the path to the working tree. It can be an absolute path

 Documentation/git.txt | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)