diff mbox series

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

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

Commit Message

Johannes Schindelin via GitGitGadget Jan. 28, 2020, 4: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-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-537/HebaWaly/git_dir_doc-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/537

Range-diff vs v2:

 1:  8a69eecb97 ! 1:  2a1404f1b3 git: update documentation for --git-dir
     @@ -29,20 +29,20 @@
      +	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.
     +++
     ++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


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


base-commit: 232378479ee6c66206d47a9be175e3a39682aea6

Comments

Junio C Hamano Jan. 28, 2020, 7:22 p.m. UTC | #1 
"Heba Waly via GitGitGadget" <gitgitgadget@gmail.com> writes:

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

Consistently quote, like `GIT_DIR`, here?

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

Likewise.  We may probably want to say `--work-tree=<path>` inside a
bq pair, and definitely `GIT_WORK_TREE` inside a bq pair.

> +environment variable)
> ++
> +If you just want to run git as if it was started in <path> then use
> +git -C.

This is the best part of this patch, I would think.  But you said
<path> in the "if" part of this "if--then", so (unless your Git
magically can read users' minds some magic), I'd expect to see the
same <path> to appear somewhere in the "then" part.

	If you just want to run git as if it was started in `<path>`
	then use `git -C <path>`.

perhaps?
Heba Waly Jan. 29, 2020, 12:10 p.m. UTC | #2 
On Wed, Jan 29, 2020 at 8:22 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Heba Waly via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> >  --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
>
> Consistently quote, like `GIT_DIR`, here?
>

Ok

> > +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
>
> Likewise.  We may probably want to say `--work-tree=<path>` inside a
> bq pair, and definitely `GIT_WORK_TREE` inside a bq pair.
>

Ok

> > +environment variable)
> > ++
> > +If you just want to run git as if it was started in <path> then use
> > +git -C.
>
> This is the best part of this patch, I would think.  But you said
> <path> in the "if" part of this "if--then", so (unless your Git
> magically can read users' minds some magic), I'd expect to see the
> same <path> to appear somewhere in the "then" part.
>

By <path> here I'm referring to the path parameter of git --git-dir=<path>.
And by mentioning `git -C` without any parameters, my intention is to point the
user to scroll up and read about git -C and its parameters. Given that was
confusing to you, I don't mind stating the command in its simplest form as
you suggested: `git -C <path>`

>         If you just want to run git as if it was started in `<path>`
>         then use `git -C <path>`.
>
> perhaps?

Thanks,
Heba
diff mbox series

Patch

diff --git a/Documentation/git.txt b/Documentation/git.txt
index b1597ac002..c21e33aa10 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