Re: Fwd: Unexpected behavior of ls-files command when using --others --exclude-from, and a .gitignore file which resides in a subdirectory
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Jan 24, 2024, 17:06 UTC
- Message-ID
- <xmqqjznyhd90.fsf@gitster.g>
- In-Reply-To
- <CABPp-BHcdn3+mbPJk8LZvMjPWZ4s-xdUyevrMbgbT4yQpJ_umA@mail.gmail.com>
Elijah Newren <newren@gmail.com> writes:
Show 9 quoted lines
> It can also imply that a feature, design, or practice will be removed > or discontinued entirely in the future. > ``` > > Since "can also imply" != "does also imply", and based on the commit > message of 491a7575f (particularly the part that quotes dcf0c16ef1, > both of which were prior work that informed the under discussion > e750951e74), I thought the use of deprecated was perfectly applicable > here.
I think we've seen confusions before, more than just once in the past, caused by the verb "deprecate" in our docs. People, after reading "X is deprecated; use Y instead", always assumed that X will eventually be removed, even in contexts where we did not mean it.
------ >8 ----------- >8 ----------- >8 ----------- >8 ------ Subject: ls-files: avoid the verb "deprecate" for individual options
When e750951e74f updated the documentation to give greater visibility to the --exclude-standard option, it marked the `--exclude-per-directory` option as "deprecated". While it technically is correct that being deprecated does not necessarily mean it is planned to be removed later, it seems to cause confusion to readers, especially when we merely mean
The option Y can be used to achieve the same thing as the option
X, so to those of you who aren't familiar with either X or Y, we
would recommend to use Y.This is especially true for `--exclude-standard` vs the combination of more granular `--exclude-from` and `--exclude-per-directory` options. It is true that one common combination of the granular options can be obtained by just giving the former, but that does not necessarily mean a more granular control is not necessary.
State why we recommend looking at `--exclude-standard` when we do so in the description of `--exclude-per-directory`, instead of saying that the option is deprecated. Also, spell out the recipe to emulate what `--exclude-standard` does, so that the users can give it minute tweaks (like "not reading the global exclusion file from core.excludes").
Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/git-ls-files.txt | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-)
diff --git c/Documentation/git-ls-files.txt w/Documentation/git-ls-files.txt index f65a8cd91d..93a0111cfb 100644 --- c/Documentation/git-ls-files.txt +++ w/Documentation/git-ls-files.txt @@ -119,8 +119,10 @@ OPTIONS --exclude-per-directory=<file>:: Read additional exclude patterns that apply only to the - directory and its subdirectories in <file>. Deprecated; use - --exclude-standard instead. + directory and its subdirectories in <file>. If you are + trying to emulate the way how Porcelain commands work, + using the `--exclude-standard` instead is easier and more + thorough. --exclude-standard:: Add the standard Git exclusions: .git/info/exclude, .gitignore @@ -298,9 +300,8 @@ traversing the directory tree and finding files to show when the flags --others or --ignored are specified. linkgit:gitignore[5] specifies the format of exclude patterns. -Generally, you should just use --exclude-standard, but for historical -reasons the exclude patterns can be specified from the following -places, in order: +These exclude patterns can be specified from the following places, +in order: 1. The command-line flag --exclude=<pattern> specifies a single pattern. Patterns are ordered in the same order @@ -322,6 +323,19 @@ top of the directory tree. A pattern read from a file specified by --exclude-per-directory is relative to the directory that the pattern file appears in. +Generally, you should be able to use `--exclude-standard` when you +want the exclude rules applied the same way as what Porcelain +commands do. To emulate what `--exclude-standard` specifies, you +can give `--exclude-per-directory=.gitignore`, and then specify: + + 1. The file specified by the `core.excludesfile` configuration + variable, if exists, or the `$XDG_CONFIG_HOME/git/ignore` file. + + 2. The `$GIT_DIR/info/exclude` file + +via the `--exclude-from=` option. + + SEE ALSO -------- linkgit:git-read-tree[1], linkgit:gitignore[5]