update git-clean.txt
cover update git-clean.txt
Robert reported that core.excludesFile was not mentioned in the git-clean docs[1]. This cleans that up by mentioning that in the docs.
[1]: https://public-inbox.org/git/[email protected]/
Denton Liu (1):
git-clean.txt: specify core.excludesFile variable is used
Documentation/git-clean.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-)
Signature · 1 line
2.21.0.317.g7f43cb445c
PATCH 1/1 git-clean.txt: specify core.excludesFile variable is used
In the git-clean documentation, -x and -e documented .gitignore, $GIT_DIR/info/excludes but neglected to mention the file pointed to by core.excludesFile.
Explicitly mention that variable so that the list is exhaustive.
--- Documentation/git-clean.txt | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-)
Documentation/git-clean.txt +5 -3
@@ -55,13 +55,15 @@ OPTIONS -e <pattern>:: --exclude=<pattern>:: - In addition to those found in .gitignore (per directory) and - $GIT_DIR/info/exclude, also consider these patterns to be in the + In addition to those found in .gitignore (per directory), + $GIT_DIR/info/exclude, and the `core.excludesFile` variable, also + consider these patterns to be in the set of the ignore rules in effect. -x:: Don't use the standard ignore rules read from .gitignore (per - directory) and $GIT_DIR/info/exclude, but do still use the ignore + directory), $GIT_DIR/info/exclude, and the `core.excludesFile` + variable, but do still use the ignore rules given with `-e` options. This allows removing all untracked files, including build products. This can be used (possibly in conjunction with 'git reset') to create a pristine
Signature · 1 line
2.21.0.317.g7f43cb445c
Re: [PATCH 1/1] git-clean.txt: specify core.excludesFile variable is used
Quoted 4 lines · Denton Liu
In the git-clean documentation, -x and -e documented .gitignore, $GIT_DIR/info/excludes but neglected to mention the file pointed to by core.excludesFile.
Nit: I suppose it doesn't so much document it, as mention it. So
In the git-clean documentation, we mention .gitignore and $GIT_DIR/info/excludes, but neglect to mention the file pointed to by core.excludesFile.
perhaps.
Documentation/git-clean.txt OPTIONS · line 61
Quoted 10 lines
Explicitly mention that variable so that the list is exhaustive.
-e <pattern>::
--exclude=<pattern>::Documentation/git-clean.txt +3
-2- In addition to those found in .gitignore (per directory) and - $GIT_DIR/info/exclude, also consider these patterns to be in the + In addition to those found in .gitignore (per directory), + $GIT_DIR/info/exclude, and the `core.excludesFile` variable, also + consider these patterns to be in the set of the ignore rules in effect.
The commit message correctly phrases it as "the file pointed to by", whereas this could give the impression that the config variable is supposed to provide patterns, not a filename. But if the choice is between creating a longer, more language-lawyer-correct phrasing and a shorter one that everyone will understand, I'll choose the latter any day.
But on the topic of preferring shorter, I sort of wonder if we really need to provide all of those filenames here. The point we're trying to make is that we consider another source. So something like this would be just as technically correct, I think:
Use the given exclude pattern in addition to those found in .gitignore and similar files (see linkgit:gitignore[5]).
This also places the interesting (IMHO) part of the sentence at the front, rather than at the end.
From gitignore(5), I get the impression that patterns provided using --exclude take precedence over those found in those files we're listing. Whether or not that is the case here might perhaps be more interesting than the exact list of files. Does that make sense?
Documentation/git-clean.txt OPTIONS · line 69
Quoted 8 lines
-x::
Don't use the standard ignore rules read from .gitignore (perDocumentation/git-clean.txt +2
-1- directory) and $GIT_DIR/info/exclude, but do still use the ignore + directory), $GIT_DIR/info/exclude, and the `core.excludesFile` + variable, but do still use the ignore rules given with `-e` options. This allows removing all untracked files, including build products. This can be used (possibly in conjunction with 'git reset') to create a pristine
Nit: Not new in this patch, but I think you could add a few backticks while you're here to render things like .gitignore and $GIT_DIR/info/exclude/ in monospace.
Martin
Re: [PATCH 1/1] git-clean.txt: specify core.excludesFile variable is used
Quoted 7 lines · Martin Ågren
But on the topic of preferring shorter, I sort of wonder if we really need to provide all of those filenames here. The point we're trying to make is that we consider another source. So something like this would be just as technically correct, I think:
Use the given exclude pattern in addition to those found in .gitignore and similar files (see linkgit:gitignore[5]).
Yes. Unless we devise some mechanism to prevent these text that list the places exclusion list are read from spread across the documentation set, saying "found in usual places (see $there)" and making sure we have the authoritative single place up-to-date is a good approach.
v2 cover make git-clean.txt more precise
In reply to Denton LiuRobert reported that core.excludesFile was not mentioned in the git-clean docs[1]. This cleans that up by mentioning that in the docs.
[1]: https://public-inbox.org/git/[email protected]/
Changes since v1:
* Use Martin's suggestions of referencing the gitignore(5) instead of writing an exhaustive list. Also, sprinkle in some backticks ;)
Denton Liu (1):
git-clean.txt: clarify ignore pattern files
Documentation/git-clean.txt | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-)
Signature · 1 line
2.21.0.368.gbf248417d7
PATCH v2 1/1 git-clean.txt: clarify ignore pattern files
In the git-clean documentation, -x and -e documented .gitignore, $GIT_DIR/info/excludes but neglected to mention the file pointed to by core.excludesFile.
Remove specific list of files and, instead, reference gitignore(5) documentation so that information is consolidated and the git-clean documentation is more precise.
--- Documentation/git-clean.txt | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-)
Documentation/git-clean.txt +4 -5
@@ -55,13 +55,12 @@ OPTIONS -e <pattern>:: --exclude=<pattern>:: - In addition to those found in .gitignore (per directory) and - $GIT_DIR/info/exclude, also consider these patterns to be in the - set of the ignore rules in effect. + Use the exclude pattern in addition to those found in + `.gitignore` and similar files (see linkgit:gitignore[5]). -x:: - Don't use the standard ignore rules read from .gitignore (per - directory) and $GIT_DIR/info/exclude, but do still use the ignore + Don't use the standard ignore rules read from `.gitignore` and + similar files (see linkgit:gitignore[5]), but do still use the ignore rules given with `-e` options. This allows removing all untracked files, including build products. This can be used (possibly in conjunction with 'git reset') to create a pristine
Signature · 1 line
2.21.0.368.gbf248417d7
Re: [PATCH v2 1/1] git-clean.txt: clarify ignore pattern files
Quoted 6 lines · Denton Liu
-e <pattern>::
--exclude=<pattern>::Documentation/git-clean.txt +1
-3- In addition to those found in .gitignore (per directory) and - $GIT_DIR/info/exclude, also consider these patterns to be in the - set of the ignore rules in effect. + Use the exclude pattern in addition to those found in
Documentation/git-clean.txt OPTIONS · line 66
Quoted 10 lines
Documentation/git-clean.txt +3
-2+ `.gitignore` and similar files (see linkgit:gitignore[5]). -x:: - Don't use the standard ignore rules read from .gitignore (per - directory) and $GIT_DIR/info/exclude, but do still use the ignore + Don't use the standard ignore rules read from `.gitignore` and + similar files (see linkgit:gitignore[5]), but do still use the ignore rules given with `-e` options. This allows removing all untracked files, including build products. This can be used (possibly in conjunction with 'git reset') to create a pristine
I do agree with the direction to abandon the attempt to be exhaustive, which has failed us and will fail. I am not sure if ".gitignore and similar files" is a good phrasing, though.
Don't use the standard ignored rules (see linkgit:gitignore[5]), but use the ignore rules given with -e options from the command line.
perhaps? I dunno.
A related tangent.
"git add --help" also has this bit.
CONFIGURATION
-------------
The optional configuration variable core.excludesFile indicates a path to a file containing patterns of file names to exclude from git-add, similar to $GIT_DIR/info/exclude. Patterns in the exclude file are used in addition to those in info/exclude. See linkgit:gitignore[5].
I do not think the omission of per-directory .gitignore from this description is because the description predates the feature (which is the reason why "git clean" doc does not mention, by the way), but this probably needs a simliar treatment.
Or perhaps this configuration section should just be removed (or moved to gitignore(5)), as it is not specific to "git add".
Re: [PATCH v2 1/1] git-clean.txt: clarify ignore pattern files
Quoted 10 lines · Junio C Hamano
Documentation/git-clean.txt OPTIONS · line 59
Quoted 2 lines · Denton Liu
Documentation/git-clean.txt +2
-0+ Use the exclude pattern in addition to those found in + `.gitignore` and similar files (see linkgit:gitignore[5]).I do agree with the direction to abandon the attempt to be exhaustive, which has failed us and will fail. I am not sure if ".gitignore and similar files" is a good phrasing, though.
Quoted 5 lines
Don't use the standard ignored rules (see linkgit:gitignore[5]), but use the ignore rules given with
-eoptions from the command line.perhaps? I dunno.
Yeah, I like "the standard ignore rules" more than my original suggestion. Hmm, I now see you wrote "the standard ignore/D/ rules" -- I believe that's a typo.
Martin
Re: [PATCH v2 1/1] git-clean.txt: clarify ignore pattern files
Quoted 2 lines · Martin Ågren
suggestion. Hmm, I now see you wrote "the standard ignore/D/ rules" -- I believe that's a typo.
Thanks for spotting. Yup, that is a typo.
v3 cover consolidate core.excludesFile docs
In reply to Denton LiuRobert reported that core.excludesFile was not mentioned in the git-clean docs[1]. This cleans that up by mentioning that in the docs.
[1]: https://public-inbox.org/git/[email protected]/
Changes since v1:
* Use Martin's suggestions of referencing the gitignore(5) instead of writing an exhaustive list. Also, sprinkle in some backticks ;)
Changes since v2:
* Use Junio's suggestion for rephrasing the text in git-clean.txt
* Move core.excludesFile specific documentation out of git-add.txt and into gitignore.txt
Denton Liu (2):
git-clean.txt: clarify ignore pattern files
Docs: move core.excludesFile from git-add to gitignore
Documentation/git-add.txt | 9 --------- Documentation/git-clean.txt | 11 +++++------ Documentation/gitignore.txt | 8 ++++++++ 3 files changed, 13 insertions(+), 15 deletions(-)
Signature · 1 line
2.21.0.368.gbf248417d7
PATCH v3 1/2 git-clean.txt: clarify ignore pattern files
In the git-clean documentation, -x and -e documented .gitignore, $GIT_DIR/info/excludes but neglected to mention the file pointed to by core.excludesFile.
Remove specific list of files and, instead, reference gitignore(5) documentation so that information is consolidated and the git-clean documentation is more precise.
--- Documentation/git-clean.txt | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-)
Documentation/git-clean.txt +5 -6
@@ -55,14 +55,13 @@ OPTIONS -e <pattern>:: --exclude=<pattern>:: - In addition to those found in .gitignore (per directory) and - $GIT_DIR/info/exclude, also consider these patterns to be in the - set of the ignore rules in effect. + Use the given exclude pattern in addition to the standard ignore rules + (see linkgit:gitignore[5]). -x:: - Don't use the standard ignore rules read from .gitignore (per - directory) and $GIT_DIR/info/exclude, but do still use the ignore - rules given with `-e` options. This allows removing all untracked + Don't use the standard ignore rules (see linkgit:gitignore[5]), but + still use the ignore rules given with `-e` options from the command + line. This allows removing all untracked files, including build products. This can be used (possibly in conjunction with 'git reset') to create a pristine working directory to test a clean build.
Signature · 1 line
2.21.0.368.gbf248417d7
PATCH v3 2/2 Docs: move core.excludesFile from git-add to gitignore
In reply to Denton LiuThere was a section on configuration mentioning core.excludesFile in git-add.txt. However, the core.excludesFile config variable is not exclusive to git-add. Move this description to gitignore.txt to be more generic.
--- Documentation/git-add.txt | 9 --------- Documentation/gitignore.txt | 8 ++++++++ 2 files changed, 8 insertions(+), 9 deletions(-)
Documentation/git-add.txt +0 -9
@@ -193,15 +193,6 @@ for "git add --no-all <pathspec>...", i.e. ignored removed files. for command-line options). -CONFIGURATION -------------- - -The optional configuration variable `core.excludesFile` indicates a path to a -file containing patterns of file names to exclude from git-add, similar to -$GIT_DIR/info/exclude. Patterns in the exclude file are used in addition to -those in info/exclude. See linkgit:gitignore[5]. - - EXAMPLES --------
Documentation/gitignore.txt +8 -0
@@ -132,6 +132,14 @@ full pathname may have special meaning: - Other consecutive asterisks are considered regular asterisks and will match according to the previous rules. +CONFIGURATION +------------- + +The optional configuration variable `core.excludesFile` indicates a path to a +file containing patterns of file names to exclude, similar to +`$GIT_DIR/info/exclude`. Patterns in the exclude file are used in addition to +those in `$GIT_DIR/info/exclude`. + NOTES -----
Signature · 1 line
2.21.0.368.gbf248417d7
Re: [PATCH v3 2/2] Docs: move core.excludesFile from git-add to gitignore
Quoted 5 lines · Denton Liu
There was a section on configuration mentioning core.excludesFile in git-add.txt. However, the core.excludesFile config variable is not exclusive to git-add. Move this description to gitignore.txt to be more generic.
---
I'll forge your sign-off and queue it like so. Thanks.
-- >8 --
From: Denton Liu <[email protected]>
Date: Thu, 7 Mar 2019 00:25:30 -0800
Subject: [PATCH] docs: move core.excludesFile from git-add to gitignore
A section in "git add" documentation mentions core.excludesFile and explains how it works, but this is not specific to the command.
Move this description to gitignore.txt to be more generic.
--- Documentation/git-add.txt | 9 --------- Documentation/gitignore.txt | 8 ++++++++ 2 files changed, 8 insertions(+), 9 deletions(-)