From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 19 Jan 2011 16:26:44 +0000 (-0800)
Subject: Merge branch 'jk/diff-driver-binary-doc' into maint
X-Git-Tag: v1.7.4-rc3~5^2~2
X-Git-Url: https://git.tokkee.org/?a=commitdiff_plain;h=ae830c211bfbf192bcefb821130fe4943daf4291;p=git.git

Merge branch 'jk/diff-driver-binary-doc' into maint

* jk/diff-driver-binary-doc:
  docs: explain diff.*.binary option
---

ae830c211bfbf192bcefb821130fe4943daf4291
diff --cc Documentation/gitattributes.txt
index fbf507a7e,f3f880e27..4641d49f7
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@@ -553,27 -414,40 +553,60 @@@ because it quickly conveys the changes 
  should generate it separately and send it as a comment _in
  addition to_ the usual binary diff that you might send.
  
 +Because text conversion can be slow, especially when doing a
 +large number of them with `git log -p`, git provides a mechanism
 +to cache the output and use it in future diffs.  To enable
 +caching, set the "cachetextconv" variable in your diff driver's
 +config. For example:
 +
 +------------------------
 +[diff "jpg"]
 +	textconv = exif
 +	cachetextconv = true
 +------------------------
 +
 +This will cache the result of running "exif" on each blob
 +indefinitely. If you change the textconv config variable for a
 +diff driver, git will automatically invalidate the cache entries
 +and re-run the textconv filter. If you want to invalidate the
 +cache manually (e.g., because your version of "exif" was updated
 +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).
  
+ Marking files as binary
+ ^^^^^^^^^^^^^^^^^^^^^^^
+ 
+ Git usually guesses correctly whether a blob contains text or binary
+ data by examining the beginning of the contents. However, sometimes you
+ may want to override its decision, either because a blob contains binary
+ data later in the file, or because the content, while technically
+ composed of text characters, is opaque to a human reader. For example,
+ many postscript files contain only ascii characters, but produce noisy
+ and meaningless diffs.
+ 
+ The simplest way to mark a file as binary is to unset the diff
+ attribute in the `.gitattributes` file:
+ 
+ ------------------------
+ *.ps -diff
+ ------------------------
+ 
+ This will cause git to generate `Binary files differ` (or a binary
+ patch, if binary patches are enabled) instead of a regular diff.
+ 
+ However, one may also want to specify other diff driver attributes. For
+ example, you might want to use `textconv` to convert postscript files to
+ an ascii representation for human viewing, but otherwise treat them as
+ binary files. You cannot specify both `-diff` and `diff=ps` attributes.
+ The solution is to use the `diff.*.binary` config option:
+ 
+ ------------------------
+ [diff "ps"]
+   textconv = ps2ascii
+   binary = true
+ ------------------------
+ 
  Performing a three-way merge
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~