{"thread":{"id":"24528","subject":"[PATCH v2] Document ls-files -t as semi-obsolete.","startedAt":"2010-07-26T16:39:51Z","lastAt":"2010-07-28T07:24:27Z","messageCount":10,"participants":["Matthieu Moy","Junio C Hamano","Michele Ballabio","Jeff King"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"146393","messageId":"1280162391-18701-1-git-send-email-Matthieu.Moy@imag.fr","threadId":"24528","inReplyTo":null,"subject":"[PATCH v2] Document ls-files -t as semi-obsolete.","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2010-07-26T16:39:51Z","receivedAt":"2010-07-26T16:39:51Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"The behavior of \"git ls-files -t\" is very misleading (see\nhttp://thread.gmane.org/gmane.comp.version-control.git/126516 and\nhttp://thread.gmane.org/gmane.comp.version-control.git/144394/focus=144397\nfor examples of mislead users) and badly documented, hence we point the\nusers to superior alternatives.\n\nThe feature is marked as \"semi-obsolete\" but not \"scheduled for removal\"\nsince it's a plumbing command, scripts might use it, and Git testsuite\nalready uses it to test the state of the index.\n\nSigned-off-by: Matthieu Moy \n---\nResurecting a very old patch:\n\nhttp://thread.gmane.org/gmane.comp.version-control.git/144874\n\nThe earlier concerns were:\n\n1) There are valid uses for \"git ls-files -t\" and\n2) If documentation is bad, then it should be improved.\n\nThis version should adress 1) by mitigating the wording (deprecated ->\nsemi-deprecated, \"almost always\"). To answer 2), I don't think\nspending energy documenting a feature that almost nobody uses is worth\nit. At least, I'm not going to do it, and since nothing happened for\nmonths, I guess no one else will.\n\n Documentation/git-ls-files.txt | 6 ++++++\n 1 files changed, 6 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 3521637..2cc3243 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -106,6 +106,12 @@ 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` is almost always a\n+\tsuperior alternative, 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 \tIdentify the file status with the following tags (followed by\n \ta space) at the start of each line:\n \tH::\tcached\n-- \n1.7.2.19.g9a302.dirty\n"},{"id":"146499","messageId":"7vsk347rol.fsf@alter.siamese.dyndns.org","threadId":"24528","inReplyTo":"1280162391-18701-1-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH v2] Document ls-files -t as semi-obsolete.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-07-27T17:36:26Z","receivedAt":"2010-07-27T17:36:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sounds good; comments from others?\n"},{"id":"146512","messageId":"201007272107.50204.barra_cuda@katamail.com","threadId":"24528","inReplyTo":"1280162391-18701-1-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH v2] Document ls-files -t as semi-obsolete.","fromName":"Michele Ballabio","fromEmail":"barra_cuda@katamail.com","sentAt":"2010-07-27T19:07:49Z","receivedAt":"2010-07-27T19:07:49Z","isPatch":true,"sender":{"key":"barra_cuda@katamail.com","avatar":"https://avatars.githubusercontent.com/u/16371673?v=4"},"body":"On Monday 26 July 2010, Matthieu Moy wrote:\n> Documentation/git-ls-files.txt | 6 ++++++\n> 1 files changed, 6 insertions(+), 0 deletions(-)\n> \n> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\n> index 3521637..2cc3243 100644\n> --- a/Documentation/git-ls-files.txt\n> +++ b/Documentation/git-ls-files.txt\n> @@ -106,6 +106,12 @@ 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` is almost always a\n> +\tsuperior alternative, 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> \tIdentify the file status with the following tags (followed by\n> \ta space) at the start of each line:\n> \tH::\tcached\n\nI think this breaks formatting. Shouldn't it be more like the following?\n(I.e. with a single '+' before \"Identify...\").\n\nAnd maybe rephrase the line\n\"Identify the file status with the following tags (followed by\na space) at the start of each line\"\ninto\n\"This option identifies...\"\njust to set apart \"semi-deprecation\" and \"explanation\" of the option.\n\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 3521637..ef84d41 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -106,15 +106,21 @@ OPTIONS\n \twith `-s` or `-u` options does not make any sense.\n \n -t::\n-\tIdentify the file status with the following tags (followed by\n-\ta space) at the start of each line:\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+\tThis feature is semi-deprecated. For scripting purpose,\n+\tlinkgit:git-status[1] `--porcelain` is almost always a\n+\tsuperior alternative, 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+Identify the file status with the following tags (followed by\n+a space) at the start of each line:\n+H::\tcached\n+S::\tskip-worktree\n+M::\tunmerged\n+R::\tremoved/deleted\n+C::\tmodified/changed\n+K::\tto be killed\n+?::\tother\n \n -v::\n \tSimilar to `-t`, but use lowercase letters for files\n"},{"id":"146516","messageId":"20100727195832.GA11717@coredump.intra.peff.net","threadId":"24528","inReplyTo":"1280162391-18701-1-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH v2] Document ls-files -t as semi-obsolete.","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-07-27T19:58:33Z","receivedAt":"2010-07-27T19:58:33Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Jul 26, 2010 at 06:39:51PM +0200, Matthieu Moy wrote:\n\n> The behavior of \"git ls-files -t\" is very misleading (see\n> http://thread.gmane.org/gmane.comp.version-control.git/126516 and\n> http://thread.gmane.org/gmane.comp.version-control.git/144394/focus=144397\n> for examples of mislead users) and badly documented, hence we point the\n> users to superior alternatives.\n\nI agree with the goal, but one nit:\n\n> -t::\n> +\tThis feature is semi-deprecated. For scripting purpose,\n> +\tlinkgit:git-status[1] `--porcelain` is almost always a\n> +\tsuperior alternative, 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\nIsn't \"git diff-files --name-status\" the closest plumbing analogue? Git\nstatus actually does a lot of extra work.\n\nAlso, while testing this, I got confused. Does \"ls-files -t\" even work,\nor am I totally misunderstanding it? I tried:\n\n mkdir repo && cd repo && git init &&\n echo content >file1 &&\n echo content >file2 &&\n git add . &&\n git commit -m one &&\n echo content >>file1 &&\n echo content >>file2 &&\n git add file1 &&\n git ls-files -t\n\nwhich yields:\n\n H file1\n H file2\n\nShouldn't one of them be marked \"C\"hanged (I think file2, but that was\nwhat I was double-checking)?\n\n-Peff\n"},{"id":"146518","messageId":"vpqeieoy9bb.fsf@bauges.imag.fr","threadId":"24528","inReplyTo":"20100727195832.GA11717@coredump.intra.peff.net","subject":"Re: [PATCH v2] Document ls-files -t as semi-obsolete.","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2010-07-27T20:11:04Z","receivedAt":"2010-07-27T20:11:04Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Jeff King writes:\n\n> On Mon, Jul 26, 2010 at 06:39:51PM +0200, Matthieu Moy wrote:\n>\n>> The behavior of \"git ls-files -t\" is very misleading (see\n>> http://thread.gmane.org/gmane.comp.version-control.git/126516 and\n>> http://thread.gmane.org/gmane.comp.version-control.git/144394/focus=144397\n>> for examples of mislead users) and badly documented, hence we point the\n>> users to superior alternatives.\n>\n> I agree with the goal, but one nit:\n>\n>> -t::\n>> +\tThis feature is semi-deprecated. For scripting purpose,\n>> +\tlinkgit:git-status[1] `--porcelain` is almost always a\n>> +\tsuperior alternative, 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> Isn't \"git diff-files --name-status\" the closest plumbing analogue? Git\n> status actually does a lot of extra work.\n\ngit diff-files --name-status won't show untracked files, while \"git\nls-files -t -o\" will for example. I agree that \"git status\" does extra\nwork, but that's what you usually want when you want to know the\nstatus of files. We already mention \"git diff --name-status\", so\npeople looking for \"git diff-tree --name-status\" should be able to\nfind it.\n\n> Also, while testing this, I got confused. Does \"ls-files -t\" even work,\n> or am I totally misunderstanding it? I tried:\n\nMany people tried to understand what \"ls-files -t\" was supposed to do,\nincluding myself, and I'm afraid nobody succeeded.\n\n> Shouldn't one of them be marked \"C\"hanged (I think file2, but that was\n> what I was double-checking)?\n\nYou should ask \"git ls-files -t -m\" if you want to see modified files.\n\nI'm afraid we have another proof that we should discourage the use of\nthis feature ;-).\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"146522","messageId":"vpqaapcy6xq.fsf@bauges.imag.fr","threadId":"24528","inReplyTo":"201007272107.50204.barra_cuda@katamail.com","subject":"Re: [PATCH v2] Document ls-files -t as semi-obsolete.","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2010-07-27T21:02:25Z","receivedAt":"2010-07-27T21:02:25Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Michele Ballabio writes:\n\n> I think this breaks formatting. Shouldn't it be more like the following?\n> (I.e. with a single '+' before \"Identify...\").\n\nYour version wraps the list and makes it unreadable. A newline between\nthe paragraph and the list seems to fix this.\n\n> And maybe rephrase the line\n> \"Identify the file status with the following tags (followed by\n> a space) at the start of each line\"\n> into\n> \"This option identifies...\"\n> just to set apart \"semi-deprecation\" and \"explanation\" of the\n> option.\n\nI buy this.\n\nNew version comming soon.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"146523","messageId":"20100727210638.GA12052@coredump.intra.peff.net","threadId":"24528","inReplyTo":"vpqeieoy9bb.fsf@bauges.imag.fr","subject":"Re: [PATCH v2] Document ls-files -t as semi-obsolete.","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-07-27T21:06:38Z","receivedAt":"2010-07-27T21:06:38Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Jul 27, 2010 at 10:11:04PM +0200, Matthieu Moy wrote:\n\n> > Isn't \"git diff-files --name-status\" the closest plumbing analogue? Git\n> > status actually does a lot of extra work.\n> \n> git diff-files --name-status won't show untracked files, while \"git\n> ls-files -t -o\" will for example. I agree that \"git status\" does extra\n> work, but that's what you usually want when you want to know the\n> status of files. We already mention \"git diff --name-status\", so\n> people looking for \"git diff-tree --name-status\" should be able to\n> find it.\n\nGood point. I was thinking of \"ls-files -t\" by itself, but you are\nlikely to ask for other things anyway.\n\n> > Shouldn't one of them be marked \"C\"hanged (I think file2, but that was\n> > what I was double-checking)?\n> \n> You should ask \"git ls-files -t -m\" if you want to see modified files.\n\nOK, that makes sense, I guess.\n\n> I'm afraid we have another proof that we should discourage the use of\n> this feature ;-).\n\nI think we all agree on that bit. :)\n\n-Peff\n"},{"id":"146525","messageId":"1280265073-23037-1-git-send-email-Matthieu.Moy@imag.fr","threadId":"24528","inReplyTo":"vpqaapcy6xq.fsf@bauges.imag.fr","subject":"[PATCH v3] Document ls-files -t as semi-obsolete.","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2010-07-27T21:11:13Z","receivedAt":"2010-07-27T21:11:13Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"The behavior of \"git ls-files -t\" is very misleading (see\nhttp://thread.gmane.org/gmane.comp.version-control.git/126516 and\nhttp://thread.gmane.org/gmane.comp.version-control.git/144394/focus=144397\nfor examples of mislead users) and badly documented, hence we point the\nusers to superior alternatives.\n\nThe feature is marked as \"semi-obsolete\" but not \"scheduled for removal\"\nsince it's a plumbing command, scripts might use it, and Git testsuite\nalready uses it to test the state of the index.\n\nSigned-off-by: Matthieu Moy \n---\nShould fix the formatting issue.\n\nFinally, I also added a mention of diff-tree --name-status too.\n\n Documentation/git-ls-files.txt | 12 ++++++++++--\n 1 files changed, 10 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 3521637..710e87a 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -106,8 +106,16 @@ OPTIONS\n \twith `-s` or `-u` options does not make any sense.\n \n -t::\n-\tIdentify the file status with the following tags (followed by\n-\ta space) at the start of each line:\n+\tThis feature is semi-deprecated. For scripting purpose,\n+\tlinkgit:git-status[1] `--porcelain` and\n+\tlinkgit:git-diff-tree[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+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-- \n1.7.2.25.g50ec3\n"},{"id":"146573","messageId":"20100728040047.GA17614@coredump.intra.peff.net","threadId":"24528","inReplyTo":"1280265073-23037-1-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH v3] Document ls-files -t as semi-obsolete.","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-07-28T04:00:47Z","receivedAt":"2010-07-28T04:00:47Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Jul 27, 2010 at 11:11:13PM +0200, Matthieu Moy wrote:\n\n> -t::\n> -\tIdentify the file status with the following tags (followed by\n> -\ta space) at the start of each line:\n> +\tThis feature is semi-deprecated. For scripting purpose,\n> +\tlinkgit:git-status[1] `--porcelain` and\n> +\tlinkgit:git-diff-tree[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\nShouldn't it be diff-files and not diff-tree?\n\n-Peff\n"},{"id":"146581","messageId":"1280301867-20516-1-git-send-email-Matthieu.Moy@imag.fr","threadId":"24528","inReplyTo":"20100728040047.GA17614@coredump.intra.peff.net","subject":"[PATCH v4] Document ls-files -t as semi-obsolete.","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2010-07-28T07:24:27Z","receivedAt":"2010-07-28T07:24:27Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"The behavior of \"git ls-files -t\" is very misleading (see\nhttp://thread.gmane.org/gmane.comp.version-control.git/126516 and\nhttp://thread.gmane.org/gmane.comp.version-control.git/144394/focus=144397\nfor examples of mislead users) and badly documented, hence we point the\nusers to superior alternatives.\n\nThe feature is marked as \"semi-obsolete\" but not \"scheduled for removal\"\nsince it's a plumbing command, scripts might use it, and Git testsuite\nalready uses it to test the state of the index.\n\nSigned-off-by: Matthieu Moy \n---\nJust s/diff-tree/diff-files/ (thanks to Peff for the correction) compared to v3.\n\n Documentation/git-ls-files.txt | 12 ++++++++++--\n 1 files changed, 10 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 3521637..bd919f2 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -106,8 +106,16 @@ OPTIONS\n \twith `-s` or `-u` options does not make any sense.\n \n -t::\n-\tIdentify the file status with the following tags (followed by\n-\ta space) at the start of each line:\n+\tThis feature is semi-deprecated. For scripting purpose,\n+\tlinkgit: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+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-- \n1.7.2.25.g9ebe3\n"}]}