docs: explain diff.*.binary option
This was added long ago as part of the userdiff refactoring for textconv, as internally it made the code simpler and cleaner. However, there was never a concrete use case for actually using the config variable. Now that Matthieu Moy has provided such a use case, it's easy to explain it using his example. Signed-off-by: Jeff King <peff@peff.net> Acked-by: Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jeff King committed
Jan 9, 2011 at 15:10 UTC
ab4356111afb28568bf1ad2e909b6ecf9f83a5e6
1 file changed
+33
Documentation/gitattributes.txt
+33
@@ -415,6 +415,39 @@ should generate it separately and send it as a comment _in
415
addition to_ the usual binary diff that you might send.
416
417
418
+Marking files as binary
419
+^^^^^^^^^^^^^^^^^^^^^^^
420
+
421
+Git usually guesses correctly whether a blob contains text or binary
422
+data by examining the beginning of the contents. However, sometimes you
423
+may want to override its decision, either because a blob contains binary
424
+data later in the file, or because the content, while technically
425
+composed of text characters, is opaque to a human reader. For example,
426
+many postscript files contain only ascii characters, but produce noisy
427
+and meaningless diffs.
428
+
429
+The simplest way to mark a file as binary is to unset the diff
430
+attribute in the `.gitattributes` file:
431
+
432
+------------------------
433
+*.ps -diff
434
+------------------------
435
+
436
+This will cause git to generate `Binary files differ` (or a binary
437
+patch, if binary patches are enabled) instead of a regular diff.
438
+
439
+However, one may also want to specify other diff driver attributes. For
440
+example, you might want to use `textconv` to convert postscript files to
441
+an ascii representation for human viewing, but otherwise treat them as
442
+binary files. You cannot specify both `-diff` and `diff=ps` attributes.
443
+The solution is to use the `diff.*.binary` config option:
444
+
445
+------------------------
446
+[diff "ps"]
447
+ textconv = ps2ascii
448
+ binary = true
449
+------------------------
450
+
451
Performing a three-way merge
452
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
453