diff: document what --name-only shows
PATCH 1/1 diff: document what --name-only shows
The "--name-only" option is about showing the name of each file in the post-image tree that got changed and nothing else (like "was it created?"). Unlike the "--name-status" option that tells how the change happened (e.g., renamed with similarity), it does not give anything else, like the name of the corresponding file in the old tree.
For example, if you start from a clean checkout that has a file whose name is COPYING, here is what you would see:
$ git mv COPYING RENAMING
$ git diff -M --name-only HEAD
RENAMING
$ git diff -M --name-status HEAD
R100 COPYING RENAMINGLack of the description of this fact has confused readers in the past. Even back when dda2d79a ([PATCH] Clean up diff option descriptions., 2005-07-13) documented "--name-only", "git diff" already supported the renames, so in a sense, from day one, this should have been documented more clearly but it wasn't.
Belatedly clarify it.
---
* In the "how about this" patch, I incorrectly said "before tree", in an failed attempt to use fewer jargon, but it was misguided. The names are taken from the post-image (i.e. "after") tree, and we already use post-image in the same document.
Also this version uses a bit of grammar trick to rephrase so that it is clear that we are talking about a single changed file having up to two names by mentioning "each changed file". That way, the phrasing strongly hints that "--name-only" shows only the name in the post-image tree while "--name-status" may show both names.
Documentation/diff-options.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)
Documentation/diff-options.txt +3 -2
@@ -318,12 +318,13 @@ explained for the configuration variable `core.quotePath` (see linkgit:git-config[1]). --name-only:: - Show only names of changed files. The file names are often encoded in UTF-8. + Show only the name of each changed file in the post-image tree. + The file names are often encoded in UTF-8. For more information see the discussion about encoding in the linkgit:git-log[1] manual page. --name-status:: - Show only names and status of changed files. See the description + Show only the name(s) and status of each changed file. See the description of the `--diff-filter` option on what the status letters mean. Just like `--name-only` the file names are often encoded in UTF-8.
Signature · 1 line
2.45.1-204-gd8ab1d464d
Quoted 10 lines
Documentation/diff-options.txt +1
-1@@ -318,12 +318,13 @@ explained for the configuration variable `core.quotePath` (see linkgit:git-config[1]). --name-only:: - Show only names of changed files. The file names are often encoded in UTF-8. + Show only the name of each changed file in the post-image tree.
Documentation/diff-options.txt explained for the configuration variable `core.quotePath` (see · line 330
Quoted 10 lines
Documentation/diff-options.txt +2
-1+ The file names are often encoded in UTF-8. For more information see the discussion about encoding in the linkgit:git-log[1] manual page. --name-status:: - Show only names and status of changed files. See the description + Show only the name(s) and status of each changed file. See the description of the `--diff-filter` option on what the status letters mean. Just like `--name-only` the file names are often encoded in UTF-8.
This new description sounds to me like it only shows files that exist in the to-commit, not any files that were deleted.
Quoted 2 lines · Nathan Faulkner
This new description sounds to me like it only shows files that exist in the to-commit, not any files that were deleted.
True.
The thing is "diff" works on pair of files from old side and new side, so a removed path still conceptually exists on both sides as a change from
<old path name, old state (has certain contents)>
to
<new path name, new state (no longer exists)>
It is the same story for a created path.
Having learned that, a proposal to rephrase the updated documentation is very much welcomed.
Thanks.