initial commit

1 files changed, 214 insertions, 0 deletions

diff --git a/docs/git-snapsign.texi b/docs/git-snapsign.texi
new file mode 100644
index 0000000..b16809b
--- /dev/null
+++ b/docs/git-snapsign.texi
@@ -0,0 +1,214 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename git-snapsign.info
+@include version.texi
+@settitle git-snapsign @value{VERSION}
+
+@copying
+This manual is for git-snapsign (version @value{VERSION}, @value{UPDATED}),
+for Sign a repository archive tarball for use with cgit.
+
+Copyright @copyright{} 2021 Jesus E.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.  A copy of the license is included in the section entitled
+``GNU Free Documentation License''.
+@end quotation
+@end copying
+
+@dircategory Freedom
+@direntry
+* git-snapsign:     Sign a repository archive tarball for use with cgit
+@end direntry
+
+@titlepage
+@title git-snapsign
+@subtitle for version @value{VERSION}, @value{UPDATED}
+@author Jesus E.  (@email{heckyel@@hyperbola.info})
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+
+@contents
+
+
+@node Top
+@top git-snapsign
+This manual is for git-snapsign (version @value{VERSION}, @value{UPDATED}).
+
+@menu
+* Description::                         General purpose and information.
+* Options::                             Usage Parameters of git-snapsign.
+* Examples::                            How to use git-snapsign.
+* Installation Requirements::           Requirements to build and install git-snapsign.
+* Installation::                        Installing git-snapsign from source.
+* GNU Free Documentation License::      Copying and sharing this documentation.
+@end menu
+
+@node Description
+@chapter Description
+
+@cindex description
+Create a detached signature for an archive of <tag> and add it to the tag's
+notes in the refs/notes/signatures/<fmt> namespace.
+
+This is useful for cgit's snapshot support.
+
+@node Options
+@chapter Options
+
+@cindex options
+
+@deffn {-d, --dry-run} Do everything except add the signature blobs and associated note refs.
+@end deffn
+
+@deffn {-f, --force} Overwrite any existing signature
+@end deffn
+
+@deffn {-F, --format <fmt>} Format to pass to @code{git-archive}.
+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".
+@end deffn
+
+@deffn {-p, --prefix <pfx>} Prefix to use when determining the prefix to pass to @code{git-archive}.
+By default, we use the repository basename to create @code{<repo-name>-<tag>.<fmt>}.
+Note that we also drop any intital "v" character from <tag>.
+@end deffn
+
+@deffn {-P, --push} Upload signature to remote git
+@end deffn
+
+@deffn {-t, --tag <tag>} Git tag name
+@end deffn
+
+@deffn {-s, --signature <key-id>} Create the signature using @code{<key-id>}.
+If not provided, the output of @code{git config user.signingkey} is used.
+@end deffn
+
+@deffn {-v, --version} Show version of git-snapsign
+@end deffn
+
+@deffn {-h, --help} This message.
+@end deffn
+
+
+@node Examples
+@chapter Examples
+@cindex examples
+
+@itemize @bullet
+@item
+Create a signature for the archive tarball at tag v1.0.0.
+
+@example
+git-snapsign -t v1.0.0
+@end example
+
+@item
+Same as above but use the zip format.
+
+@example
+git-snapsign -F zip -t v1.0.0
+@end example
+
+@item
+Create a signature with the key corresponding to
+@email{heckyel@@hyperbola.info}
+
+@example
+git-snapsign -s 4DF21B6A7C1021B25C360914F6EE7BC59A315766 -t v1.0.0
+@end example
+
+@item
+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.
+
+@example
+git-snapsign -p linux-libre-lts -t v5.4.96
+@end example
+
+@end itemize
+
+@node Installation Requirements
+@chapter Installation Requirements
+@cindex installation requirements
+
+@itemize @bullet
+
+@item
+sh
+
+@item
+git
+
+@item
+lzip
+
+@item
+xz
+
+@item
+texinfo
+
+@end itemize
+
+@node Installation
+@chapter Installation
+@cindex Installation
+
+You can install git-snapsign directly copying @file{git-snapsign}
+file to /usr/bin/git-snapsign
+
+@section Installing git-snapsign
+To install using make for all users, run:
+
+@example
+doas make install
+@end example
+
+or as root:
+
+@example
+make install
+@end example
+
+@section Releasing a new version
+Update the version number in:
+@itemize @bullet
+@item
+@file{Makefile}
+@item
+@file{git-snapsign}
+@item
+@file{doc/version.texi}
+@end itemize
+
+Then run @samp{make info} to build the docs.
+
+@example
+make info
+@end example
+
+Generate tarball
+
+@example
+make tar.gz
+@end example
+
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+
+@include fdl.texi
+
+
+@bye