[0/4] clarify ls-files docs

Message

Philippe Blain via GitGitGadget Jan. 13, 2023, 4:41 a.m. UTC

"git ls-files -t" was marked as semi-deprecated back in 5bc0e247c4
("Document ls-files -t as semi-obsolete.", 2010-07-28); quoting that commit
message:

    git ls-files -t" is [...] badly documented, hence we point the
    users to superior alternatives.

    The feature is marked as "semi-obsolete" but not "scheduled for removal"
    since it's a plumbing command, scripts might use it, and Git testsuite
    already uses it to test the state of the index.


Looking over the manual, "git ls-files -t" is very easy to
misunderstand...as are several things besides the "-t" option within that
manual page. I recall a number of discussions over the years on the mailing
list about various confusing aspects of ls-files, and I think a number of
those misunderstandings could have been avoided with a few small
clarifications. This series sets about to do that, as well as remove the
"semi-deprecated" notice on git ls-files -t. That particular command is
rather integral to sparse-checkout usage (and doesn't seem to confuse in
that case), and I think the improvements avoid the original problems.
However, I have kept the comments about git status --porcelain and such
being likely better candidates for a number of things that git ls-files -t
might have historically been used for.

Series spurred by
https://lore.kernel.org/git/CABPp-BGsD=[e-mail]/

Elijah Newren (4):
  ls-files: add missing documentation for --resolve-undo option
  ls-files: clarify descriptions of file selection options
  ls-files: clarify descriptions of status tags for -t
  ls-files: guide folks to --exclude-standard over other --exclude*
    options

 Documentation/git-ls-files.txt | 79 ++++++++++++++++++++++------------
 1 file changed, 52 insertions(+), 27 deletions(-)


base-commit: 2b4f5a4e4bb102ac8d967cea653ed753b608193c
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1463%2Fnewren%2Fls-files-docs-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1463/newren/ls-files-docs-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1463