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

["Martin Ågren" <martin.agren@gmail.com>]

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