undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

document the diff driver textconv feature

Browse Source 
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>
This commit is contained in:
Jeff King 2008-10-26 00:41:52 -04:00 committed by Junio C Hamano
parent 72cf484140
commit 678852d918
1 changed files with 53 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
Documentation/gitattributes.txt
View File

@ -213,10 +213,12 @@ with `crlf`, and then `ident` and fed to `filter`.
Generating diff text Generating diff text
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~
The attribute `diff` affects if 'git-diff' generates textual The attribute `diff` affects how 'git' generates diffs for particular
patch for the path or just says `Binary files differ`. It also files. It can tell git whether to generate a textual patch for the path
can affect what line is shown on the hunk header `@@ -k,l +n,m @@` or to treat the path as a binary file. It can also affect what line is
line. shown on the hunk header `@@ -k,l +n,m @@` line, tell git to use an
external command to generate the diff, or ask git to convert binary
files to a text format before generating the diff.
Set:: Set::
@ -227,7 +229,8 @@ Set::
Unset:: Unset::
A path to which the `diff` attribute is unset will A path to which the `diff` attribute is unset will
generate `Binary files differ`. generate `Binary files differ` (or a binary patch, if
binary patches are enabled).
Unspecified:: Unspecified::
@ -238,21 +241,21 @@ Unspecified::
String:: String::
Diff is shown using the specified custom diff driver. Diff is shown using the specified diff driver. Each driver may
The driver program is given its input using the same specify one or more options, as described in the following
calling convention as used for GIT_EXTERNAL_DIFF section. The options for the diff driver "foo" are defined
program. This name is also used for custom hunk header by the configuration variables in the "diff.foo" section of the
selection. git config file.
Defining a custom diff driver Defining an external diff driver
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The definition of a diff driver is done in `gitconfig`, not The definition of a diff driver is done in `gitconfig`, not
`gitattributes` file, so strictly speaking this manual page is a `gitattributes` file, so strictly speaking this manual page is a
wrong place to talk about it. However... wrong place to talk about it. However...
To define a custom diff driver `jcdiff`, add a section to your To define an external diff driver `jcdiff`, add a section to your
`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: `$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this:
---------------------------------------------------------------- ----------------------------------------------------------------
@ -328,6 +331,43 @@ patterns are available:
- `tex` suitable for source code for LaTeX documents. - `tex` suitable for source code for LaTeX documents.
Performing text diffs of binary files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sometimes it is desirable to see the diff of a text-converted
version of some binary files. For example, a word processor
document can be converted to an ASCII text representation, and
the diff of the text shown. Even though this conversion loses
some information, the resulting diff is useful for human
viewing (but cannot be applied directly).
The `textconv` config option is used to define a program for
performing such a conversion. The program should take a single
argument, the name of a file to convert, and produce the
resulting text on stdout.
For example, to show the diff of the exif information of a
file instead of the binary information (assuming you have the
exif tool installed):
------------------------
[diff "jpg"]
textconv = exif
------------------------
NOTE: The text conversion is generally a one-way conversion;
in this example, we lose the actual image contents and focus
just on the text data. This means that diffs generated by
textconv are _not_ suitable for applying. For this reason,
only `git diff` and the `git log` family of commands (i.e.,
log, whatchanged, show) will perform text conversion. `git
format-patch` will never generate this output. If you want to
send somebody a text-converted diff of a binary file (e.g.,
because it quickly conveys the changes you have made), you
should generate it separately and send it as a comment _in
addition to_ the usual binary diff that you might send.
Performing a three-way merge Performing a three-way merge
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~