Skip to content

Commit

Permalink
Update documentation to remove incorrect GIT_DIFF_OPTS example.
Browse files Browse the repository at this point in the history
Git no longer calls an external diff program to generate patches.
Remove the documentation which suggests that you can pass
arbitrary diff options via the GIT_DIFF_OPTS environment variable.

Signed-off-by: Sean Estabrooks <seanlkml@sympatico.ca>
Signed-off-by: Junio C Hamano <junkio@cox.net>
  • Loading branch information
loops authored and Junio C Hamano committed Nov 27, 2006
1 parent 3c23bea commit fde97d8
Show file tree
Hide file tree
Showing 2 changed files with 34 additions and 55 deletions.
57 changes: 6 additions & 51 deletions Documentation/diff-format.txt
Expand Up @@ -65,62 +65,17 @@ Generating patches with -p

When "git-diff-index", "git-diff-tree", or "git-diff-files" are run
with a '-p' option, they do not produce the output described above;
instead they produce a patch file.
instead they produce a patch file. You can customize the creation
of such patches via the GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS
environment variables.

The patch generation can be customized at two levels.

1. When the environment variable 'GIT_EXTERNAL_DIFF' is not set,
these commands internally invoke "diff" like this:

diff -L a/<path> -L b/<path> -pu <old> <new>
+
For added files, `/dev/null` is used for <old>. For removed
files, `/dev/null` is used for <new>
+
The "diff" formatting options can be customized via the
environment variable 'GIT_DIFF_OPTS'. For example, if you
prefer context diff:

GIT_DIFF_OPTS=-c git-diff-index -p HEAD


2. When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
program named by it is called, instead of the diff invocation
described above.
+
For a path that is added, removed, or modified,
'GIT_EXTERNAL_DIFF' is called with 7 parameters:

path old-file old-hex old-mode new-file new-hex new-mode
+
where:

<old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
contents of <old|new>,
<old|new>-hex:: are the 40-hexdigit SHA1 hashes,
<old|new>-mode:: are the octal representation of the file modes.

+
The file parameters can point at the user's working file
(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
when a new file is added), or a temporary file (e.g. `old-file` in the
index). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the
temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.

For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
parameter, <path>.


git specific extension to diff format
-------------------------------------

What -p option produces is slightly different from the
traditional diff format.
What the -p option produces is slightly different from the traditional
diff format.

1. It is preceded with a "git diff" header, that looks like
this:

diff --git a/file1 b/file2
diff --git a/file1 b/file2
+
The `a/` and `b/` filenames are the same unless rename/copy is
involved. Especially, even for a creation or a deletion,
Expand Down
32 changes: 28 additions & 4 deletions Documentation/git.txt
Expand Up @@ -639,11 +639,35 @@ git Commits
git Diffs
~~~~~~~~~
'GIT_DIFF_OPTS'::
Only valid setting is "--unified=??" or "-u??" to set the
number of context lines shown when a unified diff is created.
This takes precedence over any "-U" or "--unified" option
value passed on the git diff command line.

'GIT_EXTERNAL_DIFF'::
see the "generating patches" section in :
gitlink:git-diff-index[1];
gitlink:git-diff-files[1];
gitlink:git-diff-tree[1]
When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
program named by it is called, instead of the diff invocation
described above. For a path that is added, removed, or modified,
'GIT_EXTERNAL_DIFF' is called with 7 parameters:

path old-file old-hex old-mode new-file new-hex new-mode
+
where:

<old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
contents of <old|new>,
<old|new>-hex:: are the 40-hexdigit SHA1 hashes,
<old|new>-mode:: are the octal representation of the file modes.

+
The file parameters can point at the user's working file
(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
when a new file is added), or a temporary file (e.g. `old-file` in the
index). 'GIT_EXTERNAL_DIFF' should not worry about unlinking the
temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.
+
For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
parameter, <path>.

other
~~~~~
Expand Down

0 comments on commit fde97d8

Please sign in to comment.