[PATCH] Doc: Mention core.excludesFile in "man git-clean"

Robert P. J. Day· May 22, 2018, 07:48 UTC · lore

Add a reference to the configuration setting "core.excludesFile" to the man page for git-clean.

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>

---

Show changes to Documentation/git-clean.txt +6 −4

diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 03056dad0..449cbc2af 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
-	set of the ignore rules in effect.
+	In addition to patterns found in any of .gitignore (per directory),
+	$GIT_DIR/info/exclude and the exclude file specified by the
+	configuration variable core.excludesFile, 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 exclude file specified
+	by core.excludesFile, 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

-- 
========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Junio C Hamano· May 23, 2018, 01:48 UTC · re: Robert P. J. Day · lore

Re: [PATCH] Doc: Mention core.excludesFile in "man git-clean"

"Robert P. J. Day" <rpjday@crashcourse.ca> writes:

Show 6 quoted lines

> Add a reference to the configuration setting "core.excludesFile" to
> the man page for git-clean.
>
> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
>
> ---

I understand that you are trying to reduce the source of the confusion you felt, which comes from mentioning only per-directory .gitignore and per-repository info/exclude, but I am not sure if the proposed solution is a good one that learned from our past mistakes.

Wouldn't it make more sense to _avoid_ appearing as if we are giving a complete list and refer those who want a single authoritative list to the source? For example

	In addition to those found in standard places for exclude
	patterns such as `.gitignore` (cf. linkgit:gitignore[5]),
	also consider these patterns...

After all, having an incomplete list and not hinting that it is incomplete is what made you react to the current description. It is unlikely that we stop treating `.gitignore` as one of the standard places, so phrasing like above will have a lot smaller chance to go stale, even accounting for the possibility that we will grow Git over time and the standard parttern sources may be updated in the future.

Show 25 quoted lines

>
> diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
> index 03056dad0..449cbc2af 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
> -	set of the ignore rules in effect.
> +	In addition to patterns found in any of .gitignore (per directory),
> +	$GIT_DIR/info/exclude and the exclude file specified by the
> +	configuration variable core.excludesFile, 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 exclude file specified
> +	by core.excludesFile, 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

patchDoc: Mention core.excludesFile in "man git-clean"