# [PATCH] Document ls-files -t as obsolete. 6 messages from 2010-04-14 to 2010-04-14. Participants: Matthieu Moy, Junio C Hamano, Daniel Grace, Tor Arntsen. Thread: https://gitlist.dev/t/23458 ## Matthieu Moy, 2010-04-14 13:45 Subject: [PATCH] Document ls-files -t as obsolete. Message-ID: <1271252704-21739-1-git-send-email-Matthieu.Moy@imag.fr> URL: https://gitlist.dev/e/1271252704-21739-1-git-send-email-Matthieu.Moy%40imag.fr ``` The behavior of "git ls-files -t" is very misleading (see http://thread.gmane.org/gmane.comp.version-control.git/126516 and http://thread.gmane.org/gmane.comp.version-control.git/144394/focus=144397 for examples of mislead users) and badly documented, hence we point the users to superior alternatives. The feature is marked as "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. Signed-off-by: Matthieu Moy --- Documentation/git-ls-files.txt | 5 +++++ 1 files changed, 5 insertions(+), 0 deletions(-) diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 3521637..7b86bb5 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -106,6 +106,11 @@ OPTIONS with `-s` or `-u` options does not make any sense. -t:: + This feature is deprecated. Authors of scripts should use + linkgit:git-status[1] `--porcelain`, and users can look at + linkgit:git-status[1] `--short` or linkgit:git-diff[1] + `--name-status` for alternatives. + Identify the file status with the following tags (followed by a space) at the start of each line: H:: cached -- 1.7.0.3.299.gb22d9.dirty ``` ## Junio C Hamano, 2010-04-14 14:39 Subject: Re: [PATCH] Document ls-files -t as obsolete. Message-ID: <7vaat6qesd.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7vaat6qesd.fsf%40alter.siamese.dyndns.org In-Reply-To: <1271252704-21739-1-git-send-email-Matthieu.Moy@imag.fr> ``` Matthieu Moy writes: > The behavior of "git ls-files -t" is very misleading (see > http://thread.gmane.org/gmane.comp.version-control.git/126516 and > http://thread.gmane.org/gmane.comp.version-control.git/144394/focus=144397 > for examples of mislead users) and badly documented, hence we point the > users to superior alternatives. I am no entirely happy with this patch. If all your scripted Porcelain wants to see is "what are the paths I might want to run 'git add' on?", you do not want to run diff twice (which is what "status" does); you would say "ls-files -t -m -o --exclude-standard", instead. The alternative is not even superiour in this case. Having said that, I personally don't think of any other combination of flags with which "ls-files -t" is useful. If there are parts of the documentation that are misleading, perhaps that is what your patch should be fixing instead, no? ``` ## Tor Arntsen, 2010-04-14 14:47 Subject: Re: [PATCH] Document ls-files -t as obsolete. Message-ID: URL: https://gitlist.dev/e/z2hd2d39d861004140747u5980eeach66b58102cd5ede25%40mail.gmail.com In-Reply-To: <1271252704-21739-1-git-send-email-Matthieu.Moy@imag.fr> ``` Sorry for being stupid and a bit off-topic, but.. >  -t:: > +       This feature is deprecated. Authors of scripts should use > +       linkgit:git-status[1] `--porcelain`, [...] I've always understood 'porcelain' as for users, and 'plumbing' for scripts.. so, if the option is meant for scripting (as opposed to --short), why wasn't it called --plumbing? There's obviously something I'm not getting here! -:) -Tor ``` ## Daniel Grace, 2010-04-14 14:47 Subject: Re: [PATCH] Document ls-files -t as obsolete. Message-ID: URL: https://gitlist.dev/e/t2r62a3a9cb1004140747s46c5ee50z3a063d8f2acf4e61%40mail.gmail.com In-Reply-To: <7vaat6qesd.fsf@alter.siamese.dyndns.org> ``` On Wed, Apr 14, 2010 at 9:39 AM, Junio C Hamano wrote: > If all your scripted Porcelain wants to see is "what are the paths I might > want to run 'git add' on?", you do not want to run diff twice (which is > what "status" does); you would say "ls-files -t -m -o --exclude-standard", > instead. The alternative is not even superiour in this case. Why -m? I have a script that attempts to ask just this question and I don't use -m. Reading the documentation, I'm not sure why I would. In what cases would I get wrong information without -m? For the record, I also don't use -t, though using -t in this case does make sense to me, I just apparently didn't notice that bit of the documentation when writing that feature. Daniel http://www.doomstick.com ``` ## Matthieu Moy, 2010-04-14 14:55 Subject: Re: [PATCH] Document ls-files -t as obsolete. Message-ID: URL: https://gitlist.dev/e/vpq4oje2idk.fsf%40bauges.imag.fr In-Reply-To: <7vaat6qesd.fsf@alter.siamese.dyndns.org> ``` Junio C Hamano writes: > Matthieu Moy writes: > >> The behavior of "git ls-files -t" is very misleading (see >> http://thread.gmane.org/gmane.comp.version-control.git/126516 and >> http://thread.gmane.org/gmane.comp.version-control.git/144394/focus=144397 >> for examples of mislead users) and badly documented, hence we point the >> users to superior alternatives. > > I am no entirely happy with this patch. > > If all your scripted Porcelain wants to see is "what are the paths I might > want to run 'git add' on?", you do not want to run diff twice (which is > what "status" does); you would say "ls-files -t -m -o --exclude-standard", > instead. The alternative is not even superiour in this case. > > Having said that, I personally don't think of any other combination of > flags with which "ls-files -t" is useful. > > If there are parts of the documentation that are misleading, perhaps that > is what your patch should be fixing instead, no? After having tried to understand how "git ls-files -t" was supposed to work ( http://thread.gmane.org/gmane.comp.version-control.git/126516/focus=126520 ), I admit that I have no idea how to document such weird behavior. If power users want to use "git ls-files -t", let them do (I'm not saying the feature should be removed), but I don't see a point trying to help people to use it. -- Matthieu Moy http://www-verimag.imag.fr/~moy/ ``` ## Matthieu Moy, 2010-04-14 14:58 Subject: Re: [PATCH] Document ls-files -t as obsolete. Message-ID: URL: https://gitlist.dev/e/vpqeiii13o3.fsf%40bauges.imag.fr In-Reply-To: ``` Tor Arntsen writes: > Sorry for being stupid and a bit off-topic, but.. > >>  -t:: >> +       This feature is deprecated. Authors of scripts should use >> +       linkgit:git-status[1] `--porcelain`, [...] > > I've always understood 'porcelain' as for users, and 'plumbing' for > scripts.. so, if the option is meant for scripting (as opposed to > --short), why wasn't it called --plumbing? There's obviously something > I'm not getting here! -:) There's prior art ("git annotate --porcelain" at least). I disagree with the rationale, but --porcelain means "to be used by porcelain scripts", hence "behave like plubing". -- Matthieu Moy http://www-verimag.imag.fr/~moy/ ```