document the diff driver textconv feature
This patch also changes the term "custom diff driver" to "external diff driver"; now that there are more facets of a "custom driver" than just external diffing, it makes sense to refer to the configuration of "diff.foo.*" as the "foo diff driver", with "diff.foo.command" as the "external driver for foo". Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jeff King committed
Oct 26, 2008 at 00:41 UTC
678852d918e874c99590ba6e857efeef974a3fb9
1 file changed
+53
-13
Documentation/gitattributes.txt
+53
-13
@@ -213,10 +213,12 @@ with `crlf`, and then `ident` and fed to `filter`.
213
Generating diff text
214
~~~~~~~~~~~~~~~~~~~~
215
216
-The attribute `diff` affects if 'git-diff' generates textual
217
-patch for the path or just says `Binary files differ`. It also
218
-can affect what line is shown on the hunk header `@@ -k,l +n,m @@`
219
-line.
216
+The attribute `diff` affects how 'git' generates diffs for particular
217
+files. It can tell git whether to generate a textual patch for the path
218
+or to treat the path as a binary file. It can also affect what line is
219
+shown on the hunk header `@@ -k,l +n,m @@` line, tell git to use an
220
+external command to generate the diff, or ask git to convert binary
221
+files to a text format before generating the diff.
222
223
Set::
224
@@ -227,7 +229,8 @@ Set::
229
Unset::
230
231
A path to which the `diff` attribute is unset will
230
- generate `Binary files differ`.
232
+ generate `Binary files differ` (or a binary patch, if
233
+ binary patches are enabled).
234
235
Unspecified::
236
@@ -238,21 +241,21 @@ Unspecified::
241
242
String::
243
241
- Diff is shown using the specified custom diff driver.
242
- The driver program is given its input using the same
243
- calling convention as used for GIT_EXTERNAL_DIFF
244
- program. This name is also used for custom hunk header
245
- selection.
244
+ Diff is shown using the specified diff driver. Each driver may
245
+ specify one or more options, as described in the following
246
+ section. The options for the diff driver "foo" are defined
247
+ by the configuration variables in the "diff.foo" section of the
248
+ git config file.
249
250
248
-Defining a custom diff driver
249
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
251
+Defining an external diff driver
252
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
253
254
The definition of a diff driver is done in `gitconfig`, not
255
`gitattributes` file, so strictly speaking this manual page is a
256
wrong place to talk about it. However...
257
255
-To define a custom diff driver `jcdiff`, add a section to your
258
+To define an external diff driver `jcdiff`, add a section to your
259
`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
260
261
----------------------------------------------------------------
@@ -328,6 +331,43 @@ patterns are available:
331
- `tex` suitable for source code for LaTeX documents.
332
333
334
+Performing text diffs of binary files
335
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
336
+
337
+Sometimes it is desirable to see the diff of a text-converted
338
+version of some binary files. For example, a word processor
339
+document can be converted to an ASCII text representation, and
340
+the diff of the text shown. Even though this conversion loses
341
+some information, the resulting diff is useful for human
342
+viewing (but cannot be applied directly).
343
+
344
+The `textconv` config option is used to define a program for
345
+performing such a conversion. The program should take a single
346
+argument, the name of a file to convert, and produce the
347
+resulting text on stdout.
348
+
349
+For example, to show the diff of the exif information of a
350
+file instead of the binary information (assuming you have the
351
+exif tool installed):
352
+
353
+------------------------
354
+[diff "jpg"]
355
+ textconv = exif
356
+------------------------
357
+
358
+NOTE: The text conversion is generally a one-way conversion;
359
+in this example, we lose the actual image contents and focus
360
+just on the text data. This means that diffs generated by
361
+textconv are _not_ suitable for applying. For this reason,
362
+only `git diff` and the `git log` family of commands (i.e.,
363
+log, whatchanged, show) will perform text conversion. `git
364
+format-patch` will never generate this output. If you want to
365
+send somebody a text-converted diff of a binary file (e.g.,
366
+because it quickly conveys the changes you have made), you
367
+should generate it separately and send it as a comment _in
368
+addition to_ the usual binary diff that you might send.
369
+
370
+
371
Performing a three-way merge
372
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
373