qmanifest: allow GPG-signing top-level Manifest

Signed-off-by: Fabian Groffen <grobian@gentoo.org>

3 files changed, 53 insertions, 2 deletions

diff --git a/man/include/qmanifest-01-generation.include b/man/include/qmanifest-01-generation.include
new file mode 100644
index 00000000..5a24a02e
--- /dev/null
+++ b/man/include/qmanifest-01-generation.include
@@ -0,0 +1,17 @@
+.SH "GENERATING A SIGNED TREE"
+.PP
+By default, \fBqmanifest\fR will not try to sign the top-level Manifest
+when it generating thick Manifests.  A tree as such isn't completely
+valid (as it misses the final signature), but still correct.  To sign
+the top-level Manifest, the \fB-s\fR flag needs to be used to provide
+the GPG keyid to sign with.  The passphrase is requested by \fBgpg\fR(1)
+itself, unless the \fB-p\fR flag is given, in which case \fBqmanifest\fR
+attempts to read the passphrase from \fIstdin\fR and then pass that
+passphrase onto \fBgpg\fR.  This is useful for scenarios in which the
+signing of a tree is scripted.
+.PP
+To generate a tree signed by GPG keyid \fI0x123567ABC\fR using
+passphrase \fImypasswd\fR, one could use:
+.nf\fI
+	$ echo mypasswd | qmanifest -g -s 0x123567ABC -p /path/to/tree
+.fi
diff --git a/man/include/qmanifest.optdesc.yaml b/man/include/qmanifest.optdesc.yaml
new file mode 100644
index 00000000..8bf1ce71
--- /dev/null
+++ b/man/include/qmanifest.optdesc.yaml
@@ -0,0 +1,8 @@
+signas: |
+    Sign generated Manifest using GPG key.  This key must exist in your
+    keyring and be valid for signing.
+passphrase: |
+    Ask for GPG key password (instead of relying on gpg-agent).  While
+    this option is not very useful compared to gpg's ways of gathering a
+    password, it is mainly intended for automated setups where the
+    password is piped in using \fIstdin\fR.
diff --git a/man/qmanifest.1 b/man/qmanifest.1
index e2231225..15027f6a 100644
--- a/man/qmanifest.1
+++ b/man/qmanifest.1
@@ -38,7 +38,17 @@ with the desired maximum amount of threads in use by \fIqmanifest\fR.
 .SH OPTIONS
 .TP
 \fB\-g\fR, \fB\-\-generate\fR
-Generate thick Manifests and sign.
+Generate thick Manifests.
+.TP
+\fB\-s\fR \fI<arg>\fR, \fB\-\-signas\fR \fI<arg>\fR
+Sign generated Manifest using GPG key.  This key must exist in your
+keyring and be valid for signing.
+.TP
+\fB\-p\fR, \fB\-\-passphrase\fR
+Ask for GPG key password (instead of relying on gpg-agent).  While
+this option is not very useful compared to gpg's ways of gathering a
+password, it is mainly intended for automated setups where the
+password is piped in using \fIstdin\fR.
 .TP
 \fB\-d\fR, \fB\-\-dir\fR
 Treat arguments as directories.
@@ -63,7 +73,23 @@ Print this help and exit.
 .TP
 \fB\-V\fR, \fB\-\-version\fR
 Print version and exit.
-
+.SH "GENERATING A SIGNED TREE"
+.PP
+By default, \fBqmanifest\fR will not try to sign the top-level Manifest
+when it generating thick Manifests.  A tree as such isn't completely
+valid (as it misses the final signature), but still correct.  To sign
+the top-level Manifest, the \fB-s\fR flag needs to be used to provide
+the GPG keyid to sign with.  The passphrase is requested by \fBgpg\fR(1)
+itself, unless the \fB-p\fR flag is given, in which case \fBqmanifest\fR
+attempts to read the passphrase from \fIstdin\fR and then pass that
+passphrase onto \fBgpg\fR.  This is useful for scenarios in which the
+signing of a tree is scripted.
+.PP
+To generate a tree signed by GPG keyid \fI0x123567ABC\fR using
+passphrase \fImypasswd\fR, one could use:
+.nf\fI
+	$ echo mypasswd | qmanifest -g -s 0x123567ABC -p /path/to/tree
+.fi
 .SH "REPORTING BUGS"
 Please report bugs via http://bugs.gentoo.org/
 .br