@matheusbsbs / matheus-bagliano / commits / 272bd3cfd0
Fork 0

Include diff options in the git-log manpage

[jc: with quite a few fixups] Signed-off-by: Miklos Vajna <vmiklos@frugalware.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Miklos Vajna committed Nov 1, 2007 at 15:57 UTC 272bd3cfd059cf867b979d5c11b0ccce9bcccbb3
4 files changed +168 -161
Documentation/diff-format.txt
+1 -158
@@ -83,161 +83,4 @@ Note that 'combined diff' lists only files which were modified from
83 all parents.
84
85
86 -Generating patches with -p
87 ---------------------------
88 -
89 -When "git-diff-index", "git-diff-tree", or "git-diff-files" are run
90 -with a '-p' option, or "git diff" without the '--raw' option, they
91 -do not produce the output described above; instead they produce a
92 -patch file. You can customize the creation of such patches via the
93 -GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables.
94 -
95 -What the -p option produces is slightly different from the traditional
96 -diff format.
97 -
98 -1. It is preceded with a "git diff" header, that looks like
99 - this:
100 -
101 - diff --git a/file1 b/file2
102 -+
103 -The `a/` and `b/` filenames are the same unless rename/copy is
104 -involved. Especially, even for a creation or a deletion,
105 -`/dev/null` is _not_ used in place of `a/` or `b/` filenames.
106 -+
107 -When rename/copy is involved, `file1` and `file2` show the
108 -name of the source file of the rename/copy and the name of
109 -the file that rename/copy produces, respectively.
110 -
111 -2. It is followed by one or more extended header lines:
112 -
113 - old mode <mode>
114 - new mode <mode>
115 - deleted file mode <mode>
116 - new file mode <mode>
117 - copy from <path>
118 - copy to <path>
119 - rename from <path>
120 - rename to <path>
121 - similarity index <number>
122 - dissimilarity index <number>
123 - index <hash>..<hash> <mode>
124 -
125 -3. TAB, LF, double quote and backslash characters in pathnames
126 - are represented as `\t`, `\n`, `\"` and `\\`, respectively.
127 - If there is need for such substitution then the whole
128 - pathname is put in double quotes.
129 -
130 -The similarity index is the percentage of unchanged lines, and
131 -the dissimilarity index is the percentage of changed lines. It
132 -is a rounded down integer, followed by a percent sign. The
133 -similarity index value of 100% is thus reserved for two equal
134 -files, while 100% dissimilarity means that no line from the old
135 -file made it into the new one.
136 -
137 -
138 -combined diff format
139 ---------------------
140 -
141 -"git-diff-tree", "git-diff-files" and "git-diff" can take '-c' or
142 -'--cc' option to produce 'combined diff', which looks like this:
143 -
144 -------------
145 -diff --combined describe.c
146 -index fabadb8,cc95eb0..4866510
147 ---- a/describe.c
148 -+++ b/describe.c
149 -@@@ -98,20 -98,12 +98,20 @@@
150 - return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
151 - }
152 -
153 -- static void describe(char *arg)
154 - -static void describe(struct commit *cmit, int last_one)
155 -++static void describe(char *arg, int last_one)
156 - {
157 - + unsigned char sha1[20];
158 - + struct commit *cmit;
159 - struct commit_list *list;
160 - static int initialized = 0;
161 - struct commit_name *n;
162 -
163 - + if (get_sha1(arg, sha1) < 0)
164 - + usage(describe_usage);
165 - + cmit = lookup_commit_reference(sha1);
166 - + if (!cmit)
167 - + usage(describe_usage);
168 - +
169 - if (!initialized) {
170 - initialized = 1;
171 - for_each_ref(get_name);
172 -------------
173 -
174 -1. It is preceded with a "git diff" header, that looks like
175 - this (when '-c' option is used):
176 -
177 - diff --combined file
178 -+
179 -or like this (when '--cc' option is used):
180 -
181 - diff --c file
182 -
183 -2. It is followed by one or more extended header lines
184 - (this example shows a merge with two parents):
185 -
186 - index <hash>,<hash>..<hash>
187 - mode <mode>,<mode>..<mode>
188 - new file mode <mode>
189 - deleted file mode <mode>,<mode>
190 -+
191 -The `mode <mode>,<mode>..<mode>` line appears only if at least one of
192 -the <mode> is different from the rest. Extended headers with
193 -information about detected contents movement (renames and
194 -copying detection) are designed to work with diff of two
195 -<tree-ish> and are not used by combined diff format.
196 -
197 -3. It is followed by two-line from-file/to-file header
198 -
199 - --- a/file
200 - +++ b/file
201 -+
202 -Similar to two-line header for traditional 'unified' diff
203 -format, `/dev/null` is used to signal created or deleted
204 -files.
205 -
206 -4. Chunk header format is modified to prevent people from
207 - accidentally feeding it to `patch -p1`. Combined diff format
208 - was created for review of merge commit changes, and was not
209 - meant for apply. The change is similar to the change in the
210 - extended 'index' header:
211 -
212 - @@@ <from-file-range> <from-file-range> <to-file-range> @@@
213 -+
214 -There are (number of parents + 1) `@` characters in the chunk
215 -header for combined diff format.
216 -
217 -Unlike the traditional 'unified' diff format, which shows two
218 -files A and B with a single column that has `-` (minus --
219 -appears in A but removed in B), `+` (plus -- missing in A but
220 -added to B), or `" "` (space -- unchanged) prefix, this format
221 -compares two or more files file1, file2,... with one file X, and
222 -shows how X differs from each of fileN. One column for each of
223 -fileN is prepended to the output line to note how X's line is
224 -different from it.
225 -
226 -A `-` character in the column N means that the line appears in
227 -fileN but it does not appear in the result. A `+` character
228 -in the column N means that the line appears in the last file,
229 -and fileN does not have that line (in other words, the line was
230 -added, from the point of view of that parent).
231 -
232 -In the above example output, the function signature was changed
233 -from both files (hence two `-` removals from both file1 and
234 -file2, plus `++` to mean one line that was added does not appear
235 -in either file1 nor file2). Also two other lines are the same
236 -from file1 but do not appear in file2 (hence prefixed with ` +`).
237 -
238 -When shown by `git diff-tree -c`, it compares the parents of a
239 -merge commit with the merge result (i.e. file1..fileN are the
240 -parents). When shown by `git diff-files -c`, it compares the
241 -two unresolved merge parents with the working tree file
242 -(i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka
243 -"their version").
86 +include::diff-generate-patch.txt[]
Documentation/diff-generate-patch.txt new
+161
@@ -0,0 +1,161 @@
1 +Generating patches with -p
2 +--------------------------
3 +
4 +When "git-diff-index", "git-diff-tree", or "git-diff-files" are run
5 +with a '-p' option, "git diff" without the '--raw' option, or
6 +"git log" with the "-p" option, they
7 +do not produce the output described above; instead they produce a
8 +patch file. You can customize the creation of such patches via the
9 +GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables.
10 +
11 +What the -p option produces is slightly different from the traditional
12 +diff format.
13 +
14 +1. It is preceded with a "git diff" header, that looks like
15 + this:
16 +
17 + diff --git a/file1 b/file2
18 ++
19 +The `a/` and `b/` filenames are the same unless rename/copy is
20 +involved. Especially, even for a creation or a deletion,
21 +`/dev/null` is _not_ used in place of `a/` or `b/` filenames.
22 ++
23 +When rename/copy is involved, `file1` and `file2` show the
24 +name of the source file of the rename/copy and the name of
25 +the file that rename/copy produces, respectively.
26 +
27 +2. It is followed by one or more extended header lines:
28 +
29 + old mode <mode>
30 + new mode <mode>
31 + deleted file mode <mode>
32 + new file mode <mode>
33 + copy from <path>
34 + copy to <path>
35 + rename from <path>
36 + rename to <path>
37 + similarity index <number>
38 + dissimilarity index <number>
39 + index <hash>..<hash> <mode>
40 +
41 +3. TAB, LF, double quote and backslash characters in pathnames
42 + are represented as `\t`, `\n`, `\"` and `\\`, respectively.
43 + If there is need for such substitution then the whole
44 + pathname is put in double quotes.
45 +
46 +The similarity index is the percentage of unchanged lines, and
47 +the dissimilarity index is the percentage of changed lines. It
48 +is a rounded down integer, followed by a percent sign. The
49 +similarity index value of 100% is thus reserved for two equal
50 +files, while 100% dissimilarity means that no line from the old
51 +file made it into the new one.
52 +
53 +
54 +combined diff format
55 +--------------------
56 +
57 +"git-diff-tree", "git-diff-files" and "git-diff" can take '-c' or
58 +'--cc' option to produce 'combined diff'. For showing a merge commit
59 +with "git log -p", this is the default format.
60 +A 'combined diff' format looks like this:
61 +
62 +------------
63 +diff --combined describe.c
64 +index fabadb8,cc95eb0..4866510
65 +--- a/describe.c
66 ++++ b/describe.c
67 +@@@ -98,20 -98,12 +98,20 @@@
68 + return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
69 + }
70 +
71 +- static void describe(char *arg)
72 + -static void describe(struct commit *cmit, int last_one)
73 +++static void describe(char *arg, int last_one)
74 + {
75 + + unsigned char sha1[20];
76 + + struct commit *cmit;
77 + struct commit_list *list;
78 + static int initialized = 0;
79 + struct commit_name *n;
80 +
81 + + if (get_sha1(arg, sha1) < 0)
82 + + usage(describe_usage);
83 + + cmit = lookup_commit_reference(sha1);
84 + + if (!cmit)
85 + + usage(describe_usage);
86 + +
87 + if (!initialized) {
88 + initialized = 1;
89 + for_each_ref(get_name);
90 +------------
91 +
92 +1. It is preceded with a "git diff" header, that looks like
93 + this (when '-c' option is used):
94 +
95 + diff --combined file
96 ++
97 +or like this (when '--cc' option is used):
98 +
99 + diff --c file
100 +
101 +2. It is followed by one or more extended header lines
102 + (this example shows a merge with two parents):
103 +
104 + index <hash>,<hash>..<hash>
105 + mode <mode>,<mode>..<mode>
106 + new file mode <mode>
107 + deleted file mode <mode>,<mode>
108 ++
109 +The `mode <mode>,<mode>..<mode>` line appears only if at least one of
110 +the <mode> is different from the rest. Extended headers with
111 +information about detected contents movement (renames and
112 +copying detection) are designed to work with diff of two
113 +<tree-ish> and are not used by combined diff format.
114 +
115 +3. It is followed by two-line from-file/to-file header
116 +
117 + --- a/file
118 + +++ b/file
119 ++
120 +Similar to two-line header for traditional 'unified' diff
121 +format, `/dev/null` is used to signal created or deleted
122 +files.
123 +
124 +4. Chunk header format is modified to prevent people from
125 + accidentally feeding it to `patch -p1`. Combined diff format
126 + was created for review of merge commit changes, and was not
127 + meant for apply. The change is similar to the change in the
128 + extended 'index' header:
129 +
130 + @@@ <from-file-range> <from-file-range> <to-file-range> @@@
131 ++
132 +There are (number of parents + 1) `@` characters in the chunk
133 +header for combined diff format.
134 +
135 +Unlike the traditional 'unified' diff format, which shows two
136 +files A and B with a single column that has `-` (minus --
137 +appears in A but removed in B), `+` (plus -- missing in A but
138 +added to B), or `" "` (space -- unchanged) prefix, this format
139 +compares two or more files file1, file2,... with one file X, and
140 +shows how X differs from each of fileN. One column for each of
141 +fileN is prepended to the output line to note how X's line is
142 +different from it.
143 +
144 +A `-` character in the column N means that the line appears in
145 +fileN but it does not appear in the result. A `+` character
146 +in the column N means that the line appears in the last file,
147 +and fileN does not have that line (in other words, the line was
148 +added, from the point of view of that parent).
149 +
150 +In the above example output, the function signature was changed
151 +from both files (hence two `-` removals from both file1 and
152 +file2, plus `++` to mean one line that was added does not appear
153 +in either file1 nor file2). Also two other lines are the same
154 +from file1 but do not appear in file2 (hence prefixed with ` +`).
155 +
156 +When shown by `git diff-tree -c`, it compares the parents of a
157 +merge commit with the merge result (i.e. file1..fileN are the
158 +parents). When shown by `git diff-files -c`, it compares the
159 +two unresolved merge parents with the working tree file
160 +(i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka
161 +"their version").
Documentation/diff-options.txt
+2
@@ -6,7 +6,9 @@
6
7 ifndef::git-format-patch[]
8 ifndef::git-diff[]
9 +ifndef::git-log[]
10 :git-diff-core: 1
11 +endif::git-log[]
12 endif::git-diff[]
13 endif::git-format-patch[]
14
Documentation/git-log.txt
+4 -3
@@ -27,6 +27,9 @@ OPTIONS
27
28 include::pretty-options.txt[]
29
30 +:git-log: 1
31 +include::diff-options.txt[]
32 +
33 -<n>::
34 Limits the number of commits to show.
35
@@ -43,9 +46,6 @@ include::pretty-options.txt[]
46 commit. This option gives a better overview of the
47 evolution of a particular branch.
48
46 --p::
47 - Show the change the commit introduces in a patch form.
48 -
49 -g, \--walk-reflogs::
50 Show commits as they were recorded in the reflog. The log contains
51 a record about how the tip of a reference was changed.
@@ -78,6 +78,7 @@ include::pretty-options.txt[]
78
79 include::pretty-formats.txt[]
80
81 +include::diff-generate-patch.txt[]
82
83 Examples
84 --------