From: David Kastrup <dak@gnu.org>
Date: Sat, 14 Apr 2012 08:50:48 +0000 (+0200)
Subject: source-code.itexi: explain use of "git apply --index"
X-Git-Tag: release/2.15.37-1~13
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=d9d6f6296ec64971c613964c49acf91fe16e2b1e;p=lilypond.git

source-code.itexi: explain use of "git apply --index"
---

diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi
index 930f7857af..8477969899 100644
--- a/Documentation/contributor/source-code.itexi
+++ b/Documentation/contributor/source-code.itexi
@@ -1683,10 +1683,10 @@ git am @var{patch}
 
 Patches created without @code{git@tie{}format-patch} can be
 applied in two steps.  The first step is to apply the patch to the
-working tree:
+working tree and the index:
 
 @example
-git apply @var{patch}
+git apply --index @var{patch}
 @end example
 
 @noindent
@@ -1694,9 +1694,16 @@ The second step is to commit the changes and give credit to the
 author of the patch.  This can be done with the following command:
 
 @example
-git commit -a --author="@var{John Smith} <@var{john@@example.com}>"
+git commit --author="@var{John Smith} <@var{john@@example.com}>"
 @end example
 
+Please note that using the @code{--index} option for patching is quite
+important here and @emph{cannot} reliably be replaced by using the
+@code{-a} option when committing: that would only commit files from the
+working tree that are already registered with git, so every file that
+the patch actually @emph{adds}, like a regtest for a fixed bug, would
+get lost.  For the same reason, you should not use the git-independent
+@samp{patch} program for applying patches.
 
 @node Sending and receiving patches via email
 @subsection Sending and receiving patches via email