summaryrefslogtreecommitdiff
path: root/Documentation/diff-format.txt
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2007-12-11 23:46:30 -0800
committerJunio C Hamano <gitster@pobox.com>2007-12-12 10:59:22 -0800
commitf604652e05073aaef6d83e83b5d6499b55bb6dfd (patch)
treee435dad9c570157709c3966518058c21be4958c6 /Documentation/diff-format.txt
parent71a9883db2b60e0d21b730cb9695de69111ab584 (diff)
downloadgit-f604652e05073aaef6d83e83b5d6499b55bb6dfd.tar.gz
git-diff --numstat -z: make it machine readable
The "-z" format is all about machine parsability, but showing renamed paths as "common/{a => b}/suffix" makes it impossible. The scripts would never have successfully parsed "--numstat -z -M" in the old format. This fixes the output format in a (hopefully minimally) backward incompatible way. * The output without -z is not changed. This has given a good way for humans to view added and deleted lines separately, and showing the path in combined, shorter way would preserve readability. * The output with -z is unchanged for paths that do not involve renames. Existing scripts that do not pass -M/-C are not affected at all. * The output with -z for a renamed path is shown in a format that can easily be distinguished from an unrenamed path. This is based on Jakub Narebski's patch. Bugs and documentation typos are mine. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Diffstat (limited to 'Documentation/diff-format.txt')
-rw-r--r--Documentation/diff-format.txt61
1 files changed, 61 insertions, 0 deletions
diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
index 2c3a4c433b..400cbb3b1c 100644
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.txt
@@ -84,3 +84,64 @@ all parents.
include::diff-generate-patch.txt[]
+
+
+other diff formats
+------------------
+
+The `--summary` option describes newly added, deleted, renamed and
+copied files. The `--stat` option adds diffstat(1) graph to the
+output. These options can be combined with other options, such as
+`-p`, and are meant for human consumption.
+
+When showing a change that involves a rename or a copy, `--stat` output
+formats the pathnames compactly by combining common prefix and suffix of
+the pathnames. For example, a change that moves `arch/i386/Makefile` to
+`arch/x86/Makefile` while modifying 4 lines will be shown like this:
+
+------------------------------------
+arch/{i386 => x86}/Makefile | 4 +--
+------------------------------------
+
+The `--numstat` option gives the diffstat(1) information but is designed
+for easier machine consumption. An entry in `--numstat` output looks
+like this:
+
+----------------------------------------
+1 2 README
+3 1 arch/{i386 => x86}/Makefile
+----------------------------------------
+
+That is, from left to right:
+
+. the number of added lines;
+. a tab;
+. the number of deleted lines;
+. a tab;
+. pathname (possibly with rename/copy information);
+. a newline.
+
+When `-z` output option is in effect, the output is formatted this way:
+
+----------------------------------------
+1 2 README NUL
+3 1 NUL arch/i386/Makefile NUL arch/x86/Makefile NUL
+----------------------------------------
+
+That is:
+
+. the number of added lines;
+. a tab;
+. the number of deleted lines;
+. a tab;
+. a NUL (only exists if renamed/copied);
+. pathname in preimage;
+. a NUL (only exists if renamed/copied);
+. pathname in postimage (only exists if renamed/copied);
+. a NUL.
+
+The extra `NUL` before the preimage path in renamed case is to allow
+scripts that read the output to tell if the current record being read is
+a single-path record or a rename/copy record without reading ahead.
+After reading added and deleted lines, reading up to `NUL` would yield
+the pathname, but if that is `NUL`, the record will show two paths.