aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGravatar Junio C Hamano <gitster@pobox.com> 2021-11-29 15:41:46 -0800
committerGravatar Junio C Hamano <gitster@pobox.com> 2021-11-29 15:41:46 -0800
commit9b96d91e94dabe32627eb1bf17edf057c6ef8e5c (patch)
treea87fbd080ba565974daa5b7b434b297d476915b0
parent96f6623ada056c24a60e10ad58acc42871dd9f41 (diff)
parent0b45a41dc1bf973243935c1115b2a898fa89e6ef (diff)
downloadgit-9b96d91e94dabe32627eb1bf17edf057c6ef8e5c.tar.gz
git-9b96d91e94dabe32627eb1bf17edf057c6ef8e5c.zip
Merge branch 'jc/tutorial-format-patch-base'
Teach and encourage first-time contributors to this project to state the base commit when they submit their topic. * jc/tutorial-format-patch-base: MyFirstContribution: teach to use "format-patch --base=auto"
-rw-r--r--Documentation/MyFirstContribution.txt41
1 files changed, 28 insertions, 13 deletions
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index b20bc8e914..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