Re: Combined diff format documentation

From: Junio C Hamano <junkio@cox.net>
Date: Oct 25, 2006, 22:40 UTC
Message-ID: <7vejswkoi4.fsf@assigned-by-dhcp.cox.net>
In-Reply-To: <ehoo2k$1g6$1@sea.gmane.org>

Jakub Narebski <jnareb@gmail.com> 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.