summaryrefslogtreecommitdiff
path: root/Documentation/MyFirstContribution.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/MyFirstContribution.txt')
-rw-r--r--Documentation/MyFirstContribution.txt83
1 files changed, 59 insertions, 24 deletions
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 015cf24631..63a2ef5449 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -905,19 +905,34 @@ Sending emails with Git is a two-part process; before you can prepare the emails
themselves, you'll need to prepare the patches. Luckily, this is pretty simple:
----
-$ git format-patch --cover-letter -o psuh/ master..psuh
-----
-
-The `--cover-letter` parameter tells `format-patch` to create a cover letter
-template for you. You will need to fill in the template before you're ready
-to send - but for now, the template will be next to your other patches.
-
-The `-o psuh/` parameter tells `format-patch` to place the patch files into a
-directory. This is useful because `git send-email` can take a directory and
-send out all the patches from there.
-
-`master..psuh` tells `format-patch` to generate patches for the difference
-between `master` and `psuh`. It will make one patch file per commit. After you
+$ git format-patch --cover-letter -o psuh/ --base=auto psuh@{u}..psuh
+----
+
+ . The `--cover-letter` option tells `format-patch` to create a
+ cover letter template for you. You will need to fill in the
+ template before you're ready to send - but for now, the template
+ will be next to your other patches.
+
+ . The `-o psuh/` option tells `format-patch` to place the patch
+ files into a directory. This is useful because `git send-email`
+ can take a directory and send out all the patches from there.
+
+ . The `--base=auto` option tells the command to record the "base
+ commit", on which the recipient is expected to apply the patch
+ series. The `auto` value will cause `format-patch` to compute
+ the base commit automatically, which is the merge base of tip
+ commit of the remote-tracking branch and the specified revision
+ range.
+
+ . The `psuh@{u}..psuh` option tells `format-patch` to generate
+ patches for the commits you created on the `psuh` branch since it
+ forked from its upstream (which is `origin/master` if you
+ followed the example in the "Set up your workspace" section). If
+ you are already on the `psuh` branch, you can just say `@{u}`,
+ which means "commits on the current branch since it forked from
+ its upstream", which is the same thing.
+
+The command will make one patch file per commit. After you
run, you can go have a look at each of the patches with your favorite text
editor and make sure everything looks alright; however, it's not recommended to
make code fixups via the patch file. It's a better idea to make the change the
@@ -1029,22 +1044,42 @@ kidding - be patient!)
[[v2-git-send-email]]
=== Sending v2
-Skip ahead to <<reviewing,Responding to Reviews>> for information on how to
-handle comments from reviewers. Continue this section when your topic branch is
-shaped the way you want it to look for your patchset v2.
+This section will focus on how to send a v2 of your patchset. To learn what
+should go into v2, skip ahead to <<reviewing,Responding to Reviews>> for
+information on how to handle comments from reviewers.
-When you're ready with the next iteration of your patch, the process is fairly
-similar.
+We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll
+mark the tip of our v1 branch for easy reference:
-First, generate your v2 patches again:
+----
+$ git checkout psuh
+$ git branch psuh-v1
+----
+
+Refine your patch series by using `git rebase -i` to adjust commits based upon
+reviewer comments. Once the patch series is ready for submission, generate your
+patches again, but with some new flags:
----
-$ git format-patch -v2 --cover-letter -o psuh/ master..psuh
+$ git format-patch -v2 --cover-letter -o psuh/ --range-diff master..psuh-v1 master..
----
-This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`,
-to the `psuh/` directory. You may notice that they are sitting alongside the v1
-patches; that's fine, but be careful when you are ready to send them.
+The `--range-diff master..psuh-v1` parameter tells `format-patch` to include a
+range-diff between `psuh-v1` and `psuh` in the cover letter (see
+linkgit:git-range-diff[1]). This helps tell reviewers about the differences
+between your v1 and v2 patches.
+
+The `-v2` parameter tells `format-patch` to output your patches
+as version "2". For instance, you may notice that your v2 patches are
+all named like `v2-000n-my-commit-subject.patch`. `-v2` will also format
+your patches by prefixing them with "[PATCH v2]" instead of "[PATCH]",
+and your range-diff will be prefaced with "Range-diff against v1".
+
+Afer you run this command, `format-patch` will output the patches to the `psuh/`
+directory, alongside the v1 patches. Using a single directory makes it easy to
+refer to the old v1 patches while proofreading the v2 patches, but you will need
+to be careful to send out only the v2 patches. We will use a pattern like
+"psuh/v2-*.patch" (not "psuh/*.patch", which would match v1 and v2 patches).
Edit your cover letter again. Now is a good time to mention what's different
between your last version and now, if it's something significant. You do not
@@ -1082,7 +1117,7 @@ to the command:
----
$ git send-email --to=target@example.com
--in-reply-to="<foo.12345.author@example.com>"
- psuh/v2*
+ psuh/v2-*.patch
----
[[single-patch]]