{"thread":{"id":"59081","subject":"[PATCH 2/4] ls-files: clarify descriptions of file selection options","startedAt":"2023-01-13T04:42:05Z","lastAt":"2023-01-16T17:43:24Z","messageCount":12,"participants":["Elijah Newren via GitGitGadget","ZheNing Hu","Elijah Newren"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"470237","messageId":"1d1330243109d499d1c07f6518265b2e163406ef.1673584914.git.gitgitgadget@gmail.com","threadId":"59081","inReplyTo":"pull.1463.git.1673584914.gitgitgadget@gmail.com","subject":"[PATCH 2/4] ls-files: clarify descriptions of file selection options","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-01-13T04:41:52Z","receivedAt":"2023-01-13T04:42:05Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nThe previous descriptions of the file selection options were very easy\nto misunderstand. For example:\n\n * \"Show cached files in the output\"\n This could be interpreted as meaning \"show files which have been\n modified and git-add'ed, i.e. files which have cached changes\n relative to HEAD\".\n\n * \"Show deleted files\"\n This could be interpreted as meaning \"for each `git rm $FILE` we\n ran, show me $FILE\"\n\n * \"Show modified files\"\n This could be interpreted as meaning \"show files which have been\n modified and git-add'ed\" or as \"show me files that differ from HEAD\"\n or as \"show me undeleted files different from HEAD\" (given that\n --deleted is a separate option), none of which are correct.\n\nFurther, it's not very clear when some options only modify and/or\noverride other options, as was the case with --ignored, --directory, and\n--unmerged (I've seen folks confused by each of them on the mailing\nlist, sometimes even fellow git developers.)\n\nTweak these definitions, and the one for --killed, to try to make them\nall a bit more clear. Finally, also clarify early on that duplicate\nreports for paths are often expected (both when (a) there are multiple\nentries for the file in the index -- i.e. when there are conflicts, and\nalso (b) when the user specifies options that might pick the same file\nmultiple times, such as `git ls-files --cached --deleted --modified`\nwhen there is a file with an unstaged deletion).\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-ls-files.txt | 37 ++++++++++++++++++++++------------\n 1 file changed, 24 insertions(+), 13 deletions(-)\n\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex cb071583f8b..f89ab1bfc98 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -29,21 +29,26 @@ This merges the file listing in the index with the actual working\n directory list, and shows different combinations of the two.\n \n One or more of the options below may be used to determine the files\n-shown:\n+shown, and each file may be printed multiple times if there are\n+multiple entries in the index or multiple statuses are applicable for\n+the relevant file selection options.\n \n OPTIONS\n -------\n -c::\n --cached::\n-\tShow cached files in the output (default)\n+\tShow all files cached in Git's index, i.e. all tracked files.\n+\t(This is the default if no -c/-s/-d/-o/-u/-k/-m/--resolve-undo\n+\toptions are specified.)\n \n -d::\n --deleted::\n-\tShow deleted files in the output\n+\tShow files with an unstaged deletion\n \n -m::\n --modified::\n-\tShow modified files in the output\n+\tShow files with an unstaged modification (note that an unstaged\n+\tdeletion also counts as an unstaged modification)\n \n -o::\n --others::\n@@ -51,11 +56,14 @@ OPTIONS\n \n -i::\n --ignored::\n-\tShow only ignored files in the output. When showing files in the\n-\tindex, print only those matched by an exclude pattern. When\n-\tshowing \"other\" files, show only those matched by an exclude\n-\tpattern. Standard ignore rules are not automatically activated,\n-\ttherefore at least one of the `--exclude*` options is required.\n+\tShow only ignored files in the output. Must be used with\n+\teither an explicit '-c' or '-o'. When showing files in the\n+\tindex (i.e. when used with '-c'), print only those files\n+\tmatching an exclude pattern. When showing \"other\" files\n+\t(i.e. when used with '-o'), show only those matched by an\n+\texclude pattern. Standard ignore rules are not automatically\n+\tactivated, therefore at least one of the `--exclude*` options\n+\tis required.\n \n -s::\n --stage::\n@@ -64,19 +72,22 @@ OPTIONS\n --directory::\n \tIf a whole directory is classified as \"other\", show just its\n \tname (with a trailing slash) and not its whole contents.\n+\tHas no effect without -o/--others.\n \n --no-empty-directory::\n \tDo not list empty directories. Has no effect without --directory.\n \n -u::\n --unmerged::\n-\tShow unmerged files in the output (forces --stage)\n+\tShow information about unmerged files in the output, but do\n+\tnot show any other tracked files (forces --stage, overrides\n+\t--cached).\n \n -k::\n --killed::\n-\tShow files on the filesystem that need to be removed due\n-\tto file/directory conflicts for checkout-index to\n-\tsucceed.\n+\tShow untracked files on the filesystem that need to be removed\n+\tdue to file/directory conflicts for tracked files to be able to\n+\tbe written to the filesystem.\n \n --resolve-undo::\n \tShow files having resolve-undo information in the index\n-- \ngitgitgadget\n\n"},{"id":"470238","messageId":"pull.1463.git.1673584914.gitgitgadget@gmail.com","threadId":"59081","inReplyTo":null,"subject":"[PATCH 0/4] clarify ls-files docs","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-01-13T04:41:50Z","receivedAt":"2023-01-13T04:42:08Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"\"git ls-files -t\" was marked as semi-deprecated back in 5bc0e247c4\n(\"Document ls-files -t as semi-obsolete.\", 2010-07-28); quoting that commit\nmessage:\n\n git ls-files -t\" is [...] badly documented, hence we point the\n    users to superior alternatives.\n\n The feature is marked as \"semi-obsolete\" but not \"scheduled for removal\"\n since it's a plumbing command, scripts might use it, and Git testsuite\n already uses it to test the state of the index.\n\n\nLooking over the manual, \"git ls-files -t\" is very easy to\nmisunderstand...as are several things besides the \"-t\" option within that\nmanual page. I recall a number of discussions over the years on the mailing\nlist about various confusing aspects of ls-files, and I think a number of\nthose misunderstandings could have been avoided with a few small\nclarifications. This series sets about to do that, as well as remove the\n\"semi-deprecated\" notice on git ls-files -t. That particular command is\nrather integral to sparse-checkout usage (and doesn't seem to confuse in\nthat case), and I think the improvements avoid the original problems.\nHowever, I have kept the comments about git status --porcelain and such\nbeing likely better candidates for a number of things that git ls-files -t\nmight have historically been used for.\n\nSeries spurred by\nhttps://lore.kernel.org/git/CABPp-BGsD=6PiJtnsuYPsiZJ1rm2X8yTeu-YeP4q5uu5UDw2og@mail.gmail.com/\n\nElijah Newren (4):\n ls-files: add missing documentation for --resolve-undo option\n ls-files: clarify descriptions of file selection options\n ls-files: clarify descriptions of status tags for -t\n ls-files: guide folks to --exclude-standard over other --exclude*\n options\n\n Documentation/git-ls-files.txt | 79 ++++++++++++++++++++++------------\n 1 file changed, 52 insertions(+), 27 deletions(-)\n\n\nbase-commit: 2b4f5a4e4bb102ac8d967cea653ed753b608193c\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1463%2Fnewren%2Fls-files-docs-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1463/newren/ls-files-docs-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1463\n-- \ngitgitgadget\n"},{"id":"470239","messageId":"6bd92c51550c4960ee4de272d3b19451f1e337cc.1673584914.git.gitgitgadget@gmail.com","threadId":"59081","inReplyTo":"pull.1463.git.1673584914.gitgitgadget@gmail.com","subject":"[PATCH 1/4] ls-files: add missing documentation for --resolve-undo option","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-01-13T04:41:51Z","receivedAt":"2023-01-13T04:42:14Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nls-files' --resolve-undo option has existed ever since 9d9a2f4aba\n(\"resolve-undo: basic tests\", 2009-12-25), but was never documented.\nHowever, the option has been referred to in the ls-files manual itself\never since ce74de931d (\"ls-files: introduce \"--format\" option\",\n2022-07-23), making its omission a bit jarring. Document this option.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-ls-files.txt | 9 +++++++++\n 1 file changed, 9 insertions(+)\n\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 440043cdb8e..cb071583f8b 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -12,6 +12,7 @@ SYNOPSIS\n 'git ls-files' [-z] [-t] [-v] [-f]\n \t\t[-c|--cached] [-d|--deleted] [-o|--others] [-i|--ignored]\n \t\t[-s|--stage] [-u|--unmerged] [-k|--killed] [-m|--modified]\n+\t\t[--resolve-undo]\n \t\t[--directory [--no-empty-directory]] [--eol]\n \t\t[--deduplicate]\n \t\t[-x |--exclude=]\n@@ -77,6 +78,13 @@ OPTIONS\n \tto file/directory conflicts for checkout-index to\n \tsucceed.\n \n+--resolve-undo::\n+\tShow files having resolve-undo information in the index\n+\ttogether with their resolve-undo information. (resolve-undo\n+\tinformation is what is used to implement \"git checkout -m\n+\t$PATH\", i.e. to recreate merge conflicts that were\n+\taccidentally resolved)\n+\n -z::\n \t\\0 line termination on output and do not quote filenames.\n \tSee OUTPUT below for more information.\n@@ -136,6 +144,7 @@ a space) at the start of each line:\n \tC::\tmodified/changed\n \tK::\tto be killed\n \t?::\tother\n+\tU:: resolve-undo\n --\n \n -v::\n-- \ngitgitgadget\n\n"},{"id":"470240","messageId":"26406a4d8797e68f0ba4fe097cf0973f60d67114.1673584914.git.gitgitgadget@gmail.com","threadId":"59081","inReplyTo":"pull.1463.git.1673584914.gitgitgadget@gmail.com","subject":"[PATCH 3/4] ls-files: clarify descriptions of status tags for -t","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-01-13T04:41:53Z","receivedAt":"2023-01-13T04:42:19Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nMuch like the file selection options we tweaked in the last commit, the\nstatus tags printed with -t had descriptions that were easy to\nmisunderstand, and for many of the same reasons. Clarify them.\n\nAlso, while at it, remove the \"semi-deprecated\" comment for \"git\nls-files -t\". The -t option was marked as semi-deprecated in 5bc0e247c4\n(\"Document ls-files -t as semi-obsolete.\", 2010-07-28) because:\n\n    \"git ls-files -t\" is [...] badly documented, hence we point the\n    users to superior alternatives.\n    The feature is marked as \"semi-obsolete\" but not \"scheduled for removal\"\n    since it's a plumbing command, scripts might use it, and Git testsuite\n    already uses it to test the state of the index.\n\nMarking it as obsolete because it was easily misunderstood, which I\nthink was primarily due to documentation problems, is one strategy, but\nI think fixing the documentation is a better option. Especially since\nin the intervening time, \"git ls-files -t\" has become heavily used by\nsparse-checkout users where the same confusion just doesn't apply.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-ls-files.txt | 28 +++++++++++++++-------------\n 1 file changed, 15 insertions(+), 13 deletions(-)\n\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex f89ab1bfc98..3886d58d178 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -137,25 +137,27 @@ OPTIONS\n \twith `-s` or `-u` options does not make any sense.\n \n -t::\n-\tThis feature is semi-deprecated. For scripting purpose,\n-\tlinkgit:git-status[1] `--porcelain` and\n+\tShow status tags together with filenames. Note that for\n+\tscripting purposes, linkgit:git-status[1] `--porcelain` and\n \tlinkgit:git-diff-files[1] `--name-status` are almost always\n \tsuperior alternatives, and users should look at\n \tlinkgit:git-status[1] `--short` or linkgit:git-diff[1]\n \t`--name-status` for more user-friendly alternatives.\n +\n --\n-This option identifies the file status with the following tags (followed by\n-a space) at the start of each line:\n-\n-\tH::\tcached\n-\tS::\tskip-worktree\n-\tM::\tunmerged\n-\tR::\tremoved/deleted\n-\tC::\tmodified/changed\n-\tK::\tto be killed\n-\t?::\tother\n-\tU:: resolve-undo\n+This option provides a reason for showing each filename, in the form\n+of a status tag (which is followed by a space and then the filename).\n+The status tags are all single characters from the following list:\n+\n+\tH::\ttracked file that is not either unmerged or skip-worktree\n+\tS::\ttracked file that is skip-worktree\n+\tM::\ttracked file that is unmerged\n+\tR::\ttracked file with unstaged removal/deletion\n+\tC::\ttracked file with unstaged modification/change\n+\tK::\tuntracked paths which are part of file/directory conflicts\n+\t\twhich prevent checking out tracked files\n+\t?::\tuntracked file\n+\tU:: file with resolve-undo information\n --\n \n -v::\n-- \ngitgitgadget\n\n"},{"id":"470241","messageId":"b144d55d111d09f8d54502cee8cc1dfb2401dc95.1673584914.git.gitgitgadget@gmail.com","threadId":"59081","inReplyTo":"pull.1463.git.1673584914.gitgitgadget@gmail.com","subject":"[PATCH 4/4] ls-files: guide folks to --exclude-standard over other --exclude* options","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-01-13T04:41:54Z","receivedAt":"2023-01-13T04:42:35Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-ls-files.txt | 7 +++++--\n 1 file changed, 5 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 3886d58d178..1abdd3c21c5 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -119,7 +119,8 @@ OPTIONS\n \n --exclude-per-directory=::\n \tRead additional exclude patterns that apply only to the\n-\tdirectory and its subdirectories in .\n+\tdirectory and its subdirectories in . Deprecated; use\n+\t--exclude-standard instead.\n \n --exclude-standard::\n \tAdd the standard Git exclusions: .git/info/exclude, .gitignore\n@@ -291,7 +292,9 @@ traversing the directory tree and finding files to show when the\n flags --others or --ignored are specified. linkgit:gitignore[5]\n specifies the format of exclude patterns.\n \n-These exclude patterns come from these places, in order:\n+Generally, you should just use --exclude-standard, but for historical\n+reasons the exclude patterns can be specified from the following\n+places, in order:\n \n 1. The command-line flag --exclude= specifies a\n single pattern. Patterns are ordered in the same order\n-- \ngitgitgadget\n"},{"id":"470323","messageId":"CAOLTT8TS+8gM0c1WhZJTz22ZV=PzCSTwZTn4jYAgmjoNMVG=Hg@mail.gmail.com","threadId":"59081","inReplyTo":"6bd92c51550c4960ee4de272d3b19451f1e337cc.1673584914.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/4] ls-files: add missing documentation for --resolve-undo option","fromName":"ZheNing Hu","fromEmail":"adlternative@gmail.com","sentAt":"2023-01-14T08:07:35Z","receivedAt":"2023-01-14T08:07:52Z","isPatch":true,"sender":{"key":"adlternative@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58138461?v=4"},"body":"Elijah Newren via GitGitGadget 于2023年1月13日周五 12:41写道：\n\n>\n> From: Elijah Newren \n>\n> ls-files' --resolve-undo option has existed ever since 9d9a2f4aba\n> (\"resolve-undo: basic tests\", 2009-12-25), but was never documented.\n> However, the option has been referred to in the ls-files manual itself\n> ever since ce74de931d (\"ls-files: introduce \"--format\" option\",\n> 2022-07-23), making its omission a bit jarring. Document this option.\n>\n\nI checked this should be the only option that git ls-files forgot to\ndocument, thanks.\n\n> Signed-off-by: Elijah Newren \n> ---\n> Documentation/git-ls-files.txt | 9 +++++++++\n> 1 file changed, 9 insertions(+)\n>\n> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\n> index 440043cdb8e..cb071583f8b 100644\n> --- a/Documentation/git-ls-files.txt\n> +++ b/Documentation/git-ls-files.txt\n> @@ -12,6 +12,7 @@ SYNOPSIS\n> 'git ls-files' [-z] [-t] [-v] [-f]\n> [-c|--cached] [-d|--deleted] [-o|--others] [-i|--ignored]\n> [-s|--stage] [-u|--unmerged] [-k|--killed] [-m|--modified]\n> + [--resolve-undo]\n> [--directory [--no-empty-directory]] [--eol]\n> [--deduplicate]\n> [-x |--exclude=]\n> @@ -77,6 +78,13 @@ OPTIONS\n> to file/directory conflicts for checkout-index to\n> succeed.\n>\n> +--resolve-undo::\n> + Show files having resolve-undo information in the index\n> + together with their resolve-undo information. (resolve-undo\n> + information is what is used to implement \"git checkout -m\n> + $PATH\", i.e. to recreate merge conflicts that were\n> + accidentally resolved)\n> +\n> -z::\n> \\0 line termination on output and do not quote filenames.\n> See OUTPUT below for more information.\n> @@ -136,6 +144,7 @@ a space) at the start of each line:\n> C:: modified/changed\n> K:: to be killed\n> ?:: other\n> + U:: resolve-undo\n> --\n>\n> -v::\n> --\n> gitgitgadget\n>\n"},{"id":"470324","messageId":"CAOLTT8Qx6chcA7MEY9Hzeq9U5pfR-fC8aOxhZMvYvi8ZtQeVdA@mail.gmail.com","threadId":"59081","inReplyTo":"1d1330243109d499d1c07f6518265b2e163406ef.1673584914.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 2/4] ls-files: clarify descriptions of file selection options","fromName":"ZheNing Hu","fromEmail":"adlternative@gmail.com","sentAt":"2023-01-14T08:21:14Z","receivedAt":"2023-01-14T08:21:59Z","isPatch":true,"sender":{"key":"adlternative@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58138461?v=4"},"body":"Elijah Newren via GitGitGadget 于2023年1月13日周五 12:41写道：\n>\n> From: Elijah Newren \n>\n> The previous descriptions of the file selection options were very easy\n> to misunderstand. For example:\n>\n> * \"Show cached files in the output\"\n> This could be interpreted as meaning \"show files which have been\n> modified and git-add'ed, i.e. files which have cached changes\n> relative to HEAD\".\n>\n> * \"Show deleted files\"\n> This could be interpreted as meaning \"for each `git rm $FILE` we\n> ran, show me $FILE\"\n>\n> * \"Show modified files\"\n> This could be interpreted as meaning \"show files which have been\n> modified and git-add'ed\" or as \"show me files that differ from HEAD\"\n> or as \"show me undeleted files different from HEAD\" (given that\n> --deleted is a separate option), none of which are correct.\n>\n> Further, it's not very clear when some options only modify and/or\n> override other options, as was the case with --ignored, --directory, and\n> --unmerged (I've seen folks confused by each of them on the mailing\n> list, sometimes even fellow git developers.)\n>\n> Tweak these definitions, and the one for --killed, to try to make them\n> all a bit more clear. Finally, also clarify early on that duplicate\n> reports for paths are often expected (both when (a) there are multiple\n> entries for the file in the index -- i.e. when there are conflicts, and\n> also (b) when the user specifies options that might pick the same file\n> multiple times, such as `git ls-files --cached --deleted --modified`\n> when there is a file with an unstaged deletion).\n>\n> Signed-off-by: Elijah Newren \n> ---\n> Documentation/git-ls-files.txt | 37 ++++++++++++++++++++++------------\n> 1 file changed, 24 insertions(+), 13 deletions(-)\n>\n> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\n> index cb071583f8b..f89ab1bfc98 100644\n> --- a/Documentation/git-ls-files.txt\n> +++ b/Documentation/git-ls-files.txt\n> @@ -29,21 +29,26 @@ This merges the file listing in the index with the actual working\n> directory list, and shows different combinations of the two.\n>\n> One or more of the options below may be used to determine the files\n> -shown:\n> +shown, and each file may be printed multiple times if there are\n> +multiple entries in the index or multiple statuses are applicable for\n> +the relevant file selection options.\n>\n\n`--deduplicate` option can be used to remove deduped output.\n\n> OPTIONS\n> -------\n> -c::\n> --cached::\n> - Show cached files in the output (default)\n> + Show all files cached in Git's index, i.e. all tracked files.\n> + (This is the default if no -c/-s/-d/-o/-u/-k/-m/--resolve-undo\n> + options are specified.)\n>\n> -d::\n> --deleted::\n> - Show deleted files in the output\n> + Show files with an unstaged deletion\n>\n\nThis is a nice fix: make it clear to the user that only files in the\nworking tree are deleted, not in the index.\n\n> -m::\n> --modified::\n> - Show modified files in the output\n> + Show files with an unstaged modification (note that an unstaged\n> + deletion also counts as an unstaged modification)\n>\n\nGood to mention that deleted files are also modified, otherwise no one\nlooking at the documentation would know that.\n\n> -o::\n> --others::\n> @@ -51,11 +56,14 @@ OPTIONS\n>\n> -i::\n> --ignored::\n> - Show only ignored files in the output. When showing files in the\n> - index, print only those matched by an exclude pattern. When\n> - showing \"other\" files, show only those matched by an exclude\n> - pattern. Standard ignore rules are not automatically activated,\n> - therefore at least one of the `--exclude*` options is required.\n> + Show only ignored files in the output. Must be used with\n> + either an explicit '-c' or '-o'. When showing files in the\n> + index (i.e. when used with '-c'), print only those files\n> + matching an exclude pattern. When showing \"other\" files\n> + (i.e. when used with '-o'), show only those matched by an\n> + exclude pattern. Standard ignore rules are not automatically\n> + activated, therefore at least one of the `--exclude*` options\n> + is required.\n>\n> -s::\n> --stage::\n> @@ -64,19 +72,22 @@ OPTIONS\n> --directory::\n> If a whole directory is classified as \"other\", show just its\n> name (with a trailing slash) and not its whole contents.\n> + Has no effect without -o/--others.\n>\n> --no-empty-directory::\n> Do not list empty directories. Has no effect without --directory.\n>\n> -u::\n> --unmerged::\n> - Show unmerged files in the output (forces --stage)\n> + Show information about unmerged files in the output, but do\n> + not show any other tracked files (forces --stage, overrides\n> + --cached).\n>\n> -k::\n> --killed::\n> - Show files on the filesystem that need to be removed due\n> - to file/directory conflicts for checkout-index to\n> - succeed.\n> + Show untracked files on the filesystem that need to be removed\n> + due to file/directory conflicts for tracked files to be able to\n> + be written to the filesystem.\n>\n> --resolve-undo::\n> Show files having resolve-undo information in the index\n> --\n> gitgitgadget\n>\n"},{"id":"470327","messageId":"CAOLTT8RXgw0CC7TBUunCPnnk1=5gKkyYZcFQyWu29QM9bn9s9w@mail.gmail.com","threadId":"59081","inReplyTo":"26406a4d8797e68f0ba4fe097cf0973f60d67114.1673584914.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 3/4] ls-files: clarify descriptions of status tags for -t","fromName":"ZheNing Hu","fromEmail":"adlternative@gmail.com","sentAt":"2023-01-14T08:26:55Z","receivedAt":"2023-01-14T08:28:00Z","isPatch":true,"sender":{"key":"adlternative@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58138461?v=4"},"body":"Elijah Newren via GitGitGadget 于2023年1月13日周五 12:41写道：\n>\n> From: Elijah Newren \n>\n> Much like the file selection options we tweaked in the last commit, the\n> status tags printed with -t had descriptions that were easy to\n> misunderstand, and for many of the same reasons. Clarify them.\n>\n> Also, while at it, remove the \"semi-deprecated\" comment for \"git\n> ls-files -t\". The -t option was marked as semi-deprecated in 5bc0e247c4\n> (\"Document ls-files -t as semi-obsolete.\", 2010-07-28) because:\n>\n> \"git ls-files -t\" is [...] badly documented, hence we point the\n> users to superior alternatives.\n> The feature is marked as \"semi-obsolete\" but not \"scheduled for removal\"\n> since it's a plumbing command, scripts might use it, and Git testsuite\n> already uses it to test the state of the index.\n>\n> Marking it as obsolete because it was easily misunderstood, which I\n> think was primarily due to documentation problems, is one strategy, but\n> I think fixing the documentation is a better option. Especially since\n> in the intervening time, \"git ls-files -t\" has become heavily used by\n> sparse-checkout users where the same confusion just doesn't apply.\n>\n> Signed-off-by: Elijah Newren \n> ---\n> Documentation/git-ls-files.txt | 28 +++++++++++++++-------------\n> 1 file changed, 15 insertions(+), 13 deletions(-)\n>\n> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\n> index f89ab1bfc98..3886d58d178 100644\n> --- a/Documentation/git-ls-files.txt\n> +++ b/Documentation/git-ls-files.txt\n> @@ -137,25 +137,27 @@ OPTIONS\n> with `-s` or `-u` options does not make any sense.\n>\n> -t::\n> - This feature is semi-deprecated. For scripting purpose,\n> - linkgit:git-status[1] `--porcelain` and\n> + Show status tags together with filenames. Note that for\n> + scripting purposes, linkgit:git-status[1] `--porcelain` and\n> linkgit:git-diff-files[1] `--name-status` are almost always\n> superior alternatives, and users should look at\n> linkgit:git-status[1] `--short` or linkgit:git-diff[1]\n> `--name-status` for more user-friendly alternatives.\n> +\n> --\n> -This option identifies the file status with the following tags (followed by\n> -a space) at the start of each line:\n> -\n> - H:: cached\n> - S:: skip-worktree\n> - M:: unmerged\n> - R:: removed/deleted\n> - C:: modified/changed\n> - K:: to be killed\n> - ?:: other\n> - U:: resolve-undo\n> +This option provides a reason for showing each filename, in the form\n> +of a status tag (which is followed by a space and then the filename).\n> +The status tags are all single characters from the following list:\n> +\n> + H:: tracked file that is not either unmerged or skip-worktree\n> + S:: tracked file that is skip-worktree\n> + M:: tracked file that is unmerged\n> + R:: tracked file with unstaged removal/deletion\n> + C:: tracked file with unstaged modification/change\n> + K:: untracked paths which are part of file/directory conflicts\n> + which prevent checking out tracked files\n> + ?:: untracked file\n> + U:: file with resolve-undo information\n> --\n>\n\nGood to see these tags describe are changed, especially \"K\" (reader\ndon't know what is \"to be killed\")\n\nMaybe we should mention which option will output these tags?\ne.g. default -> \"H\"/\"S\" ,`--other` -> \"?\", `--modified` -> \"C\",\n`--killed` -> \"K\"...\n\n> -v::\n> --\n> gitgitgadget\n>\n"},{"id":"470363","messageId":"CABPp-BFuZK2yap_VXWPo8qHvJ+E9V7v2UAZ9tAaQcX8zc-daDA@mail.gmail.com","threadId":"59081","inReplyTo":"CAOLTT8Qx6chcA7MEY9Hzeq9U5pfR-fC8aOxhZMvYvi8ZtQeVdA@mail.gmail.com","subject":"Re: [PATCH 2/4] ls-files: clarify descriptions of file selection options","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2023-01-14T19:42:03Z","receivedAt":"2023-01-14T19:42:22Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Sat, Jan 14, 2023 at 12:21 AM ZheNing Hu wrote:\n>\n> Elijah Newren via GitGitGadget 于2023年1月13日周五 12:41写道：\n[...]\n> > diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\n> > index cb071583f8b..f89ab1bfc98 100644\n> > --- a/Documentation/git-ls-files.txt\n> > +++ b/Documentation/git-ls-files.txt\n> > @@ -29,21 +29,26 @@ This merges the file listing in the index with the actual working\n> > directory list, and shows different combinations of the two.\n> >\n> > One or more of the options below may be used to determine the files\n> > -shown:\n> > +shown, and each file may be printed multiple times if there are\n> > +multiple entries in the index or multiple statuses are applicable for\n> > +the relevant file selection options.\n> >\n>\n> `--deduplicate` option can be used to remove deduped output.\n\nYes, I'm aware.\n\nIf you're suggesting adding this text at this point in the document,\nit occurred to me already, but I chose not to put it here. The reason\nis that this is a brief synopsis. The \"relevant file selection\noptions\" of this brief synopsis could also be expanded to mention what\nthey are or what the default selection is or whatever. But folks can\nread on to learn that `deduplicate` can be used to remove duplicate\noptions. Likewise, anyone who reads the text about \"relevant file\nselections\" and wants to learn more is inclined to read on to the\nother options to find out.\n\nIn contrast, no one will be motivated to read on to find out that\nfiles can be printed multiple times if we don't mention it right here.\nAnd they are likely to get confused when it happens, thinking it is a\nbug (in fact, I can point out emails from the archives where that has\nhappened). Without mentioning the possibility of multiple files at\nthis point, we have a discoverability problem.\n\nThere is no similar discoverability and negative-surprise problem I\ncan think of by omitting other details, so there is no need to expand\nthis brief synopsis any further.\n\nThe one place we could potentially change thing that might help, is\nmoving the text about -c being the default from under the -c option\nand putting it here. That's a toss-up to me, but for now I elected to\nkeep it where it is.\n\n> > OPTIONS\n> > -------\n> > -c::\n> > --cached::\n> > - Show cached files in the output (default)\n> > + Show all files cached in Git's index, i.e. all tracked files.\n> > + (This is the default if no -c/-s/-d/-o/-u/-k/-m/--resolve-undo\n> > + options are specified.)\n> >\n> > -d::\n> > --deleted::\n> > - Show deleted files in the output\n> > + Show files with an unstaged deletion\n> >\n>\n> This is a nice fix: make it clear to the user that only files in the\n> working tree are deleted, not in the index.\n>\n> > -m::\n> > --modified::\n> > - Show modified files in the output\n> > + Show files with an unstaged modification (note that an unstaged\n> > + deletion also counts as an unstaged modification)\n> >\n>\n> Good to mention that deleted files are also modified, otherwise no one\n> looking at the documentation would know that.\n>\n> > -o::\n> > --others::\n[...]\n\nThanks for taking a look!\n"},{"id":"470364","messageId":"CABPp-BFFfDPT1x9E4bucuQnyVrWacego2agzyqjT7h+wQ=xpUg@mail.gmail.com","threadId":"59081","inReplyTo":"CAOLTT8RXgw0CC7TBUunCPnnk1=5gKkyYZcFQyWu29QM9bn9s9w@mail.gmail.com","subject":"Re: [PATCH 3/4] ls-files: clarify descriptions of status tags for -t","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2023-01-14T20:26:50Z","receivedAt":"2023-01-14T20:27:10Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Sat, Jan 14, 2023 at 12:27 AM ZheNing Hu wrote:\n>\n> Elijah Newren via GitGitGadget 于2023年1月13日周五 12:41写道：\n> >\n> > From: Elijah Newren \n> >\n> > Much like the file selection options we tweaked in the last commit, the\n> > status tags printed with -t had descriptions that were easy to\n> > misunderstand, and for many of the same reasons. Clarify them.\n> >\n> > Also, while at it, remove the \"semi-deprecated\" comment for \"git\n> > ls-files -t\". The -t option was marked as semi-deprecated in 5bc0e247c4\n> > (\"Document ls-files -t as semi-obsolete.\", 2010-07-28) because:\n> >\n> > \"git ls-files -t\" is [...] badly documented, hence we point the\n> > users to superior alternatives.\n> > The feature is marked as \"semi-obsolete\" but not \"scheduled for removal\"\n> > since it's a plumbing command, scripts might use it, and Git testsuite\n> > already uses it to test the state of the index.\n> >\n> > Marking it as obsolete because it was easily misunderstood, which I\n> > think was primarily due to documentation problems, is one strategy, but\n> > I think fixing the documentation is a better option. Especially since\n> > in the intervening time, \"git ls-files -t\" has become heavily used by\n> > sparse-checkout users where the same confusion just doesn't apply.\n> >\n> > Signed-off-by: Elijah Newren \n> > ---\n> > Documentation/git-ls-files.txt | 28 +++++++++++++++-------------\n> > 1 file changed, 15 insertions(+), 13 deletions(-)\n> >\n> > diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\n> > index f89ab1bfc98..3886d58d178 100644\n> > --- a/Documentation/git-ls-files.txt\n> > +++ b/Documentation/git-ls-files.txt\n> > @@ -137,25 +137,27 @@ OPTIONS\n> > with `-s` or `-u` options does not make any sense.\n> >\n> > -t::\n> > - This feature is semi-deprecated. For scripting purpose,\n> > - linkgit:git-status[1] `--porcelain` and\n> > + Show status tags together with filenames. Note that for\n> > + scripting purposes, linkgit:git-status[1] `--porcelain` and\n> > linkgit:git-diff-files[1] `--name-status` are almost always\n> > superior alternatives, and users should look at\n> > linkgit:git-status[1] `--short` or linkgit:git-diff[1]\n> > `--name-status` for more user-friendly alternatives.\n> > +\n> > --\n> > -This option identifies the file status with the following tags (followed by\n> > -a space) at the start of each line:\n> > -\n> > - H:: cached\n> > - S:: skip-worktree\n> > - M:: unmerged\n> > - R:: removed/deleted\n> > - C:: modified/changed\n> > - K:: to be killed\n> > - ?:: other\n> > - U:: resolve-undo\n> > +This option provides a reason for showing each filename, in the form\n> > +of a status tag (which is followed by a space and then the filename).\n> > +The status tags are all single characters from the following list:\n> > +\n> > + H:: tracked file that is not either unmerged or skip-worktree\n> > + S:: tracked file that is skip-worktree\n> > + M:: tracked file that is unmerged\n> > + R:: tracked file with unstaged removal/deletion\n> > + C:: tracked file with unstaged modification/change\n> > + K:: untracked paths which are part of file/directory conflicts\n> > + which prevent checking out tracked files\n> > + ?:: untracked file\n> > + U:: file with resolve-undo information\n> > --\n> >\n>\n> Good to see these tags describe are changed, especially \"K\" (reader\n> don't know what is \"to be killed\")\n>\n> Maybe we should mention which option will output these tags?\n> e.g. default -> \"H\"/\"S\" ,`--other` -> \"?\", `--modified` -> \"C\",\n> `--killed` -> \"K\"...\n\nWe could, but...\n\n * It's H/S/M, not just H/S that is shown by default.\n * It gets weird because other options aren't added to the default,\nso if someone specifies \"-m\" then suddenly H/S/M go away...unless they\nalso specify \"-c\".\n\nTrying to explain all that feels like we're getting close to repeating\nthe documentation of the individual options. But maybe we could just\nignore everything around default behavior and find a way to be brief\nsuch as with:\n\n Note that H, S, and M entries are shown with --cached; R entries\n are shown with --deleted, C entries are shown with --modified, K\n entries are shown with --killed, ? entries are shown with\n --others, and U entries are shown with --resolve-undo.\n\nI'm not sure if I like the documentation better with or without this\nadded paragraph. What do others think?\n"},{"id":"470440","messageId":"CAOLTT8TxHhbjicJp1fEdjGhmP2AwOef3OU9t+tWOLq+XDcJLOg@mail.gmail.com","threadId":"59081","inReplyTo":"CABPp-BFuZK2yap_VXWPo8qHvJ+E9V7v2UAZ9tAaQcX8zc-daDA@mail.gmail.com","subject":"Re: [PATCH 2/4] ls-files: clarify descriptions of file selection options","fromName":"ZheNing Hu","fromEmail":"adlternative@gmail.com","sentAt":"2023-01-16T17:12:10Z","receivedAt":"2023-01-16T17:36:32Z","isPatch":true,"sender":{"key":"adlternative@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58138461?v=4"},"body":"Elijah Newren 于2023年1月15日周日 03:42写道：\n>\n> On Sat, Jan 14, 2023 at 12:21 AM ZheNing Hu wrote:\n> >\n> > Elijah Newren via GitGitGadget 于2023年1月13日周五 12:41写道：\n> [...]\n> > > diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\n> > > index cb071583f8b..f89ab1bfc98 100644\n> > > --- a/Documentation/git-ls-files.txt\n> > > +++ b/Documentation/git-ls-files.txt\n> > > @@ -29,21 +29,26 @@ This merges the file listing in the index with the actual working\n> > > directory list, and shows different combinations of the two.\n> > >\n> > > One or more of the options below may be used to determine the files\n> > > -shown:\n> > > +shown, and each file may be printed multiple times if there are\n> > > +multiple entries in the index or multiple statuses are applicable for\n> > > +the relevant file selection options.\n> > >\n> >\n> > `--deduplicate` option can be used to remove deduped output.\n>\n> Yes, I'm aware.\n>\n> If you're suggesting adding this text at this point in the document,\n> it occurred to me already, but I chose not to put it here. The reason\n> is that this is a brief synopsis. The \"relevant file selection\n> options\" of this brief synopsis could also be expanded to mention what\n> they are or what the default selection is or whatever. But folks can\n> read on to learn that `deduplicate` can be used to remove duplicate\n> options. Likewise, anyone who reads the text about \"relevant file\n> selections\" and wants to learn more is inclined to read on to the\n> other options to find out.\n>\n> In contrast, no one will be motivated to read on to find out that\n> files can be printed multiple times if we don't mention it right here.\n> And they are likely to get confused when it happens, thinking it is a\n> bug (in fact, I can point out emails from the archives where that has\n> happened). Without mentioning the possibility of multiple files at\n> this point, we have a discoverability problem.\n>\n> There is no similar discoverability and negative-surprise problem I\n> can think of by omitting other details, so there is no need to expand\n> this brief synopsis any further.\n>\n\nWell, you are right. It may be better to be concise here, telling users too\nmuch will make it difficult to read.\n\n> The one place we could potentially change thing that might help, is\n> moving the text about -c being the default from under the -c option\n> and putting it here. That's a toss-up to me, but for now I elected to\n> keep it where it is.\n>\n\nI think it's fine to do this or not.\n\n> > > OPTIONS\n> > > -------\n> > > -c::\n> > > --cached::\n> > > - Show cached files in the output (default)\n> > > + Show all files cached in Git's index, i.e. all tracked files.\n> > > + (This is the default if no -c/-s/-d/-o/-u/-k/-m/--resolve-undo\n> > > + options are specified.)\n> > >\n> > > -d::\n> > > --deleted::\n> > > - Show deleted files in the output\n> > > + Show files with an unstaged deletion\n> > >\n> >\n> > This is a nice fix: make it clear to the user that only files in the\n> > working tree are deleted, not in the index.\n> >\n> > > -m::\n> > > --modified::\n> > > - Show modified files in the output\n> > > + Show files with an unstaged modification (note that an unstaged\n> > > + deletion also counts as an unstaged modification)\n> > >\n> >\n> > Good to mention that deleted files are also modified, otherwise no one\n> > looking at the documentation would know that.\n> >\n> > > -o::\n> > > --others::\n> [...]\n>\n> Thanks for taking a look!\n"},{"id":"470442","messageId":"CAOLTT8Tvkz39sigiQgdRzTfFAcQO6kf3t8Pei9Mb1R2-UNje1g@mail.gmail.com","threadId":"59081","inReplyTo":"CABPp-BFFfDPT1x9E4bucuQnyVrWacego2agzyqjT7h+wQ=xpUg@mail.gmail.com","subject":"Re: [PATCH 3/4] ls-files: clarify descriptions of status tags for -t","fromName":"ZheNing Hu","fromEmail":"adlternative@gmail.com","sentAt":"2023-01-16T17:21:03Z","receivedAt":"2023-01-16T17:43:24Z","isPatch":true,"sender":{"key":"adlternative@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58138461?v=4"},"body":"Elijah Newren 于2023年1月15日周日 04:27写道：\n>\n> On Sat, Jan 14, 2023 at 12:27 AM ZheNing Hu wrote:\n> >\n> > Elijah Newren via GitGitGadget 于2023年1月13日周五 12:41写道：\n> > >\n> > > From: Elijah Newren \n> > >\n> > > Much like the file selection options we tweaked in the last commit, the\n> > > status tags printed with -t had descriptions that were easy to\n> > > misunderstand, and for many of the same reasons. Clarify them.\n> > >\n> > > Also, while at it, remove the \"semi-deprecated\" comment for \"git\n> > > ls-files -t\". The -t option was marked as semi-deprecated in 5bc0e247c4\n> > > (\"Document ls-files -t as semi-obsolete.\", 2010-07-28) because:\n> > >\n> > > \"git ls-files -t\" is [...] badly documented, hence we point the\n> > > users to superior alternatives.\n> > > The feature is marked as \"semi-obsolete\" but not \"scheduled for removal\"\n> > > since it's a plumbing command, scripts might use it, and Git testsuite\n> > > already uses it to test the state of the index.\n> > >\n> > > Marking it as obsolete because it was easily misunderstood, which I\n> > > think was primarily due to documentation problems, is one strategy, but\n> > > I think fixing the documentation is a better option. Especially since\n> > > in the intervening time, \"git ls-files -t\" has become heavily used by\n> > > sparse-checkout users where the same confusion just doesn't apply.\n> > >\n> > > Signed-off-by: Elijah Newren \n> > > ---\n> > > Documentation/git-ls-files.txt | 28 +++++++++++++++-------------\n> > > 1 file changed, 15 insertions(+), 13 deletions(-)\n> > >\n> > > diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\n> > > index f89ab1bfc98..3886d58d178 100644\n> > > --- a/Documentation/git-ls-files.txt\n> > > +++ b/Documentation/git-ls-files.txt\n> > > @@ -137,25 +137,27 @@ OPTIONS\n> > > with `-s` or `-u` options does not make any sense.\n> > >\n> > > -t::\n> > > - This feature is semi-deprecated. For scripting purpose,\n> > > - linkgit:git-status[1] `--porcelain` and\n> > > + Show status tags together with filenames. Note that for\n> > > + scripting purposes, linkgit:git-status[1] `--porcelain` and\n> > > linkgit:git-diff-files[1] `--name-status` are almost always\n> > > superior alternatives, and users should look at\n> > > linkgit:git-status[1] `--short` or linkgit:git-diff[1]\n> > > `--name-status` for more user-friendly alternatives.\n> > > +\n> > > --\n> > > -This option identifies the file status with the following tags (followed by\n> > > -a space) at the start of each line:\n> > > -\n> > > - H:: cached\n> > > - S:: skip-worktree\n> > > - M:: unmerged\n> > > - R:: removed/deleted\n> > > - C:: modified/changed\n> > > - K:: to be killed\n> > > - ?:: other\n> > > - U:: resolve-undo\n> > > +This option provides a reason for showing each filename, in the form\n> > > +of a status tag (which is followed by a space and then the filename).\n> > > +The status tags are all single characters from the following list:\n> > > +\n> > > + H:: tracked file that is not either unmerged or skip-worktree\n> > > + S:: tracked file that is skip-worktree\n> > > + M:: tracked file that is unmerged\n> > > + R:: tracked file with unstaged removal/deletion\n> > > + C:: tracked file with unstaged modification/change\n> > > + K:: untracked paths which are part of file/directory conflicts\n> > > + which prevent checking out tracked files\n> > > + ?:: untracked file\n> > > + U:: file with resolve-undo information\n> > > --\n> > >\n> >\n> > Good to see these tags describe are changed, especially \"K\" (reader\n> > don't know what is \"to be killed\")\n> >\n> > Maybe we should mention which option will output these tags?\n> > e.g. default -> \"H\"/\"S\" ,`--other` -> \"?\", `--modified` -> \"C\",\n> > `--killed` -> \"K\"...\n>\n> We could, but...\n>\n> * It's H/S/M, not just H/S that is shown by default.\n> * It gets weird because other options aren't added to the default,\n> so if someone specifies \"-m\" then suddenly H/S/M go away...unless they\n> also specify \"-c\".\n>\n> Trying to explain all that feels like we're getting close to repeating\n> the documentation of the individual options. But maybe we could just\n> ignore everything around default behavior and find a way to be brief\n> such as with:\n>\n> Note that H, S, and M entries are shown with --cached; R entries\n> are shown with --deleted, C entries are shown with --modified, K\n> entries are shown with --killed, ? entries are shown with\n> --others, and U entries are shown with --resolve-undo.\n>\n\nWhat you mean is that each tag will appear in which commands, rather than\neach command will have which tags. I think this segment is pretty good.\n\n> I'm not sure if I like the documentation better with or without this\n> added paragraph. What do others think?\n"}]}