[PATCH 1/2] Documentation/diff-format: state in which cases porcelain status is T

[PATCH 1/2] Documentation/diff-format: state in which cases porcelain status is T

[Johannes Altmanninger]

Porcelain status letter T is documented as "type of the file", which
is technically correct but not enough information for users that are
not so familiar with this term from systems programming. In particular,
given that the only supported file types are regular files and symbolic
links, the term "file type" is surely opaque to the many(?) users who
are not aware that symbolic links can be tracked - I thought that a
"chmod +x" would result in a T status (wrong, it's M).

Explicitly document the three file types (including submodules).
This makes life easier for tool authors, but has potential to go
out of date if a new type is ever added. We could avoid this with a
targeted test, or by using a reStructuredText directive to include the
list of file types from a single source.  Probably not worth it. The
next patch will copy this snippet to git-status.txt though.

Signed-off-by: Johannes Altmanninger <aclopte@gmail.com>
---

(The implementation calls the third type "gitlink" but for users that's
always a submodule, AFAICT)

 Documentation/diff-format.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
index fbbd410a84..7a9c3b6ff4 100644
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.txt
@@ -59,7 +59,7 @@ Possible status letters are:
 - D: deletion of a file
 - M: modification of the contents or mode of a file
 - R: renaming of a file
-- T: change in the type of the file
+- T: change in the type of the file (regular file, symbolic link or submodule)
 - U: file is unmerged (you must complete the merge before it can
   be committed)
 - X: "unknown" change type (most probably a bug, please report it)
-- 
2.33.0.rc2.dirty

[PATCH 2/2] Documentation/git-status: document porcelain status T (typechange)

[Johannes Altmanninger]

As reported in [1], T is missing from the description of porcelain
status letters in git-status(1) (whereas T is documented in
git-diff-files(1) and friends). Document T right after M (modified)
because the two are very similar.

A porcelain status containing C (copied) is impossible because "git
status" does not detect copies, only renames. I was going to delete
mentions of C from git-status.txt because it keeps confusing users [2]
but a discussion from 2014 suggests that "git status" should re-learn
to detect copies, which was disabled in 2005 for (obsolete) performance
reasons [3].

[1] https://github.com/fish-shell/fish-shell/issues/8311
[2] https://www.reddit.com/r/git/comments/ppc2l9/how_to_get_a_file_with_copied_status/
[3] https://marc.info/?l=git&m=141755095826447&w=2

Signed-off-by: Johannes Altmanninger <aclopte@gmail.com>
---
 Documentation/git-status.txt | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 83f38e3198..40f308c6a6 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -207,6 +207,7 @@ show tracked paths:
 
 * ' ' = unmodified
 * 'M' = modified
+* 'T' = file type changed (regular file, symbolic link or submodule)
 * 'A' = added
 * 'D' = deleted
 * 'R' = renamed
@@ -217,14 +218,16 @@ show tracked paths:
 X          Y     Meaning
 -------------------------------------------------
 	 [AMD]   not updated
-M        [ MD]   updated in index
-A        [ MD]   added to index
+M        [ MTD]  updated in index
+T        [ MTD]  type changed in index
+A        [ MTD]  added to index
 D                deleted from index
-R        [ MD]   renamed in index
-C        [ MD]   copied in index
-[MARC]           index and work tree matches
-[ MARC]     M    work tree changed since index
-[ MARC]     D    deleted in work tree
+R        [ MTD]  renamed in index
+C        [ MTD]  copied in index
+[MTARC]          index and work tree matches
+[ MTARC]    M    work tree changed since index
+[ MTARC]    T    type changed in work tree since index
+[ MTARC]    D    deleted in work tree
 [ D]        R    renamed in work tree
 [ D]        C    copied in work tree
 -------------------------------------------------
-- 
2.33.0.rc2.dirty

Re: [PATCH 2/2] Documentation/git-status: document porcelain status T (typechange)

[Johannes Altmanninger]

In case anyone is curious and lazy, here is a script that generates all
possible status letters containing T:

#!/bin/sh

set -e

_T() {
	touch file-1.T
	git add file-1.T
	git commit -q -m add
	rm file-1.T
	ln -s /dev/null file-1.T
}

MT() {
	touch file-1MT
	git add file-1MT
	git commit -q -m add
	echo modify > file-1MT
	git add file-1MT
	ln -sf /dev/null file-1MT
}

TM() {
	ln -sf /dev/null file-1TM
	git add file-1TM
	git commit -q -m add
	rm file-1TM
	touch file-1TM
	git add file-1TM
	echo modify > file-1TM
}

TT() {
	touch file-1TT
	git add file-1TT
	git commit -q -m add
	ln -sf /dev/null file-1TT
	git add file-1TT
	rm file-1TT
	touch file-1TT
}

TD() {
	touch file-1TD
	git add file-1TD
	git commit -q -m add
	ln -sf /dev/null file-1TD
	git add file-1TD
	rm file-1TD
}

AT() {
	touch file-1AT
	git add file-1AT
	git commit -q -m add
	ln -sf /dev/null file-1AT
}

RT() {
	touch file-2RT
	git add file-2RT
	git commit -q -m add
	git mv file-2RT new-file-2RT
	ln -sf /dev/null new-file-2RT
}

T_() {
	touch file-1T.
	git add file-1T.
	git commit -q -m add
	ln -sf /dev/null file-1T.
	git add file-1T.
}

cd "$(mktemp -d)"
git init -q
git commit -q --allow-empty -m initial\ commit

for state in _T MT TM TT TD AT RT T_
do
	git reset -q --hard :/initial.commit
	"$state"
	git status --porcelain=2
done

Re: [PATCH 2/2] Documentation/git-status: document porcelain status T (typechange)

[Elijah Newren]

On Sat, Oct 2, 2021 at 2:38 PM Johannes Altmanninger <aclopte@gmail.com> wrote:
>
> As reported in [1], T is missing from the description of porcelain
> status letters in git-status(1) (whereas T is documented in
> git-diff-files(1) and friends). Document T right after M (modified)
> because the two are very similar.

Good; thanks for sending this in.

> A porcelain status containing C (copied) is impossible because "git
> status" does not detect copies, only renames.

This is no true (since ~2018); here's an example:

    $ cp -a README.md README-copy
    $ echo garbage >>README.md
    $ git add README-copy README.md
    $ git -c status.renames=copy status --porcelain
    C  README.md -> README-copy
    M  README.md

You can also use diff.renames instead of status.renames, since the
latter defaults to the former.  Note that you do need to both modify
and stage README.md in the example above to see the copy status.

> I was going to delete
> mentions of C from git-status.txt because it keeps confusing users [2]
> but a discussion from 2014 suggests that "git status" should re-learn
> to detect copies, which was disabled in 2005 for (obsolete) performance
> reasons [3].

That thread you refer to suggests it was turned off because copy
detection meant the equivalent of find-copies-harder, and that thread
also provided numbers showing find-copies-harder would still be very
painful performance-wise.  Perhaps the "obsolete performance reasons"
was meant to imply that basic copy detection is cheaper since it does
something different today than what status's copy detection did back
then, but summarizing this as "obsolete performance reasons" feels
misleading to me.

> [1] https://github.com/fish-shell/fish-shell/issues/8311
> [2] https://www.reddit.com/r/git/comments/ppc2l9/how_to_get_a_file_with_copied_status/
> [3] https://marc.info/?l=git&m=141755095826447&w=2

Links to lore.kernel.org would be much preferred to marc.info links;
here that would be
https://lore.kernel.org/git/20141202200910.GB23461@peff.net/.

The lore.kernel.org links provide an interface to easily search for
other mailing list messages, and use the Message-ID in the URL which
makes it easier for people to find the message in other locations,
etc.

> Signed-off-by: Johannes Altmanninger <aclopte@gmail.com>
> ---
>  Documentation/git-status.txt | 17 ++++++++++-------
>  1 file changed, 10 insertions(+), 7 deletions(-)
>
> diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
> index 83f38e3198..40f308c6a6 100644
> --- a/Documentation/git-status.txt
> +++ b/Documentation/git-status.txt
> @@ -207,6 +207,7 @@ show tracked paths:
>
>  * ' ' = unmodified
>  * 'M' = modified
> +* 'T' = file type changed (regular file, symbolic link or submodule)
>  * 'A' = added
>  * 'D' = deleted
>  * 'R' = renamed
> @@ -217,14 +218,16 @@ show tracked paths:
>  X          Y     Meaning
>  -------------------------------------------------
>          [AMD]   not updated
> -M        [ MD]   updated in index
> -A        [ MD]   added to index
> +M        [ MTD]  updated in index
> +T        [ MTD]  type changed in index
> +A        [ MTD]  added to index
>  D                deleted from index
> -R        [ MD]   renamed in index
> -C        [ MD]   copied in index
> -[MARC]           index and work tree matches
> -[ MARC]     M    work tree changed since index
> -[ MARC]     D    deleted in work tree
> +R        [ MTD]  renamed in index
> +C        [ MTD]  copied in index
> +[MTARC]          index and work tree matches
> +[ MTARC]    M    work tree changed since index
> +[ MTARC]    T    type changed in work tree since index
> +[ MTARC]    D    deleted in work tree

Looks good up to here.

>  [ D]        R    renamed in work tree
>  [ D]        C    copied in work tree

This wasn't something you added; it appears these two came from commit
176ea74793 ("wt-status.c: handle worktree renames", 2017-12-27).
However, I don't think the 'D' part of these examples is possible.  If
a file is deleted in the index relative to HEAD (what the 'D' means),
then comparing the index to the worktree means the file didn't even
exist in the index.  Thus no delete pair for that file will be passed
to diffcore-rename, and without a delete pair for some file, there is
nothing for the add pairs to be combined with to create a rename or
copy pair.  So these lines are misleading and should only have a space
in the first column rather than either a space or 'D'.

That said, of course, since this wasn't caused by your patch, you are
under no obligation to fix.  It would go nicely with your series,
though.  Would you like to add another patch to your series to fix
that, or would you rather that I contributed such a patch separately?

Thanks for the contribution!

Re: [PATCH 2/2] Documentation/git-status: document porcelain status T (typechange)

[Johannes Altmanninger]

Thanks for the review, I'll send v2 which addresses comments and makes some
minor hanges to the commit messages.

On Sat, Oct 02, 2021 at 04:29:52PM -0700, Elijah Newren wrote:
> > A porcelain status containing C (copied) is impossible because "git
> > status" does not detect copies, only renames.
> 
> This is no true (since ~2018); here's an example:

Ah my bad. Turns out skimming git-status(1) was not enough.  I added patch
4/4 to make that easier (or at least document that it *is* possible).

> 
>     $ cp -a README.md README-copy
>     $ echo garbage >>README.md
>     $ git add README-copy README.md
>     $ git -c status.renames=copy status --porcelain
>     C  README.md -> README-copy
>     M  README.md
> 
> You can also use diff.renames instead of status.renames, since the
> latter defaults to the former.  Note that you do need to both modify
> and stage README.md in the example above to see the copy status.

Wow yeah, this is quite a special case.

> 
> > I was going to delete
> > mentions of C from git-status.txt because it keeps confusing users [2]
> > but a discussion from 2014 suggests that "git status" should re-learn
> > to detect copies, which was disabled in 2005 for (obsolete) performance
> > reasons [3].
> 
> That thread you refer to suggests it was turned off because copy
> detection meant the equivalent of find-copies-harder, and that thread
> also provided numbers showing find-copies-harder would still be very
> painful performance-wise.  Perhaps the "obsolete performance reasons"
> was meant to imply that basic copy detection is cheaper since it does
> something different today than what status's copy detection did back
> then, but summarizing this as "obsolete performance reasons" feels
> misleading to me.

Right, I should have acknowledged the change to copy detection.

> 
> Links to lore.kernel.org would be much preferred to marc.info links;
> here that would be
> https://lore.kernel.org/git/20141202200910.GB23461@peff.net/.
> 
> The lore.kernel.org links provide an interface to easily search for
> other mailing list messages, and use the Message-ID in the URL which
> makes it easier for people to find the message in other locations,
> etc.

got it

> 
> >  [ D]        R    renamed in work tree
> >  [ D]        C    copied in work tree
> 
> This wasn't something you added; it appears these two came from commit
> 176ea74793 ("wt-status.c: handle worktree renames", 2017-12-27).
> However, I don't think the 'D' part of these examples is possible.  If
> a file is deleted in the index relative to HEAD (what the 'D' means),
> then comparing the index to the worktree means the file didn't even
> exist in the index.  Thus no delete pair for that file will be passed
> to diffcore-rename, and without a delete pair for some file, there is
> nothing for the add pairs to be combined with to create a rename or
> copy pair.  So these lines are misleading and should only have a space
> in the first column rather than either a space or 'D'.
> 
> That said, of course, since this wasn't caused by your patch, you are
> under no obligation to fix.  It would go nicely with your series,
> though.  Would you like to add another patch to your series to fix
> that, or would you rather that I contributed such a patch separately?

Ok I've added patch 1/4

[PATCH v2 1/4] Documentation/git-status: remove impossible porcelain status DR and DC

[Johannes Altmanninger]

Commit 176ea74793 ("wt-status.c: handle worktree renames", 2017-12-27)
made a porcelain status like .R or .C possible. They occur only when
the source file is added to the index and the destination file is
added with --intent-to-add.

They also documented DR, but that status is impossible.  The index
change D means that the source file does not exist in the index.
The worktree change R/C states that the file has been renamed/copied
since the index, but that's impossible if it did not exist there.

Reported-by: Elijah Newren <newren@gmail.com>
Signed-off-by: Johannes Altmanninger <aclopte@gmail.com>
---
 Documentation/git-status.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(the diff looks off by one column but that's just because we use tabs for indentation)

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 83f38e3198..20f496094a 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -225,8 +225,8 @@ C        [ MD]   copied in index
 [MARC]           index and work tree matches
 [ MARC]     M    work tree changed since index
 [ MARC]     D    deleted in work tree
-[ D]        R    renamed in work tree
-[ D]        C    copied in work tree
+	    R    renamed in work tree
+	    C    copied in work tree
 -------------------------------------------------
 D           D    unmerged, both deleted
 A           U    unmerged, added by us
-- 
2.33.0.rc2.dirty

[PATCH v2 2/4] Documentation/diff-format: state in which cases porcelain status is T

[Johannes Altmanninger]

Porcelain status letter T is documented as "type of the file", which
is technically correct but not enough information for users that are
not so familiar with this term from systems programming. In particular,
given that the only supported file types are "regular file", "symbolic
link" and "submodule", the term "file type" is surely opaque to the
many(?) users who are not aware that symbolic links can be tracked -
I thought that a "chmod +x" could cause the T status (wrong, it's M).

Explicitly document the three file types so users know if/how they
want to handle this.

Signed-off-by: Johannes Altmanninger <aclopte@gmail.com>
---
 Documentation/diff-format.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
index fbbd410a84..7a9c3b6ff4 100644
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.txt
@@ -59,7 +59,7 @@ Possible status letters are:
 - D: deletion of a file
 - M: modification of the contents or mode of a file
 - R: renaming of a file
-- T: change in the type of the file
+- T: change in the type of the file (regular file, symbolic link or submodule)
 - U: file is unmerged (you must complete the merge before it can
   be committed)
 - X: "unknown" change type (most probably a bug, please report it)
-- 
2.33.0.rc2.dirty

[PATCH v2 3/4] Documentation/git-status: document porcelain status T (typechange)

[Johannes Altmanninger]

As reported in [1], T is missing from the description of porcelain
status letters in git-status(1) (whereas T *is* documented in
git-diff-files(1) and friends). Document T right after M (modified)
because the two are very similar.

[1] https://github.com/fish-shell/fish-shell/issues/8311

Signed-off-by: Johannes Altmanninger <aclopte@gmail.com>
---
 Documentation/git-status.txt | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 20f496094a..255dc6af9b 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -207,6 +207,7 @@ show tracked paths:
 
 * ' ' = unmodified
 * 'M' = modified
+* 'T' = file type changed (regular file, symbolic link or submodule)
 * 'A' = added
 * 'D' = deleted
 * 'R' = renamed
@@ -217,14 +218,16 @@ show tracked paths:
 X          Y     Meaning
 -------------------------------------------------
 	 [AMD]   not updated
-M        [ MD]   updated in index
-A        [ MD]   added to index
+M        [ MTD]  updated in index
+T        [ MTD]  type changed in index
+A        [ MTD]  added to index
 D                deleted from index
-R        [ MD]   renamed in index
-C        [ MD]   copied in index
-[MARC]           index and work tree matches
-[ MARC]     M    work tree changed since index
-[ MARC]     D    deleted in work tree
+R        [ MTD]  renamed in index
+C        [ MTD]  copied in index
+[MTARC]          index and work tree matches
+[ MTARC]    M    work tree changed since index
+[ MTARC]    T    type changed in work tree since index
+[ MTARC]    D    deleted in work tree
 	    R    renamed in work tree
 	    C    copied in work tree
 -------------------------------------------------
-- 
2.33.0.rc2.dirty

[PATCH v2 4/4] Documentation/git-status: mention how to detect copies

[Johannes Altmanninger]

The man page documents that git-status can find copies, but does not
mention how. Whereas git-diff has command line options -C, there is
no such option for git-status - it will only detect copies when the
"status.renames" config option is "copies" or "copy". Document that
in git-status.txt because this has confused me and others[1].

[1]: https://www.reddit.com/r/git/comments/ppc2l9/how_to_get_a_file_with_copied_status/

Signed-off-by: Johannes Altmanninger <aclopte@gmail.com>
---
 Documentation/git-status.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 255dc6af9b..8f959afa0f 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -211,7 +211,7 @@ show tracked paths:
 * 'A' = added
 * 'D' = deleted
 * 'R' = renamed
-* 'C' = copied
+* 'C' = copied (if config option status.renames is set to "copies")
 * 'U' = updated but unmerged
 
 ....
-- 
2.33.0.rc2.dirty

Re: [PATCH v2 4/4] Documentation/git-status: mention how to detect copies

[Bagas Sanjaya]

On 05/10/21 02.00, Johannes Altmanninger wrote:
> @@ -211,7 +211,7 @@ show tracked paths:
>   * 'A' = added
>   * 'D' = deleted
>   * 'R' = renamed
> -* 'C' = copied
> +* 'C' = copied (if config option status.renames is set to "copies")
>   * 'U' = updated but unmerged
>   
>   ....
> 

The config name and value can be formatted to monospace 
("`status.renames`" and "`copies`" respectively).

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH v2 4/4] Documentation/git-status: mention how to detect copies

[Johannes Altmanninger]

On Tue, Oct 05, 2021 at 04:48:00PM +0700, Bagas Sanjaya wrote:
> On 05/10/21 02.00, Johannes Altmanninger wrote:
> > -* 'C' = copied
> > +* 'C' = copied (if config option status.renames is set to "copies")
> 
> The config name and value can be formatted to monospace ("`status.renames`"
> and "`copies`" respectively).

I wasn't sure whether to add backticks to status.renames because we are
already inconsistent in this file (search for "config option").
Anyway I agree that backticks look better here (makes it bold in the man page).

Maybe we should automate this? We can write a test that makes sure that we
always use backticks around config keys, at least for new changes.

---

I didn't add backticks to "copies" to be consistent with this part before the context

	Ignore changes to submodules when looking for changes. <when> can be
	either "none", "untracked", "dirty" or "all", which is the default.

Re: [PATCH v2 4/4] Documentation/git-status: mention how to detect copies

[Bagas Sanjaya]

On 06/10/21 02.42, Johannes Altmanninger wrote:
> I wasn't sure whether to add backticks to status.renames because we are
> already inconsistent in this file (search for "config option").
> Anyway I agree that backticks look better here (makes it bold in the man page).
> 
> Maybe we should automate this? We can write a test that makes sure that we
> always use backticks around config keys, at least for new changes.
> 
> ---
> 
> I didn't add backticks to "copies" to be consistent with this part before the context
> 
> 	Ignore changes to submodules when looking for changes. <when> can be
> 	either "none", "untracked", "dirty" or "all", which is the default.
> 

I think for consistency, we can go with automated style changes that use 
backticks to monospace:
     - file name and paths
     - daemons/services
     - configuration names and values
     - file content (use ```...``` block unless inline)
     - command-line
     - keyboard keys (dunno?)
     - any other inline text that needs to be written exactly

I have seen many times articles that say `Run "foo bar" (no quotes)` 
when they mean `Run `foo bar``.

For the exception you mentioned above it can be monospaced as part of 
automated change above.

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH v2 4/4] Documentation/git-status: mention how to detect copies

[Elijah Newren]

On Tue, Oct 5, 2021 at 10:05 PM Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>
> On 06/10/21 02.42, Johannes Altmanninger wrote:
> > I wasn't sure whether to add backticks to status.renames because we are
> > already inconsistent in this file (search for "config option").
> > Anyway I agree that backticks look better here (makes it bold in the man page).
> >
> > Maybe we should automate this? We can write a test that makes sure that we
> > always use backticks around config keys, at least for new changes.
> >
> > ---
> >
> > I didn't add backticks to "copies" to be consistent with this part before the context
> >
> >       Ignore changes to submodules when looking for changes. <when> can be
> >       either "none", "untracked", "dirty" or "all", which is the default.
> >
>
> I think for consistency, we can go with automated style changes that use
> backticks to monospace:
>      - file name and paths
>      - daemons/services
>      - configuration names and values
>      - file content (use ```...``` block unless inline)
>      - command-line
>      - keyboard keys (dunno?)
>      - any other inline text that needs to be written exactly
>
> I have seen many times articles that say `Run "foo bar" (no quotes)`
> when they mean `Run `foo bar``.
>
> For the exception you mentioned above it can be monospaced as part of
> automated change above.

Doing some cleanup passes on the documentation files would probably be
a good thing, but it'd probably belong in a different series.  Better
to keep this one focused on the fixes being proposed.

Re: [PATCH v2 1/4] Documentation/git-status: remove impossible porcelain status DR and DC

[Junio C Hamano]

Johannes Altmanninger <aclopte@gmail.com> writes:

> diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
> index 83f38e3198..20f496094a 100644
> --- a/Documentation/git-status.txt
> +++ b/Documentation/git-status.txt
> @@ -225,8 +225,8 @@ C        [ MD]   copied in index
>  [MARC]           index and work tree matches
>  [ MARC]     M    work tree changed since index
>  [ MARC]     D    deleted in work tree
> -[ D]        R    renamed in work tree
> -[ D]        C    copied in work tree
> +	    R    renamed in work tree
> +	    C    copied in work tree

I do not see lines with horizontal tabs used in exiting entries to
skip to columns.  Perhaps these two lines should follow suit.

>  -------------------------------------------------
>  D           D    unmerged, both deleted
>  A           U    unmerged, added by us

Re: [PATCH v2 1/4] Documentation/git-status: remove impossible porcelain status DR and DC

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Johannes Altmanninger <aclopte@gmail.com> writes:
>
>> diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
>> index 83f38e3198..20f496094a 100644
>> --- a/Documentation/git-status.txt
>> +++ b/Documentation/git-status.txt
>> @@ -225,8 +225,8 @@ C        [ MD]   copied in index
>>  [MARC]           index and work tree matches
>>  [ MARC]     M    work tree changed since index
>>  [ MARC]     D    deleted in work tree
>> -[ D]        R    renamed in work tree
>> -[ D]        C    copied in work tree
>> +	    R    renamed in work tree
>> +	    C    copied in work tree
>
> I do not see lines with horizontal tabs used in exiting entries to
> skip to columns.  Perhaps these two lines should follow suit.

Nah, there is one before the pre-context of this hunk.  I guess it
is OK, and certainly would not need a reroll for it.

Thanks.

Re: [PATCH 1/2] Documentation/diff-format: state in which cases porcelain status is T

[Elijah Newren]

On Sat, Oct 2, 2021 at 2:38 PM Johannes Altmanninger <aclopte@gmail.com> wrote:
>
> Porcelain status letter T is documented as "type of the file", which
> is technically correct but not enough information for users that are
> not so familiar with this term from systems programming. In particular,
> given that the only supported file types are regular files and symbolic
> links,

and submodules (though users aren't likely to think of that as a "file" type)

> the term "file type" is surely opaque to the many(?) users who
> are not aware that symbolic links can be tracked - I thought that a
> "chmod +x" would result in a T status (wrong, it's M).

Heh, I've probably made that mistake before...and I was actually
thinking of exactly that case while reading this commit message.  Just
goes to show that I'm prone to repeat my mistakes.  Anyway, I'm glad
you discussed the executable bit case in the commit message.

> Explicitly document the three file types (including submodules).
> This makes life easier for tool authors, but has potential to go
> out of date if a new type is ever added. We could avoid this with a
> targeted test, or by using a reStructuredText directive to include the
> list of file types from a single source.  Probably not worth it. The
> next patch will copy this snippet to git-status.txt though.
>
> Signed-off-by: Johannes Altmanninger <aclopte@gmail.com>
> ---
>
> (The implementation calls the third type "gitlink" but for users that's
> always a submodule, AFAICT)
>
>  Documentation/diff-format.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
> index fbbd410a84..7a9c3b6ff4 100644
> --- a/Documentation/diff-format.txt
> +++ b/Documentation/diff-format.txt
> @@ -59,7 +59,7 @@ Possible status letters are:
>  - D: deletion of a file
>  - M: modification of the contents or mode of a file
>  - R: renaming of a file
> -- T: change in the type of the file
> +- T: change in the type of the file (regular file, symbolic link or submodule)
>  - U: file is unmerged (you must complete the merge before it can
>    be committed)
>  - X: "unknown" change type (most probably a bug, please report it)
> --
> 2.33.0.rc2.dirty

Thanks, this change looks good to me, modulo the tiny comment on the
commit message about submodules being another file type.