| Message ID | 20211002213046.725892-1-aclopte@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [1/2] Documentation/diff-format: state in which cases porcelain status is T | expand |
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.
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)
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(-)