| Message ID | 26406a4d8797e68f0ba4fe097cf0973f60d67114.1673584914.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | 4173b806c75dbcf4406c7a5ad6158dcbfa2beb2f |
| Headers | show |
| Series | clarify ls-files docs | expand |
Elijah Newren via GitGitGadget <gitgitgadget@gmail.com> 于2023年1月13日周五 12:41写道： > > From: Elijah Newren <newren@gmail.com> > > Much like the file selection options we tweaked in the last commit, the > status tags printed with -t had descriptions that were easy to > misunderstand, and for many of the same reasons. Clarify them. > > Also, while at it, remove the "semi-deprecated" comment for "git > ls-files -t". The -t option was marked as semi-deprecated in 5bc0e247c4 > ("Document ls-files -t as semi-obsolete.", 2010-07-28) because: > > "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. > > Marking it as obsolete because it was easily misunderstood, which I > think was primarily due to documentation problems, is one strategy, but > I think fixing the documentation is a better option. Especially since > in the intervening time, "git ls-files -t" has become heavily used by > sparse-checkout users where the same confusion just doesn't apply. > > Signed-off-by: Elijah Newren <newren@gmail.com> > --- > Documentation/git-ls-files.txt | 28 +++++++++++++++------------- > 1 file changed, 15 insertions(+), 13 deletions(-) > > diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt > index f89ab1bfc98..3886d58d178 100644 > --- a/Documentation/git-ls-files.txt > +++ b/Documentation/git-ls-files.txt > @@ -137,25 +137,27 @@ OPTIONS > with `-s` or `-u` options does not make any sense. > > -t:: > - This feature is semi-deprecated. For scripting purpose, > - linkgit:git-status[1] `--porcelain` and > + Show status tags together with filenames. Note that for > + scripting purposes, linkgit:git-status[1] `--porcelain` and > linkgit:git-diff-files[1] `--name-status` are almost always > superior alternatives, and users should look at > linkgit:git-status[1] `--short` or linkgit:git-diff[1] > `--name-status` for more user-friendly alternatives. > + > -- > -This option identifies the file status with the following tags (followed by > -a space) at the start of each line: > - > - H:: cached > - S:: skip-worktree > - M:: unmerged > - R:: removed/deleted > - C:: modified/changed > - K:: to be killed > - ?:: other > - U:: resolve-undo > +This option provides a reason for showing each filename, in the form > +of a status tag (which is followed by a space and then the filename). > +The status tags are all single characters from the following list: > + > + H:: tracked file that is not either unmerged or skip-worktree > + S:: tracked file that is skip-worktree > + M:: tracked file that is unmerged > + R:: tracked file with unstaged removal/deletion > + C:: tracked file with unstaged modification/change > + K:: untracked paths which are part of file/directory conflicts > + which prevent checking out tracked files > + ?:: untracked file > + U:: file with resolve-undo information > -- > Good to see these tags describe are changed, especially "K" (reader don't know what is "to be killed") Maybe we should mention which option will output these tags? e.g. default -> "H"/"S" ,`--other` -> "?", `--modified` -> "C", `--killed` -> "K"... > -v:: > -- > gitgitgadget >
On Sat, Jan 14, 2023 at 12:27 AM ZheNing Hu <adlternative@gmail.com> wrote: > > Elijah Newren via GitGitGadget <gitgitgadget@gmail.com> 于2023年1月13日周五 12:41写道： > > > > From: Elijah Newren <newren@gmail.com> > > > > Much like the file selection options we tweaked in the last commit, the > > status tags printed with -t had descriptions that were easy to > > misunderstand, and for many of the same reasons. Clarify them. > > > > Also, while at it, remove the "semi-deprecated" comment for "git > > ls-files -t". The -t option was marked as semi-deprecated in 5bc0e247c4 > > ("Document ls-files -t as semi-obsolete.", 2010-07-28) because: > > > > "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. > > > > Marking it as obsolete because it was easily misunderstood, which I > > think was primarily due to documentation problems, is one strategy, but > > I think fixing the documentation is a better option. Especially since > > in the intervening time, "git ls-files -t" has become heavily used by > > sparse-checkout users where the same confusion just doesn't apply. > > > > Signed-off-by: Elijah Newren <newren@gmail.com> > > --- > > Documentation/git-ls-files.txt | 28 +++++++++++++++------------- > > 1 file changed, 15 insertions(+), 13 deletions(-) > > > > diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt > > index f89ab1bfc98..3886d58d178 100644 > > --- a/Documentation/git-ls-files.txt > > +++ b/Documentation/git-ls-files.txt > > @@ -137,25 +137,27 @@ OPTIONS > > with `-s` or `-u` options does not make any sense. > > > > -t:: > > - This feature is semi-deprecated. For scripting purpose, > > - linkgit:git-status[1] `--porcelain` and > > + Show status tags together with filenames. Note that for > > + scripting purposes, linkgit:git-status[1] `--porcelain` and > > linkgit:git-diff-files[1] `--name-status` are almost always > > superior alternatives, and users should look at > > linkgit:git-status[1] `--short` or linkgit:git-diff[1] > > `--name-status` for more user-friendly alternatives. > > + > > -- > > -This option identifies the file status with the following tags (followed by > > -a space) at the start of each line: > > - > > - H:: cached > > - S:: skip-worktree > > - M:: unmerged > > - R:: removed/deleted > > - C:: modified/changed > > - K:: to be killed > > - ?:: other > > - U:: resolve-undo > > +This option provides a reason for showing each filename, in the form > > +of a status tag (which is followed by a space and then the filename). > > +The status tags are all single characters from the following list: > > + > > + H:: tracked file that is not either unmerged or skip-worktree > > + S:: tracked file that is skip-worktree > > + M:: tracked file that is unmerged > > + R:: tracked file with unstaged removal/deletion > > + C:: tracked file with unstaged modification/change > > + K:: untracked paths which are part of file/directory conflicts > > + which prevent checking out tracked files > > + ?:: untracked file > > + U:: file with resolve-undo information > > -- > > > > Good to see these tags describe are changed, especially "K" (reader > don't know what is "to be killed") > > Maybe we should mention which option will output these tags? > e.g. default -> "H"/"S" ,`--other` -> "?", `--modified` -> "C", > `--killed` -> "K"... We could, but... * It's H/S/M, not just H/S that is shown by default. * It gets weird because other options aren't added to the default, so if someone specifies "-m" then suddenly H/S/M go away...unless they also specify "-c". Trying to explain all that feels like we're getting close to repeating the documentation of the individual options. But maybe we could just ignore everything around default behavior and find a way to be brief such as with: Note that H, S, and M entries are shown with --cached; R entries are shown with --deleted, C entries are shown with --modified, K entries are shown with --killed, ? entries are shown with --others, and U entries are shown with --resolve-undo. I'm not sure if I like the documentation better with or without this added paragraph. What do others think?
Elijah Newren <newren@gmail.com> 于2023年1月15日周日 04:27写道： > > On Sat, Jan 14, 2023 at 12:27 AM ZheNing Hu <adlternative@gmail.com> wrote: > > > > Elijah Newren via GitGitGadget <gitgitgadget@gmail.com> 于2023年1月13日周五 12:41写道： > > > > > > From: Elijah Newren <newren@gmail.com> > > > > > > Much like the file selection options we tweaked in the last commit, the > > > status tags printed with -t had descriptions that were easy to > > > misunderstand, and for many of the same reasons. Clarify them. > > > > > > Also, while at it, remove the "semi-deprecated" comment for "git > > > ls-files -t". The -t option was marked as semi-deprecated in 5bc0e247c4 > > > ("Document ls-files -t as semi-obsolete.", 2010-07-28) because: > > > > > > "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. > > > > > > Marking it as obsolete because it was easily misunderstood, which I > > > think was primarily due to documentation problems, is one strategy, but > > > I think fixing the documentation is a better option. Especially since > > > in the intervening time, "git ls-files -t" has become heavily used by > > > sparse-checkout users where the same confusion just doesn't apply. > > > > > > Signed-off-by: Elijah Newren <newren@gmail.com> > > > --- > > > Documentation/git-ls-files.txt | 28 +++++++++++++++------------- > > > 1 file changed, 15 insertions(+), 13 deletions(-) > > > > > > diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt > > > index f89ab1bfc98..3886d58d178 100644 > > > --- a/Documentation/git-ls-files.txt > > > +++ b/Documentation/git-ls-files.txt > > > @@ -137,25 +137,27 @@ OPTIONS > > > with `-s` or `-u` options does not make any sense. > > > > > > -t:: > > > - This feature is semi-deprecated. For scripting purpose, > > > - linkgit:git-status[1] `--porcelain` and > > > + Show status tags together with filenames. Note that for > > > + scripting purposes, linkgit:git-status[1] `--porcelain` and > > > linkgit:git-diff-files[1] `--name-status` are almost always > > > superior alternatives, and users should look at > > > linkgit:git-status[1] `--short` or linkgit:git-diff[1] > > > `--name-status` for more user-friendly alternatives. > > > + > > > -- > > > -This option identifies the file status with the following tags (followed by > > > -a space) at the start of each line: > > > - > > > - H:: cached > > > - S:: skip-worktree > > > - M:: unmerged > > > - R:: removed/deleted > > > - C:: modified/changed > > > - K:: to be killed > > > - ?:: other > > > - U:: resolve-undo > > > +This option provides a reason for showing each filename, in the form > > > +of a status tag (which is followed by a space and then the filename). > > > +The status tags are all single characters from the following list: > > > + > > > + H:: tracked file that is not either unmerged or skip-worktree > > > + S:: tracked file that is skip-worktree > > > + M:: tracked file that is unmerged > > > + R:: tracked file with unstaged removal/deletion > > > + C:: tracked file with unstaged modification/change > > > + K:: untracked paths which are part of file/directory conflicts > > > + which prevent checking out tracked files > > > + ?:: untracked file > > > + U:: file with resolve-undo information > > > -- > > > > > > > Good to see these tags describe are changed, especially "K" (reader > > don't know what is "to be killed") > > > > Maybe we should mention which option will output these tags? > > e.g. default -> "H"/"S" ,`--other` -> "?", `--modified` -> "C", > > `--killed` -> "K"... > > We could, but... > > * It's H/S/M, not just H/S that is shown by default. > * It gets weird because other options aren't added to the default, > so if someone specifies "-m" then suddenly H/S/M go away...unless they > also specify "-c". > > Trying to explain all that feels like we're getting close to repeating > the documentation of the individual options. But maybe we could just > ignore everything around default behavior and find a way to be brief > such as with: > > Note that H, S, and M entries are shown with --cached; R entries > are shown with --deleted, C entries are shown with --modified, K > entries are shown with --killed, ? entries are shown with > --others, and U entries are shown with --resolve-undo. > What you mean is that each tag will appear in which commands, rather than each command will have which tags. I think this segment is pretty good. > I'm not sure if I like the documentation better with or without this > added paragraph. What do others think?
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index f89ab1bfc98..3886d58d178 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -137,25 +137,27 @@ OPTIONS with `-s` or `-u` options does not make any sense. -t:: - This feature is semi-deprecated. For scripting purpose, - linkgit:git-status[1] `--porcelain` and + Show status tags together with filenames. Note that for + scripting purposes, linkgit:git-status[1] `--porcelain` and linkgit:git-diff-files[1] `--name-status` are almost always superior alternatives, and users should look at linkgit:git-status[1] `--short` or linkgit:git-diff[1] `--name-status` for more user-friendly alternatives. + -- -This option identifies the file status with the following tags (followed by -a space) at the start of each line: - - H:: cached - S:: skip-worktree - M:: unmerged - R:: removed/deleted - C:: modified/changed - K:: to be killed - ?:: other - U:: resolve-undo +This option provides a reason for showing each filename, in the form +of a status tag (which is followed by a space and then the filename). +The status tags are all single characters from the following list: + + H:: tracked file that is not either unmerged or skip-worktree + S:: tracked file that is skip-worktree + M:: tracked file that is unmerged + R:: tracked file with unstaged removal/deletion + C:: tracked file with unstaged modification/change + K:: untracked paths which are part of file/directory conflicts + which prevent checking out tracked files + ?:: untracked file + U:: file with resolve-undo information -- -v::