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

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

[Matthieu Moy]

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(-)

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

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

[Junio C Hamano]

Sounds good; comments from others?

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

[Michele Ballabio]

On Monday 26 July 2010, Matthieu Moy wrote:
>  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.

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

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

[Jeff King]

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.

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

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

[Matthieu Moy]

Jeff King <peff@peff.net> writes:

> 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/

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

[Matthieu Moy]

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.

> 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/

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

[Jeff King]

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

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

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

[Matthieu Moy]

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>
---
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(-)

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

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

[Jeff King]

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

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

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

[Matthieu Moy]

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>
---
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(-)

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