git: 51d1d857fa - main - Porter's handbook: Mention git-format-patch(1) in using git to make patches

The branch main has been updated by lwhsu:

URL: https://cgit.FreeBSD.org/doc/commit/?id=51d1d857fa76781b1875f920aa0c29c8c2c183b6

commit 51d1d857fa76781b1875f920aa0c29c8c2c183b6
Author:     Li-Wen Hsu <lwhsu@FreeBSD.org>
AuthorDate: 2021-10-29 08:47:47 +0000
Commit:     Li-Wen Hsu <lwhsu@FreeBSD.org>
CommitDate: 2021-10-29 08:47:47 +0000

    Porter's handbook: Mention git-format-patch(1) in using git to make patches
    
    Reviewed by:    carlavilla, ygy, portmgr (bapt)
    Differential Revision:  https://reviews.freebsd.org/D32485
    Sponsored by:   The FreeBSD Foundation
---
 .../books/porters-handbook/upgrading/_index.adoc   | 33 ++++++++++++++++++++--
 1 file changed, 30 insertions(+), 3 deletions(-)

diff --git a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc
index b93d0dac18..968b25a6ed 100644
--- a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc
@@ -113,11 +113,13 @@ Now that all of that is done, read about how to keep up-to-date in crossref:keep
 [[git-diff]]
 == Using Git to Make Patches
 
-When possible, please submit a man:git[1] diff.
+When possible, please submit a man:git[1] patch or diff.
 They are easier to handle than diffs between "new and old" directories.
 It is easier to see what has changed, and to update the diff if something was modified in the Ports Collection since the work on it began,
 or if the committer asks for something to be fixed.
-Also, a patch generated with `git diff` can be easily applied with `git apply` and will save some time to the committer.
+Also, a patch generated with man:git-format-patch[1] or man:git-diff[1] can be easily applied with man:git-am[1] or man:git-apply[1] and will save some time for the committer.
+Finally, the git patch generated by man:git-format-patch[1] includes your author information and commit messages.
+These will be recorded in the log of the repository and this is the recommended way to submit your changes.
 
 [source,shell]
 ....
@@ -159,12 +161,37 @@ Check the changes staged for the patch:
 % git diff --staged
 ....
 
-The last step is to make a unified man:diff[1] of the changes:
+The last step is to make an unified diff or patch of the changes:
 
+To generate an unified diff with man:git-diff[1]:
 [source,shell]
 ....
 % git diff --staged > ../`make -VPKGNAME`.diff
 ....
+This will generate a diff named like `foo-1.2.3.diff`.
+Where `foo` is replaced with the first line of the commit message, i.e., the subject of the commit message.
+
+To generate a patch with man:git-format-patch[1]:
+[source,shell]
+....
+% git checkout -b my_branch
+% git commit
+% git format-patch main
+....
+
+This will generate a patch named like `0001-foo.patch`.
+
+After patch has been created, you can switch to the main branch for starting other developments.
+[source,shell]
+....
+% git checkout main
+....
+
+Once the patch is accepted and merged, you can delete the local development branch if you want:
+[source,shell]
+....
+% git branch -D my_branch
+....
 
 [NOTE]
 ====