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 <jrnieder@xxxxxxxxx> --- 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html