threads / patch / 24528

v2Document ls-files -t as semi-obsolete.

Subject: [PATCH v2] Document ls-files -t as semi-obsolete.

## tl;dr

10 messages between Jul 26, 2010 and Jul 28, 2010. Diffs are folded; open one to read it.

replies: 9people: 5as markdown or json

Matthieu Moy· Jul 26, 2010, 16:39 UTC · lore

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 "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.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
Resurecting a very old patch:

http://thread.gmane.org/gmane.comp.version-control.git/144874

The earlier concerns were:

1) There are valid uses for "git ls-files -t" and
2) If documentation is bad, then it should be improved.

This version should adress 1) by mitigating the wording (deprecated -> semi-deprecated, "almost always"). To answer 2), I don't think spending energy documenting a feature that almost nobody uses is worth it. At least, I'm not going to do it, and since nothing happened for months, I guess no one else will.

 Documentation/git-ls-files.txt |    6 ++++++
 1 files changed, 6 insertions(+), 0 deletions(-)

Show changes to Documentation/git-ls-files.txt +6 −0

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 3521637..2cc3243 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -106,6 +106,12 @@ 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` is almost always a
+	superior alternative, and users should look at
+	linkgit:git-status[1] `--short` or linkgit:git-diff[1]
+	`--name-status` for more user-friendly alternatives.
+
 	Identify the file status with the following tags (followed by
 	a space) at the start of each line:
 	H::	cached

-- 
1.7.2.19.g9a302.dirty

Junio C Hamano· Jul 27, 2010, 17:36 UTC · re: Matthieu Moy · lore

Re: [PATCH v2] Document ls-files -t as semi-obsolete.

Sounds good; comments from others?

Michele Ballabio· Jul 27, 2010, 19:07 UTC · re: Matthieu Moy · lore

Re: [PATCH v2] Document ls-files -t as semi-obsolete.

On Monday 26 July 2010, Matthieu Moy wrote:

Show 20 quoted lines

>  Documentation/git-ls-files.txt |    6 ++++++
>  1 files changed, 6 insertions(+), 0 deletions(-)
> 
> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
> index 3521637..2cc3243 100644
> --- a/Documentation/git-ls-files.txt
> +++ b/Documentation/git-ls-files.txt
> @@ -106,6 +106,12 @@ 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` is almost always a
> +	superior alternative, and users should look at
> +	linkgit:git-status[1] `--short` or linkgit:git-diff[1]
> +	`--name-status` for more user-friendly alternatives.
> +
>  	Identify the file status with the following tags (followed by
>  	a space) at the start of each line:
>  	H::	cached

I think this breaks formatting. Shouldn't it be more like the following? (I.e. with a single '+' before "Identify...").

And maybe rephrase the line "Identify the file status with the following tags (followed by a space) at the start of each line" into "This option identifies..." just to set apart "semi-deprecation" and "explanation" of the option.

Show changes to Documentation/git-ls-files.txt +15 −9

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 3521637..ef84d41 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -106,15 +106,21 @@ OPTIONS
 	with `-s` or `-u` options does not make any sense.
 
 -t::
-	Identify 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
+	This feature is semi-deprecated. For scripting purpose,
+	linkgit:git-status[1] `--porcelain` is almost always a
+	superior alternative, and users should look at
+	linkgit:git-status[1] `--short` or linkgit:git-diff[1]
+	`--name-status` for more user-friendly alternatives.
++
+Identify 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
 
 -v::
 	Similar to `-t`, but use lowercase letters for files

Matthieu Moy· Jul 27, 2010, 21:02 UTC · re: Michele Ballabio · lore

Re: [PATCH v2] Document ls-files -t as semi-obsolete.

Michele Ballabio <barra_cuda@katamail.com> writes:

> I think this breaks formatting. Shouldn't it be more like the following?
> (I.e. with a single '+' before "Identify...").

Your version wraps the list and makes it unreadable. A newline between the paragraph and the list seems to fix this.

Show 7 quoted lines

> And maybe rephrase the line
> "Identify the file status with the following tags (followed by
> a space) at the start of each line"
> into
> "This option identifies..."
> just to set apart "semi-deprecation" and "explanation" of the
> option.

I buy this.

New version comming soon.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Matthieu Moy· Jul 27, 2010, 21:11 UTC · re: Matthieu Moy · lore

[PATCH v3] Document ls-files -t as semi-obsolete.

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.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
Should fix the formatting issue.

Finally, I also added a mention of diff-tree --name-status too.

 Documentation/git-ls-files.txt |   12 ++++++++++--
 1 files changed, 10 insertions(+), 2 deletions(-)

Show changes to Documentation/git-ls-files.txt +10 −2

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 3521637..710e87a 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -106,8 +106,16 @@ OPTIONS
 	with `-s` or `-u` options does not make any sense.
 
 -t::
