diff mbox series

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

Message ID pull.537.v2.git.1580091855792.gitgitgadget@gmail.com (mailing list archive)
State New, archived
Headers show
Series [v2] git: update documentation for --git-dir | expand

Commit Message

Linus Arver via GitGitGadget Jan. 27, 2020, 2:24 a.m. UTC 
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 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@gmail.com>
     +    Helped-by: Junio C Hamano <gitster@pobox.com>
      
       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(-)


base-commit: 232378479ee6c66206d47a9be175e3a39682aea6

Comments

Johannes Sixt Jan. 27, 2020, 6:28 a.m. UTC | #1 
Am 27.01.20 um 03:24 schrieb Heba Waly via GitGitGadget:
> 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.

Does this render well? Judging by the precedent set by the descriptions
of -C and -c options earlier in this file, continuation paragraphs
should not be indented and separated by a line with just a plus sign
instead of an empty line.

-- Hannes
Heba Waly Jan. 28, 2020, 4:17 a.m. UTC | #2 
On Mon, Jan 27, 2020 at 7:29 PM Johannes Sixt <j6t@kdbg.org> wrote:
>
> Does this render well? Judging by the precedent set by the descriptions
> of -C and -c options earlier in this file, continuation paragraphs
> should not be indented and separated by a line with just a plus sign
> instead of an empty line.

It doesn't render well, thanks for pointing it out, will send an
updated version.

Thanks,
Heba
Jeff King Jan. 28, 2020, 7:33 a.m. UTC | #3 
On Tue, Jan 28, 2020 at 05:17:49PM +1300, Heba Waly wrote:

> On Mon, Jan 27, 2020 at 7:29 PM Johannes Sixt <j6t@kdbg.org> wrote:
> >
> > Does this render well? Judging by the precedent set by the descriptions
> > of -C and -c options earlier in this file, continuation paragraphs
> > should not be indented and separated by a line with just a plus sign
> > instead of an empty line.
> 
> It doesn't render well, thanks for pointing it out, will send an
> updated version.

One tool that might help as you do documentation patches: there's a
doc-diff script that shows the rendered differences.

Try:

  cd Documentation
  ./doc-diff HEAD^ HEAD

(on a branch with your patch at the tip). It was originally written to
investigate changes to the markup, etc, but I find it's useful just for
looking at any documentation patch, because it takes you right to the
part that changed. :)

-Peff
Heba Waly Jan. 28, 2020, 10:40 a.m. UTC | #4 
On Tue, Jan 28, 2020 at 8:33 PM Jeff King <peff@peff.net> wrote:
>
> One tool that might help as you do documentation patches: there's a
> doc-diff script that shows the rendered differences.
>
> Try:
>
>   cd Documentation
>   ./doc-diff HEAD^ HEAD
>
> (on a branch with your patch at the tip). It was originally written to
> investigate changes to the markup, etc, but I find it's useful just for
> looking at any documentation patch, because it takes you right to the
> part that changed. :)
>

Nice, thank you for the tip :)

Heba
diff mbox series

Patch

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