MyFirstContribution: teach to use "format-patch --base=auto"
Let's encourage first-time contributors to tell us what commit they based their work on with the format-patch invocation. As the example already forks from origin/master and branch.autosetupmerge by default records the upstream when the psuh branch was created, we can use --base=auto for this. Also, mention that the range of commits can simply be given with `@{u}` if they are on the `psuh` branch already. As we are getting one more option on the command line, and spending one paragraph each to explain them, let's reformat that part of the description as a bulleted list. Helped-by: Bagas Sanjaya <bagasdotme@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Oct 18, 2021 at 13:08 UTC
0b45a41dc1bf973243935c1115b2a898fa89e6ef
1 file changed
+28
-13
Documentation/MyFirstContribution.txt
+28
-13
@@ -905,19 +905,34 @@ Sending emails with Git is a two-part process; before you can prepare the emails
905
themselves, you'll need to prepare the patches. Luckily, this is pretty simple:
906
907
----
908
-$ git format-patch --cover-letter -o psuh/ master..psuh
909
-----
910
-
911
-The `--cover-letter` parameter tells `format-patch` to create a cover letter
912
-template for you. You will need to fill in the template before you're ready
913
-to send - but for now, the template will be next to your other patches.
914
-
915
-The `-o psuh/` parameter tells `format-patch` to place the patch files into a
916
-directory. This is useful because `git send-email` can take a directory and
917
-send out all the patches from there.
918
-
919
-`master..psuh` tells `format-patch` to generate patches for the difference
920
-between `master` and `psuh`. It will make one patch file per commit. After you
908
+$ git format-patch --cover-letter -o psuh/ --base=auto psuh@{u}..psuh
909
+----
910
+
911
+ . The `--cover-letter` option tells `format-patch` to create a
912
+ cover letter template for you. You will need to fill in the
913
+ template before you're ready to send - but for now, the template
914
+ will be next to your other patches.
915
+
916
+ . The `-o psuh/` option tells `format-patch` to place the patch
917
+ files into a directory. This is useful because `git send-email`
918
+ can take a directory and send out all the patches from there.
919
+
920
+ . The `--base=auto` option tells the command to record the "base
921
+ commit", on which the recipient is expected to apply the patch
922
+ series. The `auto` value will cause `format-patch` to compute
923
+ the base commit automatically, which is the merge base of tip
924
+ commit of the remote-tracking branch and the specified revision
925
+ range.
926
+
927
+ . The `psuh@{u}..psuh` option tells `format-patch` to generate
928
+ patches for the commits you created on the `psuh` branch since it
929
+ forked from its upstream (which is `origin/master` if you
930
+ followed the example in the "Set up your workspace" section). If
931
+ you are already on the `psuh` branch, you can just say `@{u}`,
932
+ which means "commits on the current branch since it forked from
933
+ its upstream", which is the same thing.
934
+
935
+The command will make one patch file per commit. After you
936
run, you can go have a look at each of the patches with your favorite text
937
editor and make sure everything looks alright; however, it's not recommended to
938
make code fixups via the patch file. It's a better idea to make the change the