Re: [PATCHv2] Document from line in patch format

[Linus Torvalds <torvalds@osdl.org>]

On Tue, 4 Oct 2005, Magnus Damm wrote:
> 
> Huh, I thought that the first line in a unified patch started with
> "---", and that the lines above were treated as garbage.

Indeed, that's true of traditional unified diffs. That's why my tools 
started using "---" in the first place. Cutting off at the "---" means 
that it's _guaranteed_ that we never include any valid patch in the 
description by mistake rather than applying it.

And I _used_ to just hand-edit emails so that things like "Please apply" 
and "Thanks", and "diff -urN" didn't show up.

However, note that "git diffs" can actually contain renames, so a git diff 
may have relevant stuff before the "---". For example:

	diff --git a/arch/v850/kernel/asm-consts.c b/arch/v850/kernel/asm-offsets.c
	similarity index 100%
	rename from arch/v850/kernel/asm-consts.c
	rename to arch/v850/kernel/asm-offsets.c
	diff --git a/arch/v850/kernel/entry.S b/arch/v850/kernel/entry.S
	--- a/arch/v850/kernel/entry.S
	+++ b/arch/v850/kernel/entry.S
	@@ -22,7 +22,7 @@
	 #include <asm/irq.h>
	 #include <asm/errno.h>
	 
	-#include <asm/asm-consts.h>
	+#include <asm/asm-offsets.h>
	 
	 
	 /* Make a slightly more convenient alias for C_SYMBOL_NAME.  */

is a real diff as far as git is concerned, and is obviously much more 
readable (and much more compact) than the traditional broken "delete file 
and re-create it under another name" kind of diff.

So "^diff --git " is actually the real marker for where a git diff starts.

> Relying on "diff -" or "Index: " seems wrong. Try diffing two files by 
> "diff -u file1 file2" and look at the output - the first line is 
> "---"... This extra "---" you are proposing seems like a workaround to 
> me.

With traditional unified patches nothing _relies_ of "diff -" or "Index:", 
exactly because "---" is _always_ seen as the beginning of the patch. But 
even then the patch applicator often wants to see the "diff -" or "Index:" 
line, because it can use them to disambiguate file names.

So there are real _technical_ reasons so make sure that we know where the 
diff starts, and "---" is a good marker, because it's a marker that is 
guaranteed to be there, regardless.

But even apart from those technical reasons, I don't want the first "diff 
-urN ..." or "Index:" line to show up as a commit message. So the tools 
will _also_ break the commit messages at those markers, but that's a hack.

So the _real_ rule is that we break at "---". No ifs, buts, or maybes. And 
no, it's not "extra" or "optional" or "unnecessary".

And it also allows people to put extra commentary, like a diffstat, or a 
private message to me about why I should apply the patch.

		Linus
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/