\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