Git Mailing List Archive mirror
 help / color / mirror / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: git@vger.kernel.org
Subject: [PATCH] diff: document what --name-only shows
Date: Fri, 17 May 2024 10:14:46 -0700	[thread overview]
Message-ID: <xmqqeda0jr7d.fsf@gitster.g> (raw)

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	RENAMING

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 <gitster@pobox.com>
---

 * 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(-)

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 7d73e976d9..0c456dfd0c 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -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.
 
-- 
2.45.1-204-gd8ab1d464d


             reply	other threads:[~2024-05-17 17:14 UTC|newest]

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2024-05-17 17:14 Junio C Hamano [this message]
2024-05-18 19:10 ` [PATCH] diff: document what --name-only shows Nathan Faulkner
2024-05-22  1:35   ` Junio C Hamano

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=xmqqeda0jr7d.fsf@gitster.g \
    --to=gitster@pobox.com \
    --cc=git@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).