Jakub Narebski [off-list ref] writes:
1. "git diff" header which looked like this
2. the "index" extended header line changes from
3. The "rename/copy" headers seems to be never present; see below.
...
Thanks for starting this. Your observation is correct. It was
pretty much designed for quick _content_ inspection and renames
would work correctly to pick which blobs from each tree to
compare but otherwise not reflected in the output (the pathnames
are not shown as far as I know). We could probably add it if
some users need it.
5. Hunk header is also modified: in ordinary diff we have
...
It might be not obvoious that we have (number of parents + 1) '@'
characters in chunk header for combined dif format.
Correct. This was done to prevent people from accidentally
feeding it to "patch -p1". In other words, we wanted to make it
so obvious that it is _not_ a patch.
There may be more information in "git log -- combine-diff.c"
output that ought to be collected into the documentation, and
now might be a good time to do so, given that that part of the
system is fairly stable and has not changed for quite some time
in git timescale.
BTW. it is not mentioned in documentation that git diff uses hunk section
indicator, and what regexp/expression it uses (and is it configurable).
Not described in documentation.
If you mean by "hunk section indicator" the output similar to
GNU diff -p option, I think it is not worth mentioning and we
are not ready to mention it yet (we have not etched the
expression in stone). Nobody jumped up and down to say it needs
to be configurable, so it is left undocumented more or less
deliberately.
6. Documentation/diff-format.txt explains combined and condensed combined
format quite well, although it doesn't tell us if we can have plusses and
minuses together in one line...
But you already know the answer to that question, since you
asked me a few days ago ;-).
Patches to documentation would be easier to comment on and more
productive, I guess.
Below there are following diffs: with first parent, merge (with all parents)
with renames detection, combined, combined with rename detection. Is it all
expected?
Yes. I do not see anything obviously unexpected in your output.
Junio C Hamano wrote:
quoted
BTW. it is not mentioned in documentation that git diff uses hunk section
indicator, and what regexp/expression it uses (and is it configurable).
Not described in documentation.
If you mean by "hunk section indicator" the output similar to
GNU diff -p option, I think it is not worth mentioning and we
are not ready to mention it yet (we have not etched the
expression in stone). Nobody jumped up and down to say it needs
to be configurable, so it is left undocumented more or less
deliberately.
By the way, I have just checked that combined diff format doesn't have
(for unknown reason) "which section" indicator in chunk header.
Compare
$ git diff-tree -p -m fec9ebf16c948bcb4a8b88d0173ee63584bcde76
and
$ git diff-tree -p -c fec9ebf16c948bcb4a8b88d0173ee63584bcde76
(this is the source of example combined diff format in diff-formats.txt
which I've found via
$ git rev-list --parents HEAD -- describe.c | grep " .* "
i.e. finding all merges which included changes to describe.c; there
are only two such commits).
--
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git
Junio C Hamano wrote:
Jakub Narebski [off-list ref] writes:
quoted
6. Documentation/diff-format.txt explains combined and condensed combined
format quite well, although it doesn't tell us if we can have plusses and
minuses together in one line...
But you already know the answer to that question, since you
asked me a few days ago ;-).
Yes, in "[RFC] Syntax highlighting for combined diff" thread
http://permalink.gmane.org/gmane.comp.version-control.git/29566
Well, the _documentation_ doesn't tell. I haven't fully grokked the code
for generating and coloring combined diff output besides the fact that
I think it uses last indicator ('+' or '-') to chose color for the rest
of line. You said that even if the possibility exist, it is extreme
unlikely.
Patches to documentation would be easier to comment on and more
productive, I guess.
I was not sure about output. All conclusions about combined diff output
are from examples; I've planned to send patch to documentation when I'll
be sure that at least _most_ of what I've added is correct.
Will do.
--
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git
Update example combined diff format to the current version
$ git diff-tree -p -c fec9ebf16c948bcb4a8b88d0173ee63584bcde76
and provide complete first chunk in example.
Document combined diff format headers: how "diff header" look like,
which of "extended diff headers" are used with combined diff and how
they look like, differences in two-line from-file/to-file header from
non-combined diff format, chunk header format.
It should be noted that combined diff format was designed for quick
_content_ inspection and renames would work correctly to pick which
blobs from each tree to compare but otherwise not reflected in the
output (the pathnames are not shown).
Signed-off-by: Jakub Narebski <redacted>
---
Junio C Hamano napisał:
Patches to documentation would be easier to comment on and more
productive, I guess.
So here you have. It should perhaps get review on validity by someone
well versed in the combined diff generation code. There are some guesses
here...
It compiles, but the output was not inspected.
Documentation/diff-format.txt | 70 ++++++++++++++++++++++++++++++++++++++---
1 files changed, 65 insertions(+), 5 deletions(-)
diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
index 617d8f5..0d04b03 100644
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.txt
@@ -156,18 +156,78 @@ to produce 'combined diff', which looks
------------
diff --combined describe.c
-@@@ +98,7 @@@
- return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
+index fabadb8,cc95eb0..4866510
+--- a/describe.c
++++ b/describe.c
+@@@ -98,20 -98,12 +98,20 @@@
+ return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
}
-
+
- static void describe(char *arg)
-static void describe(struct commit *cmit, int last_one)
++static void describe(char *arg, int last_one)
{
- + unsigned char sha1[20];
- + struct commit *cmit;
+ + unsigned char sha1[20];
+ + struct commit *cmit;
+ struct commit_list *list;
+ static int initialized = 0;
+ struct commit_name *n;
+
+ + if (get_sha1(arg, sha1) < 0)
+ + usage(describe_usage);
+ + cmit = lookup_commit_reference(sha1);
+ + if (!cmit)
+ + usage(describe_usage);
+ +
+ if (!initialized) {
+ initialized = 1;
+ for_each_ref(get_name);
------------
+1. It is preceded with a "git diff" header, that looks like
+ this (when '-c' option is used):
+
+ diff --combined fileM
+
+ or like this (when '--cc' option is used):
+
+ diff --c fileM
+
+2. It is followed by one or more extended header lines
+ (we assume here that we have merge with two parents):
+
+ index <hash>,<hash>..<hash>
+ mode <mode>,<mode>..<mode>
+ new file mode <mode>
+
+ The "mode <mode>,<mode>..<mode>" appears only if at least
+ one of the <mode> is diferent from the rest. Extended headers
+ with information about detected contents movement (renames
+ and copying detection) are designed to work with diff of two
+ <tree-ish> and are not used by combined diff format. Currently
+ combined diff format cannot show files which were removed
+ by merge, so "deleted file mode <mode>,<mode>" is never used.
+
+3. It is followed by two-line from-file/to-file header
+
+ --- a/fileM
+ +++ b/fileM
+
+ Contrary to two-line header for traditional 'unified' diff
+ format, and similar to filenames in ordinary "diff header",
+ /dev/null is not used for creation combined diff.
+
+4. Chunk header format is modified to prevent people from
+ accidentally feeding it to 'patch -p1'. Combined diff format
+ was created for review of merge commit changes, and was not
+ meant for apply. The change is similar to the change in the
+ extended 'index' header
+
+ @@@ <from-file-range> <from-file-range> <to-file-range> @@@
+
+ It might be not obvious that we have number of parents + 1
+ '@' characters in chunk header for combined diff format.
+
Unlike the traditional 'unified' diff format, which shows two
files A and B with a single column that has `-` (minus --
appears in A but removed in B), `+` (plus -- missing in A but--
1.4.2.1
--
Jakub Narebski