clarify ls-files docs
Get series with b4
b4 am [email protected]Versions newest first
- v1 Latest4 patches 7 repliesIn review
Patches in v1 No applies recorded yet
| # | Subject and files | Size | Replies | Applied |
|---|---|---|---|---|
| 1/4 | ls-files: add missing documentation for --resolve-undo optionDocumentation/ | +9 | 1 reply | |
| 2/4 | ls-files: clarify descriptions of file selection optionsDocumentation/ | +24 | 3 replies | |
| 3/4 | ls-files: clarify descriptions of status tags for -tDocumentation/ | +15 | 3 replies | |
| 4/4 | ls-files: guide folks to --exclude-standard over other --exclude* optionsDocumentation/ | +5 | 0 replies |
Reviews trailers per patch
No Reviewed-by, Acked-by or Tested-by trailers for v1 yet.
Cover letter [PATCH 0/4] clarify ls-files docs
"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=6PiJtnsuYPsiZJ1rm2X8yTeu-YeP4q5uu5UDw2og@mail.gmail.com/
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
Signature · 1 line
gitgitgadget