On Thursday 14 October 2010 03:55:48 Junio C Hamano wrote: > Andreas Gruenbacher <agruen@xxxxxxx> writes: > > > The `a/` and `b/` filenames are the same unless rename/copy is > > involved. Especially, even for a creation or a deletion, > > -`/dev/null` is _not_ used in place of `a/` or `b/` filenames. > > +`/dev/null` is _not_ used in place of the `a/` or `b/` filenames > > +for nonexisting files (unlike in the unified diff headers). > > The description in the parentheses is wrong, unless you qualify whose > "unified diff headers" you are talking about. I was referring to the unified diff headers that git emits, not any other utility's output. POSIX does not say anything about nonexisting files, and GNU diff with -rN uses an Epoch timestamp instead of /dev/null to distinguish between missing and empty files: http://www.gnu.org/software/diffutils/manual/html_node/Creating-and-Removing.html > For example: > > http://www.opengroup.org/onlinepubs/9699919799/utilities/diff.html#tag_20_34_10_07 > > does not mention anything about file creation/deletion events. Fine, let's make this clear in the "combined diff" format description too then. > Perhaps you are referring to cvs or svn output, but I think we can safely > drop the parenthesized part without losing clarity. I still believe that the documentation should make it very clear how it handles created and deleted files; it really is not obvious to everyone. Can you live with the attached patch? Thanks, Andreas -- [PATCH] Clarify how /dev/null is used in diffs Say where the unified diff header comes in the "git diff" format, and make it clear that /dev/null is used there. In the description of the "combined diff" format, do not claim that traditional unified diffs use /dev/null to signal created or deleted files. Signed-off-by: Andreas Gruenbacher <agruen@xxxxxxx> --- Documentation/diff-generate-patch.txt | 26 ++++++++++++++++++-------- 1 files changed, 18 insertions(+), 8 deletions(-) diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index 3ac2bea..21c4923 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -53,12 +53,22 @@ The index line includes the SHA-1 checksum before and after the change. The <mode> is included if the file mode does not change; otherwise, separate lines indicate the old and the new mode. -3. TAB, LF, double quote and backslash characters in pathnames +3. It is followed by a 'unified' diff which starts with a two-line + from-file/to-file header: + + --- a/file1 + +++ b/file2 ++ +This header is omitted if the contents of `file1` and `file2` are identical. +To signal created or deleted files, `/dev/null` is used instead of `a/file1` +or `b/file2`. + +4. TAB, LF, double quote and backslash characters in pathnames are represented as `\t`, `\n`, `\"` and `\\`, respectively. If there is need for such substitution then the whole pathname is put in double quotes. -4. All the `file1` files in the output refer to files before the +5. All the `file1` files in the output refer to files before the commit, and all the `file2` files refer to files after the commit. It is incorrect to apply each change to each file sequentially. For example, this patch will swap a and b: @@ -133,14 +143,14 @@ 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. -3. It is followed by two-line from-file/to-file header +3. It is followed by a two-line from-file/to-file header similar to the + traditional 'unified' diff format header: - --- a/file - +++ b/file + --- a/file1 + +++ b/file2 + -Similar to two-line header for traditional 'unified' diff -format, `/dev/null` is used to signal created or deleted -files. +To signal created or deleted files, `/dev/null` is used instead of `a/file1` +or `b/file2`. 4. Chunk header format is modified to prevent people from accidentally feeding it to `patch -p1`. Combined diff format -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html