-	Identify the file status with the following tags (followed by
-	a space) at the start of each line:
+	This feature is semi-deprecated. For scripting purpose,
+	linkgit:git-status[1] `--porcelain` and
+	linkgit:git-diff-tree[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

-- 
1.7.2.25.g50ec3

Jeff King· Jul 28, 2010, 04:00 UTC · re: Matthieu Moy · lore

Re: [PATCH v3] Document ls-files -t as semi-obsolete.

On Tue, Jul 27, 2010 at 11:11:13PM +0200, Matthieu Moy wrote:

Show 9 quoted lines

>  -t::
> -	Identify the file status with the following tags (followed by
> -	a space) at the start of each line:
> +	This feature is semi-deprecated. For scripting purpose,
> +	linkgit:git-status[1] `--porcelain` and
> +	linkgit:git-diff-tree[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.

Shouldn't it be diff-files and not diff-tree?

-Peff

Matthieu Moy· Jul 28, 2010, 07:24 UTC · re: Jeff King · lore

[PATCH v4] Document ls-files -t as semi-obsolete.

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.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
Just s/diff-tree/diff-files/ (thanks to Peff for the correction) compared to v3.

 Documentation/git-ls-files.txt |   12 ++++++++++--
 1 files changed, 10 insertions(+), 2 deletions(-)

Show changes to Documentation/git-ls-files.txt +10 −2

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 3521637..bd919f2 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -106,8 +106,16 @@ OPTIONS
 	with `-s` or `-u` options does not make any sense.
 
 -t::
-	Identify the file status with the following tags (followed by
-	a space) at the start of each line:
+	This feature is semi-deprecated. For scripting purpose,
+	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

-- 
1.7.2.25.g9ebe3

Jeff King· Jul 27, 2010, 19:58 UTC · re: Matthieu Moy · lore

Re: [PATCH v2] Document ls-files -t as semi-obsolete.

On Mon, Jul 26, 2010 at 06:39:51PM +0200, Matthieu Moy wrote:

Show 5 quoted lines

> 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 agree with the goal, but one nit:

Show 6 quoted lines

>  -t::
> +	This feature is semi-deprecated. For scripting purpose,
> +	linkgit:git-status[1] `--porcelain` is almost always a
> +	superior alternative, and users should look at
> +	linkgit:git-status[1] `--short` or linkgit:git-diff[1]
> +	`--name-status` for more user-friendly alternatives.

Isn't "git diff-files --name-status" the closest plumbing analogue? Git status actually does a lot of extra work.

Also, while testing this, I got confused. Does "ls-files -t" even work, or am I totally misunderstanding it? I tried:

  mkdir repo && cd repo && git init &&
  echo content >file1 &&
  echo content >file2 &&
  git add . &&
  git commit -m one &&
  echo content >>file1 &&
  echo content >>file2 &&
  git add file1 &&
  git ls-files -t

which yields:

  H file1
  H file2

Shouldn't one of them be marked "C"hanged (I think file2, but that was what I was double-checking)?

-Peff

Matthieu Moy· Jul 27, 2010, 20:11 UTC · re: Jeff King · lore

Re: [PATCH v2] Document ls-files -t as semi-obsolete.

Jeff King <peff@peff.net> writes:

Show 19 quoted lines

> On Mon, Jul 26, 2010 at 06:39:51PM +0200, Matthieu Moy wrote:
>
>> 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 agree with the goal, but one nit:
>
>>  -t::
>> +	This feature is semi-deprecated. For scripting purpose,
>> +	linkgit:git-status[1] `--porcelain` is almost always a
>> +	superior alternative, and users should look at
>> +	linkgit:git-status[1] `--short` or linkgit:git-diff[1]
>> +	`--name-status` for more user-friendly alternatives.
>
> Isn't "git diff-files --name-status" the closest plumbing analogue? Git
> status actually does a lot of extra work.

git diff-files --name-status won't show untracked files, while "git ls-files -t -o" will for example. I agree that "git status" does extra work, but that's what you usually want when you want to know the status of files. We already mention "git diff --name-status", so people looking for "git diff-tree --name-status" should be able to find it.

> Also, while testing this, I got confused. Does "ls-files -t" even work,
> or am I totally misunderstanding it? I tried:

Many people tried to understand what "ls-files -t" was supposed to do, including myself, and I'm afraid nobody succeeded.

> Shouldn't one of them be marked "C"hanged (I think file2, but that was
> what I was double-checking)?

You should ask "git ls-files -t -m" if you want to see modified files.

I'm afraid we have another proof that we should discourage the use of this feature ;-).

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Jeff King· Jul 27, 2010, 21:06 UTC · re: Matthieu Moy · lore

Re: [PATCH v2] Document ls-files -t as semi-obsolete.

On Tue, Jul 27, 2010 at 10:11:04PM +0200, Matthieu Moy wrote:

Show 9 quoted lines

> > Isn't "git diff-files --name-status" the closest plumbing analogue? Git
> > status actually does a lot of extra work.
> 
> git diff-files --name-status won't show untracked files, while "git
> ls-files -t -o" will for example. I agree that "git status" does extra
> work, but that's what you usually want when you want to know the
> status of files. We already mention "git diff --name-status", so
> people looking for "git diff-tree --name-status" should be able to
> find it.

Good point. I was thinking of "ls-files -t" by itself, but you are likely to ask for other things anyway.

> > Shouldn't one of them be marked "C"hanged (I think file2, but that was
> > what I was double-checking)?
> 
> You should ask "git ls-files -t -m" if you want to see modified files.

OK, that makes sense, I guess.

> I'm afraid we have another proof that we should discourage the use of
> this feature ;-).

I think we all agree on that bit. :)

-Peff