From owner-dev-commits-doc-all@freebsd.org Tue Apr 27 06:17:13 2021 Return-Path: Delivered-To: dev-commits-doc-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id E41D7621EF1 for ; Tue, 27 Apr 2021 06:17:13 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4FTs49659Hz3KCh; Tue, 27 Apr 2021 06:17:13 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id C3E0E15D97; Tue, 27 Apr 2021 06:17:13 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 13R6HDF5073939; Tue, 27 Apr 2021 06:17:13 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 13R6HDFT073938; Tue, 27 Apr 2021 06:17:13 GMT (envelope-from git) Date: Tue, 27 Apr 2021 06:17:13 GMT Message-Id: <202104270617.13R6HDFT073938@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Mathieu Arnold Subject: git: a6e878928c - main - Add a first quick and dirty draft of what Git can do with GnuPG. MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: mat X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: a6e878928c14923f3fa3aad6ab1b1b4811fe1bc2 Auto-Submitted: auto-generated X-BeenThere: dev-commits-doc-all@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Commit messages for all branches of the doc repository List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 27 Apr 2021 06:17:13 -0000 The branch main has been updated by mat: URL: https://cgit.FreeBSD.org/doc/commit/?id=a6e878928c14923f3fa3aad6ab1b1b4811fe1bc2 commit a6e878928c14923f3fa3aad6ab1b1b4811fe1bc2 Author: Mathieu Arnold AuthorDate: 2021-04-22 11:39:47 +0000 Commit: Mathieu Arnold CommitDate: 2021-04-27 06:16:49 +0000 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 --- .../en/articles/committers-guide/_index.adoc | 50 ++++++++++++++++++++++ 1 file changed, 50 insertions(+) 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 `, or `git log --show-signature`. + +Tag signatures can be verifed with `git verity-tag `, or `git tag -v `. + +//// +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.