[PATCH] document 'T' status from git-status

[PATCH] document 'T' status from git-status

[Mark Dominus]

From: Mark Dominus <mjd@icgroup.com>

Signed-off-by: Mark Dominus <mjd@plover.com>
---
 Documentation/git-status.txt |    4 ++++
 1 files changed, 4 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 3d51717..e7fc5c3 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -122,6 +122,8 @@ codes can be interpreted as follows:
 * 'R' = renamed
 * 'C' = copied
 * 'U' = updated but unmerged
+* 'T' = file type changed
+  (typically from plain file to symlink, or vice versa)
 
 Ignored files are not listed, unless `--ignored` option is in effect,
 in which case `XY` are `!!`.
@@ -134,9 +136,11 @@ in which case `XY` are `!!`.
     D         [ M]   deleted from index
     R        [ MD]   renamed in index
     C        [ MD]   copied in index
+    T        [ MD]   file type changed in index
     [MARC]           index and work tree matches
     [ MARC]     M    work tree changed since index
     [ MARC]     D    deleted in work tree
+    [ MARC]     T    file type changed in work tree
     -------------------------------------------------
     D           D    unmerged, both deleted
     A           U    unmerged, added by us
-- 
1.7.7.dirty

Re: [PATCH] document 'T' status from git-status

[Junio C Hamano]

Mark Dominus <mjd@plover.com> writes:

> From: Mark Dominus <mjd@icgroup.com>
>
> Signed-off-by: Mark Dominus <mjd@plover.com>
> ---
>  Documentation/git-status.txt |    4 ++++
>  1 files changed, 4 insertions(+), 0 deletions(-)
>
> diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
> index 3d51717..e7fc5c3 100644
> --- a/Documentation/git-status.txt
> +++ b/Documentation/git-status.txt
> @@ -122,6 +122,8 @@ codes can be interpreted as follows:
>  * 'R' = renamed
>  * 'C' = copied
>  * 'U' = updated but unmerged
> +* 'T' = file type changed
> +  (typically from plain file to symlink, or vice versa)
>  
>  Ignored files are not listed, unless `--ignored` option is in effect,
>  in which case `XY` are `!!`.
> @@ -134,9 +136,11 @@ in which case `XY` are `!!`.
>      D         [ M]   deleted from index
>      R        [ MD]   renamed in index
>      C        [ MD]   copied in index
> +    T        [ MD]   file type changed in index
>      [MARC]           index and work tree matches
>      [ MARC]     M    work tree changed since index
>      [ MARC]     D    deleted in work tree
> +    [ MARC]     T    file type changed in work tree

The current organization of this table may need to be rethought, but if we
were to keep it, then this change is far from sufficient. For example, you
do not explain what XY = TT means.

	Side note. The reason why we do not have two independent tables,
	one of which shows "if X is M then it means updated in index, if X
	is A then..." and the other shows "if Y is ' ' then index and
	working tree matches, if Y is 'M' then ...", is because this table
	is meant to show _possible_ combinations. For example, the row
	with X = D shows that only two possible value for Y are ' ' and M
	and A or D are not possible values for Y in that case.

It may be easier to explain if you treated that 'T' is merely a variant of
'M' (this comment applies to the first hunk of your patch that starts at
line 122), i.e.

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

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 3d51717..bc2552e 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -126,6 +126,10 @@ codes can be interpreted as follows:
 Ignored files are not listed, unless `--ignored` option is in effect,
 in which case `XY` are `!!`.
 
+Note that a change in filetype (i.e. a regular file to symbolic link or
+vice versa) is a special case of "modified" and shown as 'T' instead of
+'M'; in the table below an 'M' could be a 'T'.
+
     X          Y     Meaning
     -------------------------------------------------
               [MD]   not updated

Re: [PATCH] document 'T' status from git-status

[Mark Dominus]

On 10/30/2011 02:25 AM, Junio C Hamano wrote:
> Mark Dominus<mjd@plover.com>  writes:
>
>
>> +* 'T' = file type changed
>> +  (typically from plain file to symlink, or vice versa)
>>
>>   Ignored files are not listed, unless `--ignored` option is in effect,
>>   in which case `XY` are `!!`.
>> @@ -134,9 +136,11 @@ in which case `XY` are `!!`.
>>       D         [ M]   deleted from index
>>       R        [ MD]   renamed in index
>>       C        [ MD]   copied in index
>> +    T        [ MD]   file type changed in index
>>       [MARC]           index and work tree matches
>>       [ MARC]     M    work tree changed since index
>>       [ MARC]     D    deleted in work tree
>> +    [ MARC]     T    file type changed in work tree
> The current organization of this table may need to be rethought, but if we
> were to keep it, then this change is far from sufficient. For example, you
> do not explain what XY = TT means.
Thanks for your response.

I did not try to document that because in my experimenting I was not 
able to produce that situation.  T occurs when the filetype (as reported 
by the IS_FMT macro) is different between the two files.  On systems I 
have available, there are essentially five filetypes:  plain file, 
symlink, directory, block and character devices.  Directories are 
handled separately and are not reported by git-status.  Device files 
cannot be added to the index at all.  That leaves only two possible 
filetypes, so of the three files (the committed version, the cached 
version, and the working tree version) two must be the same.

I am aware that on some systems other filetypes may exist.  For example, 
HPUX has an 'H' filetype that is a variant of a directory.  But git 
would treat this as a directory.  Since I was not aware of any situation 
in which TT could arise, I did not try to document it.

Will you be applying the alternative patch you suggested, or would you 
prefer that I try to produce one along those lines?

Re: [PATCH] document 'T' status from git-status

[Junio C Hamano]

Mark Dominus <mjd@icgroup.com> writes:

>> The current organization of this table may need to be rethought, but if we
>> were to keep it, then this change is far from sufficient. For example, you
>> do not explain what XY = TT means.
> Thanks for your response.
>
> I did not try to document that because in my experimenting I was not
> able to produce that situation.

It is trivial if you realize that X is the change between the HEAD and the
index, and Y is the change between the index and the working tree. Most
importantly, no direct comparison between the HEAD and the working tree
gets in the picture.

    $ mv COPYING RENAMING
    $ ln -s RENAMING COPYING
    $ git add COPYING
    $ mv RENAMING COPYING
    $ git status -suno
    TT COPYING

> Will you be applying the alternative patch you suggested, or would you
> prefer that I try to produce one along those lines?

I dunno.

An obvious alternative is to add T next to all occurrences of M in the
table where we say "M is possible", but unless it is accompanied by an
explanation "T is just a special case of M", I suspect the resulting
description would be harder to understand than currently is, and as long
as the reader understands "T is just a special case of M", then there
isn't much point adding T everywhere M appears in the table anyway, so...

Re: [PATCH] document 'T' status from git-status

[Mark Dominus]

> It is trivial if

Yes, it was very stupid of me to miss that.

> I dunno.
>
> An obvious alternative is to add T next to all occurrences of M in the
> table where we say "M is possible", but unless it is accompanied by an
> explanation "T is just a special case of M", I suspect the resulting
> description would be harder to understand than currently is, and as long
> as the reader understands "T is just a special case of M", then there
> isn't much point adding T everywhere M appears in the table anyway, so...

If you are suggesting that the patch you gave is preferable to actually 
including T in the table, then I agree. Your patch is also better than 
what I sent because it includes the unusual word "filetype", which the 
user is likely to search for after seeing it in the git-status output.