doc: discuss textconv versus external diff drivers

We already talk about how to use each one and how they work,
but it is a reasonable question to wonder why one might use
one over the other.

Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Jeff King 2011-05-24 15:45:27 -04:00 committed by Junio C Hamano
parent 5df3e2b3ca
commit 55601c6a45

View File

@ -593,6 +593,37 @@ and now produces better output), you can remove the cache
manually with `git update-ref -d refs/notes/textconv/jpg` (where
"jpg" is the name of the diff driver, as in the example above).
Choosing textconv versus external diff
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you want to show differences between binary or specially-formatted
blobs in your repository, you can choose to use either an external diff
command, or to use textconv to convert them to a diff-able text format.
Which method you choose depends on your exact situation.
The advantage of using an external diff command is flexibility. You are
not bound to find line-oriented changes, nor is it necessary for the
output to resemble unified diff. You are free to locate and report
changes in the most appropriate way for your data format.
A textconv, by comparison, is much more limiting. You provide a
transformation of the data into a line-oriented text format, and git
uses its regular diff tools to generate the output. There are several
advantages to choosing this method:
1. Ease of use. It is often much simpler to write a binary to text
transformation than it is to perform your own diff. In many cases,
existing programs can be used as textconv filters (e.g., exif,
odt2txt).
2. Git diff features. By performing only the transformation step
yourself, you can still utilize many of git's diff features,
including colorization, word-diff, and combined diffs for merges.
3. Caching. Textconv caching can speed up repeated diffs, such as those
you might trigger by running `git log -p`.
Marking files as binary
^^^^^^^^^^^^^^^^^^^^^^^