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>
Jeff King committed
May 24, 2011 at 15:45 UTC
55601c6a4598f3b37e8269beff3275d6592053dd
1 file changed
+31
Documentation/gitattributes.txt
+31
@@ -593,6 +593,37 @@ and now produces better output), you can remove the cache
593
manually with `git update-ref -d refs/notes/textconv/jpg` (where
594
"jpg" is the name of the diff driver, as in the example above).
595
596
+Choosing textconv versus external diff
597
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
598
+
599
+If you want to show differences between binary or specially-formatted
600
+blobs in your repository, you can choose to use either an external diff
601
+command, or to use textconv to convert them to a diff-able text format.
602
+Which method you choose depends on your exact situation.
603
+
604
+The advantage of using an external diff command is flexibility. You are
605
+not bound to find line-oriented changes, nor is it necessary for the
606
+output to resemble unified diff. You are free to locate and report
607
+changes in the most appropriate way for your data format.
608
+
609
+A textconv, by comparison, is much more limiting. You provide a
610
+transformation of the data into a line-oriented text format, and git
611
+uses its regular diff tools to generate the output. There are several
612
+advantages to choosing this method:
613
+
614
+1. Ease of use. It is often much simpler to write a binary to text
615
+ transformation than it is to perform your own diff. In many cases,
616
+ existing programs can be used as textconv filters (e.g., exif,
617
+ odt2txt).
618
+
619
+2. Git diff features. By performing only the transformation step
620
+ yourself, you can still utilize many of git's diff features,
621
+ including colorization, word-diff, and combined diffs for merges.
622
+
623
+3. Caching. Textconv caching can speed up repeated diffs, such as those
624
+ you might trigger by running `git log -p`.
625
+
626
+
627
Marking files as binary
628
^^^^^^^^^^^^^^^^^^^^^^^
629