]> git.ipfire.org Git - thirdparty/git.git/commit
ls-files: avoid the verb "deprecate" for individual options
authorJunio C Hamano <gitster@pobox.com>
Wed, 24 Jan 2024 21:10:31 +0000 (13:10 -0800)
committerJunio C Hamano <gitster@pobox.com>
Thu, 25 Jan 2024 18:55:53 +0000 (10:55 -0800)
commit0009542cabb808f558605f0faa8c57d3b97ed055
tree871d20189f5aa5d210debf5dda852aa883b2eb38
parent564d0252ca632e0264ed670534a51d18a689ef5d
ls-files: avoid the verb "deprecate" for individual options

When e750951e (ls-files: guide folks to --exclude-standard over
other --exclude* options, 2023-01-13) updated the documentation to
give greater visibility to the `--exclude-standard` option, it marked
the `--exclude-per-directory` option as "deprecated".

While it is technically 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 much simpler. To those of you who aren't familiar with either
    X or Y, we would recommend to use Y when appropriate.

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 the reason why we recommend readers `--exclude-standard` 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 "do the same as Git Porcelain, except I do not want to
read the global exclusion file from core.excludes").

Signed-off-by: Junio C Hamano <gitster@pobox.com>
Documentation/git-ls-files.txt