Re: [PATCH] Improve the "diff --git" format documentation

[Andreas Gruenbacher <agruen@suse.de>]

On Thursday 14 October 2010 03:55:48 Junio C Hamano wrote:
> Andreas Gruenbacher <agruen@suse.de> 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@suse.de>
---
 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