Document refs/notes/signatures/..., which is two years old and dead-useful but undocumented

1 files changed, 26 insertions, 0 deletions

diff --git a/git.sr.ht/index.md b/git.sr.ht/index.md
index 60642d8..0427e31 100644
--- a/git.sr.ht/index.md
+++ b/git.sr.ht/index.md
@@ -259,6 +259,32 @@ branch, along with the new tag (this can be made the default behavior by running
 "refs" page of your repository. To attach files to it, click the tag name (e.g.
 "2.3.4") and use the upload form on this page.
 
+# Signing tags' tarballs
+
+In addition to serving tarballs for tags,
+git.sr.ht may also serve PGP signatures for those tarballs with `.asc` appended.
+
+This is done by storing the signatures as notes in the
+`refs/notes/signatures/tar{,.gz}` namespaces.
+
+As an example, the following shell program will sign the given tags
+in the given format:
+
+```sh
+[ $# -lt 1 ] && { echo "usage: $0 tar|tar.gz tag..." >&2; exit 1; }
+fmt=$1; shift
+repo=$(git remote get-url origin)
+for tag; do
+  git -c tar.tar.gz.command='gzip -n' archive --format "$fmt" --prefix "${repo##*/}-$tag/" "$tag" |
+    gpg --detach-sign -a |
+    git notes --ref refs/notes/signatures/"$fmt" add -F- "$tag"
+done
+git push origin refs/notes/signatures/"$fmt"
+```
+
+Be 'ware of compressor variance: you must compress with `gzip -n`!
+If signatures for both `tar` and `tar.gz` are set, `tar` wins.
+
 # Push Options
 
 git.sr.ht supports some git push options, which can be specified with `-o