{"thread":{"id":"61507","subject":"[PATCH] diff: document what --name-only shows","startedAt":"2024-05-17T17:14:52Z","lastAt":"2024-05-22T01:35:41Z","messageCount":3,"participants":["Junio C Hamano","Nathan Faulkner"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"494988","messageId":"xmqqeda0jr7d.fsf@gitster.g","threadId":"61507","inReplyTo":null,"subject":"[PATCH] diff: document what --name-only shows","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-17T17:14:46Z","receivedAt":"2024-05-17T17:14:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"The \"--name-only\" option is about showing the name of each file in\nthe post-image tree that got changed and nothing else (like \"was it\ncreated?\"). Unlike the \"--name-status\" option that tells how the\nchange happened (e.g., renamed with similarity), it does not give\nanything else, like the name of the corresponding file in the old\ntree.\n\nFor example, if you start from a clean checkout that has a file\nwhose name is COPYING, here is what you would see:\n\n $ git mv COPYING RENAMING\n $ git diff -M --name-only HEAD\n RENAMING\n $ git diff -M --name-status HEAD\n R100\tCOPYING\tRENAMING\n\nLack of the description of this fact has confused readers in the\npast. Even back when dda2d79a ([PATCH] Clean up diff option\ndescriptions., 2005-07-13) documented \"--name-only\", \"git diff\"\nalready supported the renames, so in a sense, from day one, this\nshould have been documented more clearly but it wasn't.\n\nBelatedly clarify it.\n\nSigned-off-by: Junio C Hamano \n---\n\n * In the \"how about this\" patch, I incorrectly said \"before tree\",\n in an failed attempt to use fewer jargon, but it was misguided.\n The names are taken from the post-image (i.e. \"after\") tree, and\n we already use post-image in the same document.\n\n Also this version uses a bit of grammar trick to rephrase so that\n it is clear that we are talking about a single changed file\n having up to two names by mentioning \"each changed file\". That\n way, the phrasing strongly hints that \"--name-only\" shows only\n the name in the post-image tree while \"--name-status\" may show\n both names.\n\n Documentation/diff-options.txt | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 7d73e976d9..0c456dfd0c 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -318,12 +318,13 @@ explained for the configuration variable `core.quotePath` (see\n linkgit:git-config[1]).\n \n --name-only::\n-\tShow only names of changed files. The file names are often encoded in UTF-8.\n+\tShow only the name of each changed file in the post-image tree.\n+\tThe file names are often encoded in UTF-8.\n \tFor more information see the discussion about encoding in the linkgit:git-log[1]\n \tmanual page.\n \n --name-status::\n-\tShow only names and status of changed files. See the description\n+\tShow only the name(s) and status of each changed file. See the description\n \tof the `--diff-filter` option on what the status letters mean.\n \tJust like `--name-only` the file names are often encoded in UTF-8.\n \n-- \n2.45.1-204-gd8ab1d464d\n\n"},{"id":"495040","messageId":"4c4049e9-f5fa-41c3-8a6a-df4fca2f07f1@gmail.com","threadId":"61507","inReplyTo":"xmqqeda0jr7d.fsf@gitster.g","subject":"Re: [PATCH] diff: document what --name-only shows","fromName":"Nathan Faulkner","fromEmail":"natedogith1@gmail.com","sentAt":"2024-05-18T19:10:01Z","receivedAt":"2024-05-18T19:10:03Z","isPatch":true,"sender":{"key":"natedogith1@gmail.com","avatar":null},"body":"> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\n> index 7d73e976d9..0c456dfd0c 100644\n> --- a/Documentation/diff-options.txt\n> +++ b/Documentation/diff-options.txt\n> @@ -318,12 +318,13 @@ explained for the configuration variable `core.quotePath` (see\n> linkgit:git-config[1]).\n> \n> --name-only::\n> -\tShow only names of changed files. The file names are often encoded in UTF-8.\n> +\tShow only the name of each changed file in the post-image tree.\n> +\tThe file names are often encoded in UTF-8.\n> \tFor more information see the discussion about encoding in the linkgit:git-log[1]\n> \tmanual page.\n> \n> --name-status::\n> -\tShow only names and status of changed files. See the description\n> +\tShow only the name(s) and status of each changed file. See the description\n> \tof the `--diff-filter` option on what the status letters mean.\n> \tJust like `--name-only` the file names are often encoded in UTF-8.\n> \n\nThis new description sounds to me like it only shows files that exist in \nthe to-commit, not any files that were deleted.\n"},{"id":"495259","messageId":"xmqq7cfmiq6t.fsf@gitster.g","threadId":"61507","inReplyTo":"4c4049e9-f5fa-41c3-8a6a-df4fca2f07f1@gmail.com","subject":"Re: [PATCH] diff: document what --name-only shows","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-05-22T01:35:38Z","receivedAt":"2024-05-22T01:35:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Nathan Faulkner writes:\n\n> This new description sounds to me like it only shows files that exist\n> in the to-commit, not any files that were deleted.\n\nTrue. \n\nThe thing is \"diff\" works on pair of files from old side and new\nside, so a removed path still conceptually exists on both sides as a\nchange from\n\n \n\nto\n\n \n\nIt is the same story for a created path.\n\nHaving learned that, a proposal to rephrase the updated\ndocumentation is very much welcomed.\n\nThanks.\n\n"}]}