Subject: Re: git diff --added (Re: Command-line interface thoughts)

From: Jonathan Nieder <[email-masked]>
Date: Mon, 13 Jun 2011 03:06:18 -0500

Miles Bader wrote:

> "--added" sounds very awkward though; "--staged" is much more natural.

You make a strong case.  How about something like this?

-- >8 --
Subject: Documentation: explain diff --cached in terms of non --cached form

"git diff" is a somewhat odd command, since it has two fairly
different roles:

 - on one hand, it is the command to explain the worktree or index in
   terms of something else;
 - on the other hand, it is the command to compare two blobs, trees,
   or on-disk files.

To a new user, that second role might seem to be the most basic and
most natural, since it is most closely analagous to the ordinary
non-git "diff" command, but in practice the first one is the one that
gets used most often and it is somewhat different.  Avoid surprises
by treating this first role separately in the introductory paragraph
and calling it "primary".

The motivation is that it is hard enough to remember the various 0-
and 1-tree forms of "git diff"; hopefully fending off the distraction
of a false analogy with 2-tree "git diff" will help with that.  This
patch also tries to clarify those mnemonics (especially: "--cached"
mean to use the index in place of the worktree) by rearranging the
material slightly.  The most obvious mechanical changes involved are
listing 0- and 1-tree "git diff" separately in the synopsis and
reordering the text to put "git diff HEAD" before "git diff --cached
HEAD".

Some small wording improvements snuck in while at it, including
mentioning the --staged synonym for --cached a little more often.

Signed-off-by: Jonathan Nieder <[email-masked]>
---
 Documentation/git-diff.txt |   61 +++++++++++++++++++++++--------------------
 1 files changed, 33 insertions(+), 28 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index f8d0819..7a66017 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -9,59 +9,64 @@ git-diff - Show changes between commits, commit and working tree, etc
 SYNOPSIS
 --------
 [verse]
-'git diff' [options] [<commit>] [--] [<path>...]
+'git diff' [options] [--] [<path>...]
+'git diff' [options] <commit> [--] [<path>...]
 'git diff' [options] --cached [<commit>] [--] [<path>...]
 'git diff' [options] <commit> <commit> [--] [<path>...]
 'git diff' [options] [--no-index] [--] <path> <path>
 
 DESCRIPTION
 -----------
-Show changes between the working tree and the index or a tree, changes
-between the index and a tree, changes between two trees, or changes
-between two files on disk.
+The primary purpose of 'git diff' is to compare files in the working
+tree to stored versions in the repository.  It can also be used to
+show changes between the index and a tree, changes between two trees,
+or changes between two files on disk.
 
-'git diff' [--options] [--] [<path>...]::
+'git diff' [options] [--] [<path>...]::
 
 	This form is to view the changes you made relative to
-	the index (staging area for the next commit).  In other
-	words, the differences are what you _could_ tell git to
-	further add to the index but you still haven't.  You can
-	stage these changes by using linkgit:git-add[1].
+	the index (staging area for the next commit).  It is
+	the most common use of 'git diff'; the differences are
+	what you _could_ tell git to further add to the index
+	but you still haven't.  You can stage these changes by
+	using linkgit:git-add[1] (aka linkgit:git-stage[1]).
 +
-If exactly two paths are given and at least one points outside
-the current repository, 'git diff' will compare the two files /
-directories. This behavior can be forced by --no-index.
+If exactly two paths are given and one points outside the current
+repository, 'git diff' will compare the two files or directories.
+This behavior can be forced with the `--no-index` option.
 
-'git diff' [--options] --cached [<commit>] [--] [<path>...]::
-
-	This form is to view the changes you staged for the next
-	commit relative to the named <commit>.  Typically you
-	would want comparison with the latest commit, so if you
-	do not give <commit>, it defaults to HEAD.
-	If HEAD does not exist (e.g. unborned branches) and
-	<commit> is not given, it shows all staged changes.
-	--staged is a synonym of --cached.
-
-'git diff' [--options] <commit> [--] [<path>...]::
+'git diff' [options] <commit> [--] [<path>...]::
 
 	This form is to view the changes you have in your
 	working tree relative to the named <commit>.  You can
-	use HEAD to compare it with the latest commit, or a
+	use HEAD to compare with the latest commit, or a
 	branch name to compare with the tip of a different
 	branch.
 
-'git diff' [--options] <commit> <commit> [--] [<path>...]::
+'git diff' [options] --cached [<commit>] [--] [<path>...]::
+'git diff' [options] --staged [<commit>] [--] [<path>...]::
+
+	If passed --cached or its synonym --staged,
+	'git diff' will view the changes you have staged for
+	the next commit instead of examining the working tree.
+	Typically you would want a comparison with the latest
+	commit, so if you do not give <commit>, it defaults
+	to HEAD.
+	If HEAD does not exist (e.g. unborn branches) and
+	<commit> is not given, it shows all staged changes.
+
+'git diff' [options] <commit> <commit> [--] [<path>...]::
 
 	This is to view the changes between two arbitrary
-	<commit>.
+	commits.
 
-'git diff' [--options] <commit>..<commit> [--] [<path>...]::
+'git diff' [options] <commit>..<commit> [--] [<path>...]::
 
 	This is synonymous to the previous form.  If <commit> on
 	one side is omitted, it will have the same effect as
 	using HEAD instead.
 
-'git diff' [--options] <commit>\...<commit> [--] [<path>...]::
+'git diff' [options] <commit>\...<commit> [--] [<path>...]::
 
 	This form is to view the changes on the branch containing
 	and up to the second <commit>, starting at a common ancestor
-- 
1.7.6.rc1