git: update documentation for --git-dir
diff mbox series

Message ID pull.537.git.1579745811615.gitgitgadget@gmail.com
State New
Headers show
Series
  • git: update documentation for --git-dir
Related show

Commit Message

Han-Wen Nienhuys via GitGitGadget Jan. 23, 2020, 2:16 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 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(-)


base-commit: 232378479ee6c66206d47a9be175e3a39682aea6

Comments

Heba Waly Jan. 23, 2020, 2:35 a.m. UTC | #1
On Thu, Jan 23, 2020 at 3:16 PM Heba Waly via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> 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.
> +

I just noticed the whitespace on the last line, will wait for the
patch to be reviewed then include its fix.

>  --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
Emily Shaffer Jan. 23, 2020, 2:55 a.m. UTC | #2
On Thu, Jan 23, 2020 at 02:16:51AM +0000, Heba Waly via GitGitGadget wrote:
> 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.

One thing Heba doesn't mention here is the effort she spent looking into
how to give a similar hint in the form of an advise() call in cases when
--git-dir is specified but --work-tree is not. While it's possible to
show that kind of hint, it turns out to be tricky to decide whether the
call in question actually wants the worktree. There was also some
concern from Jonathan Tan around whether the hint would interfere with
pre-existing user scripts which use --git-dir; since hints show on
stderr, that interference is likely cosmetic, but still not great.

That left me with a couple questions:

 - Is there a reason the advice library can't check whether it's
   pointing to an interactive shell, along the same lines as deciding
   whether to color output or not?
 - How do we generally worry about changes to stderr output in regard to
   user scripts? Is this as concerning as changes to stdout and return
   code, that is, for plumbing we do not change the format?

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

I feel biased. I want to say, "In many cases, -C=<path> is easier to
understand than --git-dir" instead. :) But my goal with sending this
task to you was "convince people to use -C instead of --git-dir unless
they're really sure" - which may or may not align with the sentiment of
the rest of the list.

 - Emily
Junio C Hamano Jan. 23, 2020, 6:21 a.m. UTC | #3
"Heba Waly via GitGitGadget" <gitgitgadget@gmail.com> writes:

> 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 

It is not "not be able to figure out".  Specifying GIT_DIR (either
with environment or the --git-dir option) tells Git that the $cwd is
the top of the working tree unless otherwise specified (e.g. with
GIT_WORK_TREE environment).  If you have to say something, saying
"When GIT_DIR is specified, the usual repository discovery is
skipped and the current directory is taken as the top level of the
working tree unless otherwise speciffied" is probably OK.
Junio C Hamano Jan. 23, 2020, 6:41 a.m. UTC | #4
"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 (i.e. the .git folder). This can also be

I suspect (i.e. ".git") may be clear enough, but if you must, say
".git directory", not ".git folder", as you mention "current working
directory" later.

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

Surely, of course.

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

It does not help the readers that much to say "It's preferrable"
without saying what negative implications there are if they don't
use it, or what positive effect they would observe if they do.

If I were writing it, I'd drop "Note that..." and rewrite the three
lines more like...

	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)

perhaps.

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

I do not know if GGG users have control over this, but I'd prefer to
see a "-- " divider before this "base-commit: ..." footer material.
Junio C Hamano Jan. 23, 2020, 6:44 a.m. UTC | #5
Emily Shaffer <emilyshaffer@google.com> writes:

> I feel biased. I want to say, "In many cases, -C=<path> is easier to
> understand than --git-dir" instead. :) But my goal with sending this
> task to you was "convince people to use -C instead of --git-dir unless
> they're really sure" - which may or may not align with the sentiment of
> the rest of the list.

Ahh, OK.  

These two are options for completely different purposes, and I tend
to agree with you that most users when they misuse --git-dir the do
want -C instead.
Heba Waly Jan. 27, 2020, 2:22 a.m. UTC | #6
On Thu, Jan 23, 2020 at 7:41 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Heba Waly via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> It is not "not be able to figure out".  Specifying GIT_DIR (either
> with environment or the --git-dir option) tells Git that the $cwd is
> the top of the working tree unless otherwise specified (e.g. with
> GIT_WORK_TREE environment).  If you have to say something, saying
> "When GIT_DIR is specified, the usual repository discovery is
> skipped and the current directory is taken as the top level of the
> working tree unless otherwise speciffied" is probably OK.
>

Ok, I didn't understand it as intentional before, will update that.

> > +     Set the path to the repository (i.e. the .git folder). This can also be
>
> I suspect (i.e. ".git") may be clear enough, but if you must, say
> ".git directory", not ".git folder", as you mention "current working
> directory" later.
>

Fair enough.

> > +     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.
>
> It does not help the readers that much to say "It's preferrable"
> without saying what negative implications there are if they don't
> use it, or what positive effect they would observe if they do.

I agree, I couldn't find enough information on the matter to elaborate more.

> If I were writing it, I'd drop "Note that..." and rewrite the three
> lines more like...
>
>         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)
>
> perhaps.

That helped me understand it better also, will use this, thanks.

>
> >  --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
>
> I do not know if GGG users have control over this, but I'd prefer to
> see a "-- " divider before this "base-commit: ..." footer material.

No I don't think I can change this one.

Thanks,
Heba

Patch
diff mbox series

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.