Documentation: explain how to check for patch corruption
SubmittingPatches has some excellent advice about how to check a patch for corruption before sending it off. Move it to the format-patch manual so it can be installed with git's documentation for use by people not necessarily interested in the git project's practices. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jonathan Nieder committed
Apr 14, 2011 at 21:24 UTC
57756161eed50f2b52c9e32b01f6388814a09943
2 files changed
+60
-44
Documentation/SubmittingPatches
+14
-44
@@ -344,50 +344,20 @@ MUA specific hints
344
345
Some of patches I receive or pick up from the list share common
346
patterns of breakage. Please make sure your MUA is set up
347
-properly not to corrupt whitespaces. Here are two common ones
348
-I have seen:
349
-
350
-* Empty context lines that do not have _any_ whitespace.
351
-
352
-* Non empty context lines that have one extra whitespace at the
353
- beginning.
354
-
355
-One test you could do yourself if your MUA is set up correctly is:
356
-
357
-* Send the patch to yourself, exactly the way you would, except
358
- To: and Cc: lines, which would not contain the list and
359
- maintainer address.
360
-
361
-* Save that patch to a file in UNIX mailbox format. Call it say
362
- a.patch.
363
-
364
-* Try to apply to the tip of the "master" branch from the
365
- git.git public repository:
366
-
367
- $ git fetch http://kernel.org/pub/scm/git/git.git master:test-apply
368
- $ git checkout test-apply
369
- $ git reset --hard
370
- $ git am a.patch
371
-
372
-If it does not apply correctly, there can be various reasons.
373
-
374
-* Your patch itself does not apply cleanly. That is _bad_ but
375
- does not have much to do with your MUA. Please rebase the
376
- patch appropriately.
377
-
378
-* Your MUA corrupted your patch; "am" would complain that
379
- the patch does not apply. Look at .git/rebase-apply/ subdirectory and
380
- see what 'patch' file contains and check for the common
381
- corruption patterns mentioned above.
382
-
383
-* While you are at it, check what are in 'info' and
384
- 'final-commit' files as well. If what is in 'final-commit' is
385
- not exactly what you would want to see in the commit log
386
- message, it is very likely that your maintainer would end up
387
- hand editing the log message when he applies your patch.
388
- Things like "Hi, this is my first patch.\n", if you really
389
- want to put in the patch e-mail, should come after the
390
- three-dash line that signals the end of the commit message.
347
+properly not to corrupt whitespaces.
348
+
349
+See the DISCUSSION section of git-format-patch(1) for hints on
350
+checking your patch by mailing it to yourself and applying with
351
+git-am(1).
352
+
353
+While you are at it, check the resulting commit log message from
354
+a trial run of applying the patch. If what is in the resulting
355
+commit is not exactly what you would want to see, it is very
356
+likely that your maintainer would end up hand editing the log
357
+message when he applies your patch. Things like "Hi, this is my
358
+first patch.\n", if you really want to put in the patch e-mail,
359
+should come after the three-dash line that signals the end of the
360
+commit message.
361
362
363
Pine
Documentation/git-format-patch.txt
+46
@@ -286,6 +286,52 @@ title is likely to be different from the subject of the discussion the
286
patch is in response to, so it is likely that you would want to keep
287
the Subject: line, like the example above.
288
289
+Checking for patch corruption
290
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
291
+Many mailers if not set up properly will corrupt whitespace. Here are
292
+two common types of corruption:
293
+
294
+* Empty context lines that do not have _any_ whitespace.
295
+
296
+* Non-empty context lines that have one extra whitespace at the
297
+ beginning.
298
+
299
+One way to test if your MUA is set up correctly is:
300
+
301
+* Send the patch to yourself, exactly the way you would, except
302
+ with To: and Cc: lines that do not contain the list and
303
+ maintainer address.
304
+
305
+* Save that patch to a file in UNIX mailbox format. Call it a.patch,
306
+ say.
307
+
308
+* Apply it:
309
+
310
+ $ git fetch <project> master:test-apply
311
+ $ git checkout test-apply
312
+ $ git reset --hard
313
+ $ git am a.patch
314
+
315
+If it does not apply correctly, there can be various reasons.
316
+
317
+* The patch itself does not apply cleanly. That is _bad_ but
318
+ does not have much to do with your MUA. You might want to rebase
319
+ the patch with linkgit:git-rebase[1] before regenerating it in
320
+ this case.
321
+
322
+* The MUA corrupted your patch; "am" would complain that
323
+ the patch does not apply. Look in the .git/rebase-apply/ subdirectory and
324
+ see what 'patch' file contains and check for the common
325
+ corruption patterns mentioned above.
326
+
327
+* While at it, check the 'info' and 'final-commit' files as well.
328
+ If what is in 'final-commit' is not exactly what you would want to
329
+ see in the commit log message, it is very likely that the
330
+ receiver would end up hand editing the log message when applying
331
+ your patch. Things like "Hi, this is my first patch.\n" in the
332
+ patch e-mail should come after the three-dash line that signals
333
+ the end of the commit message.
334
+
335
336
EXAMPLES
337
--------