initial commit

1 files changed, 66 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..cc2df3a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,66 @@
+# Overview
+
+A small git-integrated script to sign a repository archive tarball for use with cgit.
+
+## Usage
+
+    git-snapsign [--dry-run] [--force] [-s <key-id>] [-F <fmt>] [-p <pfx>] -t <tag>
+
+`git-snapsign` will create a detached signature for archive output from
+`git-archive(1)` for `<tag>` and add it to the tag's notes in the
+`refs/notes/signatures/<fmt>` namespace. cgit can then display these alongside
+the snapshots it offers on the repository's summary page.
+
+## Options
+
+```
+-d, --dry-run:
+        Do everything except add the signature blobs and associated note refs.
+
+-f, --force: Overwrite any existing signature
+
+-F, --format <fmt>:
+        Format to pass to git-archive(1). Currently, we only accept either
+        "tar.gz", "tar.lz", "tar.xz", "tgz", "tar" or "zip" as we sign only the
+        underlying archive, not the compressed version. For default "tar.lz".
+
+-p, --prefix <pfx>:
+        Prefix to use when determining the prefix to pass to git-archive(1).
+        By default, we use the repository basename to create
+        <repo-name>-<tag>.<fmt>. Note that we also drop any intital "v"
+        character from <tag>.
+
+-P, --push: Upload signature to remote git
+
+-s, --signature <key-id>:
+        Create the signature using <key-id>. If not provided, the output of
+        git config user.signingkey is used.
+
+-t, --tag <tag>: Git tag name
+
+-v, --version:
+        Show version of git-snapsign
+
+-h, --help:
+        This message
+```
+
+### Examples
+
+Create a signature for the archive tarball at tag v1.0.0.
+
+    git-snapsign -t v1.0.0
+
+Same as above but use the zip format.
+
+    git-snapsign -F zip -t v1.0.0
+
+Create a signature with the key corresponding to heckyel@hyperbola.info
+
+    git-snapsign -s 4DF21B6A7C1021B25C360914F6EE7BC59A315766 -t v1.0.0
+
+Use "linux-libre-lts" to create the archive prefix. Useful for when the repository
+basename is not the canonical name of the project. For example, the
+linux-libre-lts project may wish to set the prefix this way.
+
+    git-snapsign -p linux-libre-lts -t v5.4.96