Add a first quick and dirty draft of what Git can do with GnuPG.

Reviewed by:	rene, imp, lwhsu
Differential Revision:	https://reviews.freebsd.org/D29726

1 files changed, 50 insertions, 0 deletions

diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc
index 63a4e70f38..523a290408 100644
--- a/documentation/content/en/articles/committers-guide/_index.adoc
+++ b/documentation/content/en/articles/committers-guide/_index.adoc
@@ -462,6 +462,56 @@ When you are done, report the bad version to the developer (or fix the bug yours
 'git bisect reset' will end the process and return you back to where you started (usually tip of main).
 Again, the git-bisect manual (linked above) is a good resource for when things go wrong or for unusual cases.
 
+[[git-gpg-signing]]
+==== Signing the commits, tags, and pushes, with GnuPG
+
+Git knows how to sign commits, tags, and pushes.
+When you sign a Git commit or a tag, you can prove that the code you submitted came from you and wasn't altered while you were transferring it.
+You also can prove that you submitted the code and not someone else.
+
+A more in-depth documentation on signing commits and tags can be found in the https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work[Git Tools - Signing Your Work] chapter of the Git's book.
+
+The rationale behind signing pushes can be found in the https://github.com/git/git/commit/a85b377d0419a9dfaca8af2320cc33b051cbed04[commit that introduced the feature].
+
+The best way is to simply tell Git you always want to sign commits, tags, and pushes.
+You can do this by setting a few configuration variables:
+
+[source,shell]
+....
+% git config --add user.signingKey=LONG-KEY-ID
+% git config --add commit.gpgSign=true
+% git config --add tag.gpgSign=true
+% git config --add push.gpgSign=if-asked
+....
+
+// push.gpgSign should probably be set to `yes` once we enable it, or be set with --global, so that it is enabled for all repositories.
+
+[NOTE]
+======
+To avoid possible collisions, make sure you give a long key id to Git.
+You can get the long id with: `gpg --list-secret-keys --keyid-format LONG`.
+======
+
+[TIP]
+======
+To use specific subkeys, and not have GnuPG to resolve the subkey to a primary key, attach `!` to the key.
+For example, to encrypt for the subkey `DEADBEEF`, use `DEADBEEF!`.
+======
+
+===== Verifying signatures
+
+Commit signatures can be verified by running either `git verify-commit <commit hash>`, or `git log --show-signature`.
+
+Tag signatures can be verifed with `git verity-tag <tag name>`, or `git tag -v <tag name>`.
+
+////
+Commented out for now until we decide what to do.
+
+Git pushes are a bit different, they live in a special ref in the repository.
+TODO: write how to verify them
+
+////
+
 ==== Ports Considerations
 The ports tree operates the same way.
 The branch names are different and the repositories are in different locations.