git: update documentation for --git-dir
PATCH 1/1 git: update documentation for --git-dir
From: Heba Waly <[email protected]>
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.
---
[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(-)
Documentation/git.txt +9 -4
@@ -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
Signature · 1 line
gitgitgadget
Quoted 46 lines · Heba Waly via GitGitGadget
From: Heba Waly <[email protected]>
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 <[email protected]>---
[Outreachy] git: update documentation for --git-dirgit --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/537Documentation/git.txt | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-)Documentation/git.txt +0
-3@@ -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.
Documentation/git.txt foo.bar= ...`) sets `foo.bar` to the empty string which `git config · line 121
Quoted 10 lines
Documentation/git.txt +9
-1- + 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.
Quoted 7 lines
Documentation/git.txt +0
-0--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
Quoted 5 lines · Heba Waly via GitGitGadget
From: Heba Waly <[email protected]>
git --git-dir <path> is a bit confusing and sometimes doesn't work as the user would expect it to.
Quoted 7 lines
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?
Quoted 32 lines
Signed-off-by Heba Waly <[email protected]>---
[Outreachy] git: update documentation for --git-dirgit --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/537Documentation/git.txt | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-)Documentation/git.txt +0
-2@@ -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
Documentation/git.txt foo.bar= ...`) sets `foo.bar` to the empty string which `git config · line 120
Quoted 10 lines
Documentation/git.txt +8
-2- 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
Quoted 5 lines · Emily Shaffer
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.
Quoted 2 lines · Heba Waly via GitGitGadget
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.
Documentation/git.txt foo.bar= ...`) sets `foo.bar` to the empty string which `git config · line 113
Quoted 6 lines · Heba Waly via GitGitGadget
--git-dir=<path>::
Documentation/git.txt +1
-4- 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.
Documentation/git.txt foo.bar= ...`) sets `foo.bar` to the empty string which `git config · line 117
Quoted 4 lines
Documentation/git.txt +4
-0+ 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.
Documentation/git.txt foo.bar= ...`) sets `foo.bar` to the empty string which `git config · line 120
Quoted 3 lines
Documentation/git.txt +3
-0+ 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.
Quoted 5 lines
--work-tree=<path>::
Documentation/git.txt +0
-0Set 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.
Quoted 11 lines · Junio C Hamano
"Heba Waly via GitGitGadget" <[email protected]> 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. withGIT_WORK_TREEenvironment). If you have to say something, saying "WhenGIT_DIRis 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.
Quoted 6 lines
Quoted 1 line
+ 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.
Quoted 7 lines
Documentation/git.txt foo.bar= ...`) sets `foo.bar` to the empty string which `git config · line 120
Quoted 3 lines
Documentation/git.txt +3
-0+ 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.
Quoted 14 lines
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_DIRenvironment 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 (orGIT_WORK_TREEenvironment variable)
Quoted 1 line
perhaps.
That helped me understand it better also, will use this, thanks.
Quoted 9 lines
Quoted 6 lines
--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:
232378479ee6c66206d47a9be175e3a39682aea6I 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 v2 1/1 git: update documentation for --git-dir
In reply to Heba Waly via GitGitGadgetFrom: Heba Waly <[email protected]>
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.
---
[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.
+ Helped-by: Junio C Hamano <[email protected]>
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(-)
Documentation/git.txt +17 -3
@@ -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
base-commit: 232378479ee6c66206d47a9be175e3a39682aea6
Signature · 1 line
gitgitgadget
Am 27.01.20 um 03:24 schrieb Heba Waly via GitGitGadget:
Quoted 18 lines
Documentation/git.txt +7
-3@@ -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
Documentation/git.txt foo.bar= ...`) sets `foo.bar` to the empty string which `git config · line 129
Quoted 10 lines
Documentation/git.txt +10
-0+ ".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
Quoted 5 lines · Johannes Sixt
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
Quoted 9 lines · Heba Waly
Quoted 5 lines · Johannes Sixt
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
Quoted 6 lines · Jeff King
One tool that might help as you do documentation patches: there's a doc-diff script that shows the rendered differences.
Try:
Quoted 8 lines
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
PATCH v3 1/1 git: update documentation for --git-dir
In reply to Heba Waly via GitGitGadgetFrom: Heba Waly <[email protected]>
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.
---
[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(-)
Documentation/git.txt +17 -3
@@ -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
base-commit: 232378479ee6c66206d47a9be175e3a39682aea6
Signature · 1 line
gitgitgadget
Documentation/git.txt foo.bar= ...`) sets `foo.bar` to the empty string which `git config · line 118
Quoted 10 lines · Heba Waly via GitGitGadget
--git-dir=<path>::
Documentation/git.txt +6
-3- 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?
Documentation/git.txt foo.bar= ...`) sets `foo.bar` to the empty string which `git config · line 125
Quoted 7 lines
Documentation/git.txt +7
-0+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.
Documentation/git.txt foo.bar= ...`) sets `foo.bar` to the empty string which `git config · line 129
Quoted 4 lines
Documentation/git.txt +4
-0+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?
Quoted 16 lines · Junio C Hamano
Documentation/git.txt foo.bar= ...`) sets `foo.bar` to the empty string which `git config · line 118
Quoted 10 lines · Heba Waly via GitGitGadget
--git-dir=<path>::
Documentation/git.txt +6
-3- 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 theConsistently quote, like
GIT_DIR, here?
Ok
Quoted 11 lines
Documentation/git.txt foo.bar= ...`) sets `foo.bar` to the empty string which `git config · line 125
Quoted 7 lines
Documentation/git.txt +7
-0+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_TREELikewise. We may probably want to say
--work-tree=<path>inside a bq pair, and definitelyGIT_WORK_TREEinside a bq pair.
Ok
Quoted 10 lines
Documentation/git.txt foo.bar= ...`) sets `foo.bar` to the empty string which `git config · line 129
Quoted 4 lines
Documentation/git.txt +4
-0+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>
Quoted 4 lines
If you just want to run git as if it was started in
<path>then usegit -C <path>.perhaps?
Thanks,
Heba
PATCH v4 1/1 git: update documentation for --git-dir
In reply to Heba Waly via GitGitGadgetFrom: Heba Waly <[email protected]>
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.
---
[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(-)
Documentation/git.txt +17 -3
@@ -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 <path>`. --work-tree=<path>:: Set the path to the working tree. It can be an absolute path
base-commit: 232378479ee6c66206d47a9be175e3a39682aea6
Signature · 1 line
gitgitgadget
Quoted 15 lines · Heba Waly via GitGitGadget
Range-diff vs v3:
1:
2a1404f1b3! 1:e27f150c4bgit: 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 (orGIT_DIRenvironment variable) turns off the ++option (orGIT_DIRenvironment 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,
Quoted 8 lines
-+with the --work-tree=<path> option (or
GIT_WORK_TREE++with the--work-tree=<path>option (orGIT_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>.
Will replace and queue. Thanks.