{"thread":{"id":"23458","subject":"[PATCH] Document ls-files -t as obsolete.","startedAt":"2010-04-14T13:45:04Z","lastAt":"2010-04-14T14:58:52Z","messageCount":6,"participants":["Matthieu Moy","Junio C Hamano","Daniel Grace","Tor Arntsen"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"139477","messageId":"1271252704-21739-1-git-send-email-Matthieu.Moy@imag.fr","threadId":"23458","inReplyTo":null,"subject":"[PATCH] Document ls-files -t as obsolete.","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2010-04-14T13:45:04Z","receivedAt":"2010-04-14T13:45:04Z","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 \"obsolete\" but not \"scheduled for removal\" since\nit's a plumbing command, scripts might use it, and Git testsuite already\nuses it to test the state of the index.\n\nSigned-off-by: Matthieu Moy \n---\n Documentation/git-ls-files.txt | 5 +++++\n 1 files changed, 5 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 3521637..7b86bb5 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -106,6 +106,11 @@ OPTIONS\n \twith `-s` or `-u` options does not make any sense.\n \n -t::\n+\tThis feature is deprecated. Authors of scripts should use\n+\tlinkgit:git-status[1] `--porcelain`, and users can look at\n+\tlinkgit:git-status[1] `--short` or linkgit:git-diff[1]\n+\t`--name-status` for 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.0.3.299.gb22d9.dirty\n"},{"id":"139480","messageId":"7vaat6qesd.fsf@alter.siamese.dyndns.org","threadId":"23458","inReplyTo":"1271252704-21739-1-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH] Document ls-files -t as obsolete.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-04-14T14:39:30Z","receivedAt":"2010-04-14T14:39:30Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy writes:\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 am no entirely happy with this patch.\n\nIf all your scripted Porcelain wants to see is \"what are the paths I might\nwant to run 'git add' on?\", you do not want to run diff twice (which is\nwhat \"status\" does); you would say \"ls-files -t -m -o --exclude-standard\",\ninstead. The alternative is not even superiour in this case.\n\nHaving said that, I personally don't think of any other combination of\nflags with which \"ls-files -t\" is useful.\n\nIf there are parts of the documentation that are misleading, perhaps that\nis what your patch should be fixing instead, no?\n"},{"id":"139482","messageId":"z2hd2d39d861004140747u5980eeach66b58102cd5ede25@mail.gmail.com","threadId":"23458","inReplyTo":"1271252704-21739-1-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH] Document ls-files -t as obsolete.","fromName":"Tor Arntsen","fromEmail":"tor@spacetec.no","sentAt":"2010-04-14T14:47:45Z","receivedAt":"2010-04-14T14:47:45Z","isPatch":true,"sender":{"key":"tor@spacetec.no","avatar":null},"body":"Sorry for being stupid and a bit off-topic, but..\n\n>  -t::\n> +       This feature is deprecated. Authors of scripts should use\n> +       linkgit:git-status[1] `--porcelain`, [...]\n\nI've always understood 'porcelain' as for users, and 'plumbing' for\nscripts.. so, if the option is meant for scripting (as opposed to\n--short), why wasn't it called --plumbing? There's obviously something\nI'm not getting here! -:)\n\n-Tor\n"},{"id":"139481","messageId":"t2r62a3a9cb1004140747s46c5ee50z3a063d8f2acf4e61@mail.gmail.com","threadId":"23458","inReplyTo":"7vaat6qesd.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Document ls-files -t as obsolete.","fromName":"Daniel Grace","fromEmail":"negativeview@gmail.com","sentAt":"2010-04-14T14:47:49Z","receivedAt":"2010-04-14T14:47:49Z","isPatch":true,"sender":{"key":"negativeview@gmail.com","avatar":"https://gravatar.com/avatar/3cdfd055fcddbe166daf37ce403bfce216b100e8fc783998f43938ff77c388dc?d=mp&s=160"},"body":"On Wed, Apr 14, 2010 at 9:39 AM, Junio C Hamano wrote:\n\n> If all your scripted Porcelain wants to see is \"what are the paths I might\n> want to run 'git add' on?\", you do not want to run diff twice (which is\n> what \"status\" does); you would say \"ls-files -t -m -o --exclude-standard\",\n> instead. The alternative is not even superiour in this case.\n\nWhy -m? I have a script that attempts to ask just this question and I\ndon't use -m. Reading the documentation, I'm not sure why I would. In\nwhat cases would I get wrong information without -m? For the record, I\nalso don't use -t, though using -t in this case does make sense to me,\nI just apparently didn't notice that bit of the documentation when\nwriting that feature.\n\nDaniel\nhttp://www.doomstick.com\n"},{"id":"139484","messageId":"vpq4oje2idk.fsf@bauges.imag.fr","threadId":"23458","inReplyTo":"7vaat6qesd.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Document ls-files -t as obsolete.","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2010-04-14T14:55:51Z","receivedAt":"2010-04-14T14:55:51Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Junio C Hamano writes:\n\n> Matthieu Moy writes:\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 am no entirely happy with this patch.\n>\n> If all your scripted Porcelain wants to see is \"what are the paths I might\n> want to run 'git add' on?\", you do not want to run diff twice (which is\n> what \"status\" does); you would say \"ls-files -t -m -o --exclude-standard\",\n> instead. The alternative is not even superiour in this case.\n>\n> Having said that, I personally don't think of any other combination of\n> flags with which \"ls-files -t\" is useful.\n>\n> If there are parts of the documentation that are misleading, perhaps that\n> is what your patch should be fixing instead, no?\n\nAfter having tried to understand how \"git ls-files -t\" was supposed to\nwork\n( http://thread.gmane.org/gmane.comp.version-control.git/126516/focus=126520 ),\nI admit that I have no idea how to document such weird behavior.\n\nIf power users want to use \"git ls-files -t\", let them do (I'm not\nsaying the feature should be removed), but I don't see a point trying\nto help people to use it.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"139485","messageId":"vpqeiii13o3.fsf@bauges.imag.fr","threadId":"23458","inReplyTo":"z2hd2d39d861004140747u5980eeach66b58102cd5ede25@mail.gmail.com","subject":"Re: [PATCH] Document ls-files -t as obsolete.","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2010-04-14T14:58:52Z","receivedAt":"2010-04-14T14:58:52Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Tor Arntsen writes:\n\n> Sorry for being stupid and a bit off-topic, but..\n>\n>>  -t::\n>> +       This feature is deprecated. Authors of scripts should use\n>> +       linkgit:git-status[1] `--porcelain`, [...]\n>\n> I've always understood 'porcelain' as for users, and 'plumbing' for\n> scripts.. so, if the option is meant for scripting (as opposed to\n> --short), why wasn't it called --plumbing? There's obviously something\n> I'm not getting here! -:)\n\nThere's prior art (\"git annotate --porcelain\" at least). I disagree\nwith the rationale, but --porcelain means \"to be used by porcelain\nscripts\", hence \"behave like plubing\".\n\n--\nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"}]}