[PATCH 0/1] update git-clean.txt

[PATCH 0/1] update git-clean.txt

[Denton Liu]

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/alpine.LFD.2.21.1902231328560.2222@localhost.localdomain/

Denton Liu (1):
  git-clean.txt: specify core.excludesFile variable is used

 Documentation/git-clean.txt | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

-- 
2.21.0.317.g7f43cb445c

[PATCH 1/1] git-clean.txt: specify core.excludesFile variable is used

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

Explicitly mention that variable so that the list is exhaustive.

Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/git-clean.txt | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 03056dad0d..c6023b742c 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -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
-- 
2.21.0.317.g7f43cb445c

Re: [PATCH 1/1] git-clean.txt: specify core.excludesFile variable is used

[Martin Ågren]

On Wed, 6 Mar 2019 at 12:17, Denton Liu <liu.denton@gmail.com> wrote:
>
> 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.

> Explicitly mention that variable so that the list is exhaustive.

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

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?

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

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

[Junio C Hamano]

Martin Ågren <martin.agren@gmail.com> writes:

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

[PATCH v2 0/1] make git-clean.txt more precise

[Denton Liu]

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/alpine.LFD.2.21.1902231328560.2222@localhost.localdomain/

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

-- 
2.21.0.368.gbf248417d7

[PATCH v2 1/1] git-clean.txt: clarify ignore pattern files

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

Remove specific list of files and, instead, reference gitignore(5)
documentation so that information is consolidated and the git-clean
documentation is more precise.

Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
Helped-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/git-clean.txt | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 03056dad0d..d251ef9dd2 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -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
-- 
2.21.0.368.gbf248417d7

Re: [PATCH v2 1/1] git-clean.txt: clarify ignore pattern files

[Junio C Hamano]

Denton Liu <liu.denton@gmail.com> writes:

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

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

[Martin Ågren]

On Thu, 7 Mar 2019 at 07:57, Junio C Hamano <gitster@pobox.com> wrote:
>
> Denton Liu <liu.denton@gmail.com> writes:
>
> > +     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.
>
>     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.

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

[Junio C Hamano]

Martin Ågren <martin.agren@gmail.com> writes:

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

[PATCH v3 0/2] consolidate core.excludesFile docs

[Denton Liu]

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/alpine.LFD.2.21.1902231328560.2222@localhost.localdomain/

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

-- 
2.21.0.368.gbf248417d7

[PATCH v3 1/2] git-clean.txt: clarify ignore pattern files

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

Remove specific list of files and, instead, reference gitignore(5)
documentation so that information is consolidated and the git-clean
documentation is more precise.

Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
Helped-by: Martin Ågren <martin.agren@gmail.com>
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/git-clean.txt | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 03056dad0d..db876f7dde 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -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.
-- 
2.21.0.368.gbf248417d7

[PATCH v3 2/2] Docs: move core.excludesFile from git-add to gitignore

[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.
---
 Documentation/git-add.txt   | 9 ---------
 Documentation/gitignore.txt | 8 ++++++++
 2 files changed, 8 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 37bcab94d5..8b0e4c7fa8 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -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
 --------
 
diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 1c94f08ff4..b5bc9dbff0 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -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
 -----
 
-- 
2.21.0.368.gbf248417d7

Re: [PATCH v3 2/2] Docs: move core.excludesFile from git-add to gitignore

[Junio C Hamano]

Denton Liu <liu.denton@gmail.com> writes:

> 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 <liu.denton@gmail.com>
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.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-add.txt   | 9 ---------
 Documentation/gitignore.txt | 8 ++++++++
 2 files changed, 8 insertions(+), 9 deletions(-)