Documentation: usage for diff combined commits
Document the usage for producing combined commits with "git diff". This includes updating the synopsis section. While here, add the three-dot notation to the synopsis. Make "git diff -h" print the same usage summary as the manual page synopsis, minus the "A..B" form, which is now discouraged. Signed-off-by: Chris Torek <chris.torek@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Chris Torek committed
Jun 12, 2020 at 16:20 UTC
b7e10b2ca210d6a3647910fdecea33581e4eaf0d
2 files changed
+23
-5
Documentation/git-diff.txt
+16
-4
@@ -11,15 +11,17 @@ SYNOPSIS
11
[verse]
12
'git diff' [<options>] [<commit>] [--] [<path>...]
13
'git diff' [<options>] --cached [<commit>] [--] [<path>...]
14
-'git diff' [<options>] <commit> <commit> [--] [<path>...]
14
+'git diff' [<options>] <commit> [<commit>...] <commit> [--] [<path>...]
15
+'git diff' [<options>] <commit>...<commit> [--] [<path>...]
16
'git diff' [<options>] <blob> <blob>
17
'git diff' [<options>] --no-index [--] <path> <path>
18
19
DESCRIPTION
20
-----------
21
Show changes between the working tree and the index or a tree, changes
21
-between the index and a tree, changes between two trees, changes between
22
-two blob objects, or changes between two files on disk.
22
+between the index and a tree, changes between two trees, changes resulting
23
+from a merge, changes between two blob objects, or changes between two
24
+files on disk.
25
26
'git diff' [<options>] [--] [<path>...]::
27
@@ -67,6 +69,15 @@ two blob objects, or changes between two files on disk.
69
one side is omitted, it will have the same effect as
70
using HEAD instead.
71
72
+'git diff' [<options>] <commit> [<commit>...] <commit> [--] [<path>...]::
73
+
74
+ This form is to view the results of a merge commit. The first
75
+ listed <commit> must be the merge itself; the remaining two or
76
+ more commits should be its parents. A convenient way to produce
77
+ the desired set of revisions is to use the {caret}@ suffix.
78
+ For instance, if `master` names a merge commit, `git diff master
79
+ master^@` gives the same combined diff as `git show master`.
80
+
81
'git diff' [<options>] <commit>\...<commit> [--] [<path>...]::
82
83
This form is to view the changes on the branch containing
@@ -196,7 +207,8 @@ linkgit:git-difftool[1],
207
linkgit:git-log[1],
208
linkgit:gitdiffcore[7],
209
linkgit:git-format-patch[1],
199
-linkgit:git-apply[1]
210
+linkgit:git-apply[1],
211
+linkgit:git-show[1]
212
213
GIT
214
---
builtin/diff.c
+7
-1
@@ -24,7 +24,13 @@
24
#define DIFF_NO_INDEX_IMPLICIT 2
25
26
static const char builtin_diff_usage[] =
27
-"git diff [<options>] [<commit> [<commit>]] [--] [<path>...]";
27
+"git diff [<options>] [<commit>] [--] [<path>...]\n"
28
+" or: git diff [<options>] --cached [<commit>] [--] [<path>...]\n"
29
+" or: git diff [<options>] <commit> [<commit>...] <commit> [--] [<path>...]\n"
30
+" or: git diff [<options>] <commit>...<commit>] [--] [<path>...]\n"
31
+" or: git diff [<options>] <blob> <blob>]\n"
32
+" or: git diff [<options>] --no-index [--] <path> <path>]\n"
33
+COMMON_DIFF_OPTIONS_HELP;
34
35
static const char *blob_path(struct object_array_entry *entry)
36
{