Re*: git log --name-only improvement: show old file name in rename

Commit Message

Junio C Hamano May 17, 2024, 4 p.m. UTC

Nathan Faulkner <[e-mail]> writes:

> The documentation for --name-only says "Show only names of changed
> files." I would interpret this to mean "output the names of all files
> that changed", not "output the names of all files that changed, unless
> git detected it as renamed".

Interesting observation, but we do show renamed files no?  Even when
there is no content changes?  A quick experiment tells me it does,
so "unless" is not quite correct.

    $ git mv COPYING RENAMING
    $ git diff --name-only -M HEAD
    RENAMING
    $ git diff --name-status -M HEAD
    R100	COPYING	RENAMING

I think that the source of the confusion is actually not renames or
copies but that the explanation does not say in which commit the
phrase "only names of changed files" applies to.

The answer to that question is: Show names of the changed paths in
the post-image tree, i.e. if comparing 'diff A B' (or when 'show B'
is comparing 'diff B^ B'), the names in tree B are shown.

But because that is not explicitly said, a reader can easily mislead
into thinking that we are showing the union of names of files in
both pre-image and post-image trees that were modified.

We'd need something like this, probably.

------- >8 ------------- >8 ------------- >8 -------
Subject: 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.

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

Signed-off-by: Junio C Hamano <[e-mail]>
---
 Documentation/diff-options.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

Comments

Nathan Faulkner May 18, 2024, 12:24 a.m. UTC | #1

On 5/17/2024 12:00 PM, Junio C Hamano wrote:
> Nathan Faulkner <[e-mail]> writes:
> 
>> The documentation for --name-only says "Show only names of changed
>> files." I would interpret this to mean "output the names of all files
>> that changed", not "output the names of all files that changed, unless
>> git detected it as renamed".
> 
> Interesting observation, but we do show renamed files no?  Even when
> there is no content changes?  A quick experiment tells me it does,
> so "unless" is not quite correct.

It seems to me it's not showing the names of all files.  If a file was 
created and a separate file was deleted, but git happens to detect it as 
a rename, it will only show the created file even though from my 
perspective both files changed.

Though even for a true rename, I'd have expected --name-only to show all 
paths that changed (what you want if you're trying to find code owners 
or determine what needs to be rebuilt).

> diff --git c/Documentation/diff-options.txt w/Documentation/diff-options.txt
> index 0e9456957e..b9eaea32d9 100644
> --- c/Documentation/diff-options.txt
> +++ w/Documentation/diff-options.txt
> @@ -329,7 +329,8 @@ 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 in the before-tree of changed files.
> +	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.
>   

That description sounds to me like it only shows files that existed in 
the from-commit, not any files that were created in the to-commit.

If the description is updated, it'd probably be a good idea to 
explicitly call out that --no-renames can be used to get the expected 
behavior of showing all files that changed.


This behavior can also lead to a situation where git diff --name-only 
stops reporting a file as changed when including a newer commit that 
doesn't involve the file.

$ echo '{}' > foo.json; git add .; git commit -m foo
$ rm foo.json; git add .; git commit -m delete
$ echo '{}' > bar.json; git add .; git commit -m bar

$ git diff --name-only HEAD~2 HEAD~1
foo.json
$ git diff --name-only HEAD~1 HEAD
bar.json
$ git diff --name-only HEAD~2 HEAD
bar.json

Junio C Hamano May 18, 2024, 2:05 a.m. UTC | #2

Nathan Faulkner <[e-mail]> writes:

> That description sounds to me like it only shows files that existed in
> the from-commit, not any files that were created in the to-commit.

Sorry, this was a typo/thinko.  An updated version was posted on the
list after the message you are responding to.

Patch

diff --git c/Documentation/diff-options.txt w/Documentation/diff-options.txt
index 0e9456957e..b9eaea32d9 100644
--- c/Documentation/diff-options.txt
+++ w/Documentation/diff-options.txt
@@ -329,7 +329,8 @@  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 in the before-tree of changed files.
+	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.