gitmodules.txt: fix 'GIT_WORK_TREE' variable name
PATCH 1/1 gitmodules.txt: fix 'GIT_WORK_TREE' variable name
From: Philippe Blain <[email protected]>
'gitmodules.txt' is a guide about the '.gitmodules' file that describes submodules properties, and that file must exist at the root of the repository. This was clarified in e5b5c1d2cf (Document clarification:
gitmodules, gitattributes, 2008-08-31).
However, that commit mistakenly uses the non-existing environment variable 'GIT_WORK_DIR' to refer to the root of the repository.
Fix that by using the correct variable, 'GIT_WORK_TREE'. Take the opportunity to modernize and improve the formatting of that guide.
---
gitmodules.txt: fix 'GIT_WORK_TREE' variable name
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-942%2Fphil-blain%2Fdoc-gitmodules-envvar-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-942/phil-blain/doc-gitmodules-envvar-v1
Pull-Request: https://github.com/git/git/pull/942
Documentation/gitmodules.txt | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-)
Documentation/gitmodules.txt +12 -12
@@ -7,7 +7,7 @@ gitmodules - Defining submodule properties SYNOPSIS -------- -$GIT_WORK_DIR/.gitmodules +$GIT_WORK_TREE/.gitmodules DESCRIPTION
@@ -32,14 +32,14 @@ submodule.<name>.path:: submodule.<name>.url:: Defines a URL from which the submodule repository can be cloned. This may be either an absolute URL ready to be passed to - linkgit:git-clone[1] or (if it begins with ./ or ../) a location + linkgit:git-clone[1] or (if it begins with `./` or `../`) a location relative to the superproject's origin repository. In addition, there are a number of optional keys: submodule.<name>.update:: Defines the default update procedure for the named submodule, - i.e. how the submodule is updated by "git submodule update" + i.e. how the submodule is updated by the `git submodule update` command in the superproject. This is only used by `git submodule init` to initialize the configuration variable of the same name. Allowed values here are 'checkout', 'rebase',
@@ -58,13 +58,13 @@ submodule.<name>.branch:: submodule.<name>.fetchRecurseSubmodules:: This option can be used to control recursive fetching of this submodule. If this option is also present in the submodules entry in - .git/config of the superproject, the setting there will override the - one found in .gitmodules. + `.git/config` of the superproject, the setting there will override the + one found in `.gitmodules`. Both settings can be overridden on the command line by using the - "--[no-]recurse-submodules" option to "git fetch" and "git pull". + `--[no-]recurse-submodules` option to `git fetch` and `git pull`. submodule.<name>.ignore:: - Defines under what circumstances "git status" and the diff family show + Defines under what circumstances `git status` and the diff family show a submodule as modified. The following values are supported: + --
@@ -73,7 +73,7 @@ submodule.<name>.ignore:: been staged). dirty;; All changes to the submodule's work tree will be ignored, only - committed differences between the HEAD of the submodule and its + committed differences between the 'HEAD' of the submodule and its recorded state in the superproject are taken into account. untracked;; Only untracked files in submodules will be ignored.
@@ -84,12 +84,12 @@ submodule.<name>.ignore:: differences, and modifications to tracked and untracked files are shown. This is the default option. -If this option is also present in the submodules entry in .git/config +If this option is also present in the submodules entry in `.git/config` of the superproject, the setting there will override the one found in -.gitmodules. +`.gitmodules`. Both settings can be overridden on the command line by using the -"--ignore-submodules" option. The 'git submodule' commands are not +`--ignore-submodules` option. The `git submodule` commands are not affected by this setting. --
@@ -102,7 +102,7 @@ submodule.<name>.shallow:: EXAMPLES -------- -Consider the following .gitmodules file: +Consider the following `.gitmodules` file: ---- [submodule "libfoo"]
base-commit: 71ca53e8125e36efbda17293c50027d31681a41f
Signature · 1 line
gitgitgadget
Quoted 10 lines · Philippe Blain via GitGitGadget
From: Philippe Blain <[email protected]>
'gitmodules.txt' is a guide about the '.gitmodules' file that describes submodules properties, and that file must exist at the root of the repository. This was clarified in
e5b5c1d2cf(Document clarification:
gitmodules, gitattributes, 2008-08-31).However, that commit mistakenly uses the non-existing environment variable '
GIT_WORK_DIR' to refer to the root of the repository.
Good catch! I wonder what we should conclude from this having gone unreported for so long.
Quoted 2 lines
Fix that by using the correct variable, '
GIT_WORK_TREE'. Take the opportunity to modernize and improve the formatting of that guide.
It's a small correctness fix and some prettifying while at it. While I read the diff and realized that it was more than just one or two asciidoc tweaks in the immediate vicinity, I started wondering if this should be presented the other way round: "Let's update the formatting and fix s/DIR/TREE/ while at it." Or to split it up. But I don't think it's worth thinking too much about -- what you have looks good to me.
Review submodule.<name>.path::
Quoted 1 line
(quoted diff) +0
-0@@ -32,14 +32,14 @@ submodule.<name>.path::
Just above this point, you have another s/\.gitmodules/&/ waiting to be fixed.
Documentation/gitmodules.txt submodule.<name>.ignore:: · line 77
Quoted 8 lines
Documentation/gitmodules.txt +1
-1submodule.<name>.url:: Defines a URL from which the submodule repository can be cloned. This may be either an absolute URL ready to be passed to dirty;; All changes to the submodule's work tree will be ignored, only - committed differences between the HEAD of the submodule and its + committed differences between the 'HEAD' of the submodule and its recorded state in the superproject are taken into account.
git grep -B10 HEAD CodingGuidelines suggests this should be HEAD, not 'HEAD'. Maybe you followed style -- there's an instance of 'HEAD' earlier. I think both should be HEAD.
Documentation/gitmodules.txt submodule.<name>.ignore:: · line 89
Quoted 5 lines
Documentation/gitmodules.txt +2
-2-If this option is also present in the submodules entry in .git/config +If this option is also present in the submodules entry in `.git/config` of the superproject, the setting there will override the one found in -.gitmodules. +`.gitmodules`.
Should "submodules entry" be "submodule's entry"? I've never worked with submodules, but that reading somehow seems more natural. (There are two hits for "submodules entry" in this document -- both might be worth looking at.)
This patch looks good to me. It might be worthwhile to reroll to address the naked .gitmodules around line 30 and the two 'HEAD' while you're in the area. As for the last comment above, it could well be that the proper response is "no, you're wrong".
Martin
Quoted 10 lines · Martin Ågren
Quoted 8 lines · Philippe Blain via GitGitGadget
From: Philippe Blain <[email protected]>
'gitmodules.txt' is a guide about the '.gitmodules' file that describes submodules properties, and that file must exist at the root of the repository. This was clarified in
e5b5c1d2cf(Document clarification:
gitmodules, gitattributes, 2008-08-31).
Quoted 5 lines
Quoted 2 lines
However, that commit mistakenly uses the non-existing environment variable '
GIT_WORK_DIR' to refer to the root of the repository.Good catch! I wonder what we should conclude from this having gone unreported for so long.
That perhaps not that many people actually read the official documentation?
I've noticed the common response RTFM is not that common anymore. A lot of people seem to rely on Stack Overflow, blogs, and some semi-official documentation (GitHub, Atlassian, etc.).
Cheers.
Signature · 1 line
Felipe Contreras
Quoted 6 lines · Felipe Contreras
Quoted 2 lines · Martin Ågren
Good catch! I wonder what we should conclude from this having gone unreported for so long.
Quoted 6 lines
That perhaps not that many people actually read the official documentation?
I've noticed the common response RTFM is not that common anymore. A lot of people seem to rely on Stack Overflow, blogs, and some semi-official documentation (GitHub, Atlassian, etc.).
Hmm, now that you say it, I think that matches my impression. There was a time when that seemed to be a really "in" answer, if not always entirely friendly. You're right that it seems to be quite a bit less common today.
Martin
Hi Martin,
Le 2021-01-02 à 16:34, Martin Ågren a écrit :
Quoted 26 lines
Quoted 10 lines · Philippe Blain via GitGitGadget
From: Philippe Blain <[email protected]>
'gitmodules.txt' is a guide about the '.gitmodules' file that describes submodules properties, and that file must exist at the root of the repository. This was clarified in
e5b5c1d2cf(Document clarification:
gitmodules, gitattributes, 2008-08-31).However, that commit mistakenly uses the non-existing environment variable '
GIT_WORK_DIR' to refer to the root of the repository.Good catch! I wonder what we should conclude from this having gone unreported for so long.
Quoted 2 lines
Fix that by using the correct variable, '
GIT_WORK_TREE'. Take the opportunity to modernize and improve the formatting of that guide.It's a small correctness fix and some prettifying while at it. While I read the diff and realized that it was more than just one or two asciidoc tweaks in the immediate vicinity, I started wondering if this should be presented the other way round: "Let's update the formatting and fix s/DIR/TREE/ while at it." Or to split it up. But I don't think it's worth thinking too much about -- what you have looks good to me.
Quoted 4 lines
Review submodule.<name>.path::
Quoted 1 line
(quoted diff) +0
-0@@ -32,14 +32,14 @@ submodule.<name>.path::Just above this point, you have another s/\.gitmodules/
&/ waiting to be fixed.
Thanks, I added that.
Quoted 5 lines
Quoted 4 lines
Documentation/gitmodules.txt +0
-0submodule.<name>.url:: Defines a URL from which the submodule repository can be cloned. This may be either an absolute URL ready to be passed to
Quoted 8 lines
Documentation/gitmodules.txt submodule.<name>.ignore:: · line 77
Quoted 4 lines
Documentation/gitmodules.txt +1
-1dirty;; All changes to the submodule's work tree will be ignored, only - committed differences between the HEAD of the submodule and its + committed differences between the 'HEAD' of the submodule and its recorded state in the superproject are taken into account.
git grep -B10 HEAD CodingGuidelinessuggests this should beHEAD, not 'HEAD'. Maybe you followed style -- there's an instance of 'HEAD' earlier. I think both should beHEAD.
Yes, HEAD has indeed more hits than 'HEAD'.
Quoted 11 lines
Documentation/gitmodules.txt submodule.<name>.ignore:: · line 89
Quoted 6 lines
Documentation/gitmodules.txt +2
-2-If this option is also present in the submodules entry in .git/config +If this option is also present in the submodules entry in `.git/config` of the superproject, the setting there will override the one found in -.gitmodules. +`.gitmodules`.Should "submodules entry" be "submodule's entry"? I've never worked with submodules, but that reading somehow seems more natural. (There are two hits for "submodules entry" in this document -- both might be worth looking at.)
I agree, I also added that.
Thanks,
Philippe.
PATCH v2 1/1 gitmodules.txt: fix 'GIT_WORK_TREE' variable name
In reply to Philippe Blain via GitGitGadgetFrom: Philippe Blain <[email protected]>
'gitmodules.txt' is a guide about the '.gitmodules' file that describes submodule properties, and that file must exist at the root of the repository. This was clarified in e5b5c1d2cf (Document clarification:
gitmodules, gitattributes, 2008-08-31).
However, that commit mistakenly uses the non-existing environment variable 'GIT_WORK_DIR' to refer to the root of the repository.
Fix that by using the correct variable, 'GIT_WORK_TREE'. Take the opportunity to modernize and improve the formatting of that guide, and fix a grammar mistake.
---
gitmodules.txt: fix 'GIT_WORK_TREE' variable name
Changes since v1:
* added Martin's suggestions
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-942%2Fphil-blain%2Fdoc-gitmodules-envvar-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-942/phil-blain/doc-gitmodules-envvar-v2
Pull-Request: https://github.com/git/git/pull/942
Range-diff vs v1:
1: 8fa2238f4a0 ! 1: 4fca37ea043 gitmodules.txt: fix 'GIT_WORK_TREE' variable name
@@ Commit message
gitmodules.txt: fix 'GIT_WORK_TREE' variable name
'gitmodules.txt' is a guide about the '.gitmodules' file that describes
- submodules properties, and that file must exist at the root of the
+ submodule properties, and that file must exist at the root of the
repository. This was clarified in e5b5c1d2cf (Document clarification:
gitmodules, gitattributes, 2008-08-31).
@@ Commit message
variable 'GIT_WORK_DIR' to refer to the root of the repository.
Fix that by using the correct variable, 'GIT_WORK_TREE'. Take the
- opportunity to modernize and improve the formatting of that guide.
+ opportunity to modernize and improve the formatting of that guide,
+ and fix a grammar mistake.
@@ Documentation/gitmodules.txt: gitmodules - Defining submodule properties
DESCRIPTION
@@ Documentation/gitmodules.txt: submodule.<name>.path::
+ Defines the path, relative to the top-level directory of the Git
+ working tree, where the submodule is expected to be checked out.
+ The path name must not end with a /. All submodule paths must
+- be unique within the .gitmodules file.
++ be unique within the .gitmodules file.
+
submodule.<name>.url::
Defines a URL from which the submodule repository can be cloned. This may be either an absolute URL ready to be passed to
@@ Documentation/gitmodules.txt: submodule.<name>.path::
command in the superproject. This is only used by git submodule init to initialize the configuration variable of the same name. Allowed values here are 'checkout', 'rebase',
+@@ Documentation/gitmodules.txt: submodule.<name>.update::
+
+ submodule.<name>.branch::
+ A remote branch name for tracking updates in the upstream submodule.
+- If the option is not specified, it defaults to the remote 'HEAD'.
++ If the option is not specified, it defaults to the remote HEAD.
+ A special value of . is used to indicate that the name of the branch
+ in the submodule should be the same name as the current branch in the
+ current repository. See the --remote documentation in
@@ Documentation/gitmodules.txt: submodule.<name>.branch::
+
submodule.<name>.fetchRecurseSubmodules::
This option can be used to control recursive fetching of this
- submodule. If this option is also present in the submodules entry in
+- submodule. If this option is also present in the submodules entry in
- .git/config of the superproject, the setting there will override the
- one found in .gitmodules.
++ submodule. If this option is also present in the submodule's entry in
+ .git/config of the superproject, the setting there will override the
+ one found in .gitmodules.
Both settings can be overridden on the command line by using the
@@ Documentation/gitmodules.txt: submodule.<name>.ignore::
dirty;; All changes to the submodule's work tree will be ignored, only
- committed differences between the HEAD of the submodule and its
-+ committed differences between the 'HEAD' of the submodule and its
++ committed differences between the HEAD of the submodule and its
recorded state in the superproject are taken into account.
untracked;; Only untracked files in submodules will be ignored.
@@ Documentation/gitmodules.txt: submodule.<name>.ignore::
shown. This is the default option.
-If this option is also present in the submodules entry in .git/config
-+If this option is also present in the submodules entry in .git/config ++If this option is also present in the submodule's entry in .git/config
of the superproject, the setting there will override the one found in
-.gitmodules.
+.gitmodules.
Documentation/gitmodules.txt | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-)
Documentation/gitmodules.txt +15 -15
@@ -7,7 +7,7 @@ gitmodules - Defining submodule properties SYNOPSIS -------- -$GIT_WORK_DIR/.gitmodules +$GIT_WORK_TREE/.gitmodules DESCRIPTION
@@ -27,19 +27,19 @@ submodule.<name>.path:: Defines the path, relative to the top-level directory of the Git working tree, where the submodule is expected to be checked out. The path name must not end with a `/`. All submodule paths must - be unique within the .gitmodules file. + be unique within the `.gitmodules` file. submodule.<name>.url:: Defines a URL from which the submodule repository can be cloned. This may be either an absolute URL ready to be passed to - linkgit:git-clone[1] or (if it begins with ./ or ../) a location + linkgit:git-clone[1] or (if it begins with `./` or `../`) a location relative to the superproject's origin repository. In addition, there are a number of optional keys: submodule.<name>.update:: Defines the default update procedure for the named submodule, - i.e. how the submodule is updated by "git submodule update" + i.e. how the submodule is updated by the `git submodule update` command in the superproject. This is only used by `git submodule init` to initialize the configuration variable of the same name. Allowed values here are 'checkout', 'rebase',
@@ -49,7 +49,7 @@ submodule.<name>.update:: submodule.<name>.branch:: A remote branch name for tracking updates in the upstream submodule. - If the option is not specified, it defaults to the remote 'HEAD'. + If the option is not specified, it defaults to the remote `HEAD`. A special value of `.` is used to indicate that the name of the branch in the submodule should be the same name as the current branch in the current repository. See the `--remote` documentation in
@@ -57,14 +57,14 @@ submodule.<name>.branch:: submodule.<name>.fetchRecurseSubmodules:: This option can be used to control recursive fetching of this - submodule. If this option is also present in the submodules entry in - .git/config of the superproject, the setting there will override the - one found in .gitmodules. + submodule. If this option is also present in the submodule's entry in + `.git/config` of the superproject, the setting there will override the + one found in `.gitmodules`. Both settings can be overridden on the command line by using the - "--[no-]recurse-submodules" option to "git fetch" and "git pull". + `--[no-]recurse-submodules` option to `git fetch` and `git pull`. submodule.<name>.ignore:: - Defines under what circumstances "git status" and the diff family show + Defines under what circumstances `git status` and the diff family show a submodule as modified. The following values are supported: + --
@@ -73,7 +73,7 @@ submodule.<name>.ignore:: been staged). dirty;; All changes to the submodule's work tree will be ignored, only - committed differences between the HEAD of the submodule and its + committed differences between the `HEAD` of the submodule and its recorded state in the superproject are taken into account. untracked;; Only untracked files in submodules will be ignored.
@@ -84,12 +84,12 @@ submodule.<name>.ignore:: differences, and modifications to tracked and untracked files are shown. This is the default option. -If this option is also present in the submodules entry in .git/config +If this option is also present in the submodule's entry in `.git/config` of the superproject, the setting there will override the one found in -.gitmodules. +`.gitmodules`. Both settings can be overridden on the command line by using the -"--ignore-submodules" option. The 'git submodule' commands are not +`--ignore-submodules` option. The `git submodule` commands are not affected by this setting. --
@@ -102,7 +102,7 @@ submodule.<name>.shallow:: EXAMPLES -------- -Consider the following .gitmodules file: +Consider the following `.gitmodules` file: ---- [submodule "libfoo"]
base-commit: 71ca53e8125e36efbda17293c50027d31681a41f
Signature · 1 line
gitgitgadget
Hi Philippe,
Quoted 4 lines · Philippe Blain via GitGitGadget
Changes since v1:
* added Martin's suggestions
Yup, this looks good to me.
Martin
Quoted 5 lines · Martin Ågren
Hi Philippe,
Quoted 1 line · Philippe Blain via GitGitGadget
Quoted 7 lines
Quoted 3 lines
Changes since v1:
* added Martin's suggestions
Yup, this looks good to me.
Martin
Thanks, all.