.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH GITPKG 1 "September 29, 2023"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
gitpkg \- export a Debian source package from nominated git revisions
.SH SYNOPSIS
.B gitpkg
.I branch
.RI [ origbranch ]

.SH DESCRIPTION
If \fBgitpkg\fP is run in a \fBgit\fP(1) repo with a single 'branch' specified,
then it will do a \fBgit\-archive\fP export of that branch to the \fBDEB_DIR\fP
directory.  If the package is Debian native it will simply create a source
package from it.  If the package has a Debian version, then an orig tarball will
be expected to already exist for it.  If an orig tarball does not already exist
then what happens next depends on the value of the
\%\fBgitpkg.create\-fake\-orig\fP configuration option (described below).

If \fBgitpkg\fP is invoked with two branches specified, then the first branch
will be exported as the unpacked complete source, while the second branch will
be exported for the orig.tar.gz.  This allows all local changes to the source
to be recorded in the resulting diff.gz if a pristine upstream branch exists
in the repository.  If an orig tarball already exists for the version at 'branch'
then what happens next depends on the value of the
\%\fBgitpkg.force\-overwrite\-orig\fP configuration option (described below).

The '\fIbranch\fP' should always have a \fIdebian\fP/ dir and may be any
\fItree-ish\fP object that is accepted by \fBgit\-archive\fP(1).
The '\fIorigbranch\fP', if supplied, should usually not have a \fIdebian\fP/
dir.


.SH CONFIGURATION OPTIONS
Almost all \fBgitpkg\fP configuration is handled using \fBgit\-config\fP(1) now.
The following configuration options are supported:

.TP
.B gitpkg.deb\-dir
May be set to override the default destination directory for exported packages.
Default is '\fI../deb\-packages\fP'.  Available to hook scripts as
.nh
.BR DEB_DIR .
.hy
This may be overridden on the command line with the
.nh
.BI \-\-deb\-dir= path
.hy
option.

.TP
.B gitpkg.build\-rootcmd
May be set to override the default command used to get root for package build
operations.  Default is '\fIfakeroot\fP'.  Available to hook scripts as
.nh
.BR BUILD_ROOTCMD .
.hy

.TP
.B gitpkg.prebuild\-target
May be set to a target or targets from \fIdebian/rules\fP which will be called
after the debian source tree is exported, but before the source package is built.
Some packages may use this to generate autoconf files or the like, which should
generally not be in the repo, but which should be in the distributed package.
The target is invoked using the BUILD_ROOTCMD.  A common use for this hook would
be to call the package's '\fIclean\fP' target.  This hook is unset by default
since gitpkg 0.18.  Previous to that it defaulted to the clean target.
Available to hook scripts as
.nh
.BR PREBUILD_TARGET .
.hy

.TP
.B gitpkg.export\-submodules
If a git repository contains submodules, then the submodule managed directories
will not be automatically exported by \fBgit\-archive\fP(1), so if we want them
in the exported source package then we need to jump through some extra hoops to
export the source from each and every submodule too.  Since this may not be the
correct action for every "superproject" repository (especially since
\fBgitpkg\fP has historically just ignored submodules prior to the 0.31 release)
the option to export submodules must be explicitly enabled.

If this option is set to 'true', then we will recursively export all submodules
in the selected superproject revisions.  If it is set to 'false', they will be
treated as they were prior to \fBgitpkg\ 0.31\fP and silently ignored.  If this
option is not set and there are submodules present in the revisions being
exported, then the user will be prompted for the correct action to take.

At present this is an all or nothing selection, there is no way to selectively
exclude only certain submodules from export, but if anyone ever has a real repo
where that is the desired action then it should not be a difficult feature to
add.  As with everything git though, the range of possible use cases makes it
folly to prematurely 'support' straw man use cases, and we should wait to see
what other problems real use cases actually need solved.

Note that in a repo with submodules \fBgitpkg\fP \fImust\fP be run from a
directory that is directly managed by the superproject, not one that belongs
to a submodule.  Any \fBgit\fP commands run in directories that are managed by
submodules will use the configuration for, and act on, only that submodule \-
and it is almost impossible to know or be sure which (of possibly many)
containing superproject is the one the user really wanted to export.  See the
details of the \fBgitpkg.allow\-subproject\-export\fP option below for more
on this.

Available to hook scripts as
.nh
.BR EXPORT_SUBMODULES .
.hy

.TP
.B gitpkg.allow\-subproject\-export
If \fBgitpkg\fP is invoked from a working directory that is managed by some
submodule of a superproject then all \fBgit\fP commands will operate on the
submodule, not on its containing superproject \- and it is almost impossible
for us to know for sure whether the user has done this accidentally, intending
to export the superproject, or deliberately, intending to export just the
submodule package separately from the superproject it is a part of...

So if we detect that \fBgitpkg\fP is invoked from a directory which is managed
by a submodule then we need the user to tell us what they really wanted to do,
and we can't rely on the treeish selected for export to be in any way
persistently unique to just a single repo somewhere in the superproject tree.

If this option is not set, the user will be prompted to confirm whether they
really intended to export just the submodule, with the option to abort and
instead run \fBgitpkg\fP from the desired superproject.

If this option is set to 'true', then we will trust the user understands what
they were doing, knows which subproject repo they invoked \fBgitpkg\fP in, and
intends to export just that submodule (and possibly any other submodules that
it in turn is a superproject for).  And if they ever get that wrong, they get
to keep all the pieces.

If this option is set to 'false', then we will consider it to always be an
error to try and directly export the submodule it is set for and immediately
fail out.  Note that it \fImust\fP be set in the submodule configuration, as
the superproject configuration will not be read.

In theory we could make this option indicate the root of the superproject that
should be exported, but that just replaces an 'obvious' failure mode with a
somewhat more insidious one that assumes an immutable relationship between
them, with a silent awkward failure if that ever changes.

If some subproject really can or should be exported as a package independently
of the superproject it is a submodule of, then best practice is probably to be
exporting it (and actively working on it) from its own independent working
directory, with only selected versions checked out for read-only use as a
submodule.  Especially in the case of Debian packages, where managing them as
a submodule of a superproject would mean that you have \fIdebian\fP directories
and control files nested in the superproject source.

Available to hook scripts as
.nh
.BR ALLOW_SUBPROJECT_EXPORT .
.hy
Though it's probably of little use to them, as it won't be set unless we are
running in a submodule, and none of them will be run before the usual decision
to abort execution.

.TP
.B gitpkg.orig\-compressor
May be set to override the default compression for an exported package.orig.tar.
Default is '\fIgzip\fP'.  For format 3.0 packages, valid values also include
\fIxz\fP and \fIbzip2\fP.  Available to hook scripts as
.nh
.BR ORIG_COMPRESSOR .
.hy

.TP
.B gitpkg.orig\-compress\-level
An optional compression level to use with \fBgitpkg.orig\-compressor\fP.  1 is
usually the fastest and 9 is usually the smallest, with the precise details of
everything between being up to the chosen compressor.  Default is unset (which
will use whatever the compressor default is).  Available to hook scripts as
.nh
.BR ORIG_COMPRESS_LEVEL .
.hy

.PP
.B gitpkg.orig\-gz\-opts
.br
.B gitpkg.orig\-xz\-opts
.br
.B gitpkg.orig\-bz2\-opts
.br
.RS
May be set to pass arbitrary options verbatim to \fIgzip\fP, \fIxz\fP or
\fIbzip2\fP when compressing the orig tarball.  If not specified explicitly,
\%\fBgitpkg.orig\-gz\-opts\fP will default to include the \fB\-\-no\-name\fP
option so that no timestamp is included in the resulting file, making the
output reproducible.  No default options are used for the other compressors.
To pass multiple options to a compressor you must set this option for it
multiple times (ie. using \fBgit\ config\ \-\-add\fP for each option to use).
.RE

.TP
.B gitpkg.deb\-compressor
May be set to override the default compression used by \%\fBdpkg\-source\fP(1)
for exported packages.  Default (if unset) is to use whatever \fBdpkg\-source\fP
wants to use.  For format 3.0 packages, valid values also include \fIxz\fP and
\fIbzip2\fP.  Available to hook scripts as
.nh
.BR DEB_COMPRESSOR .
.hy

.TP
.B gitpkg.deb\-compress\-level
An optional compression level to use with \fBgitpkg.deb\-compressor\fP.  1 is
usually the fastest and 9 is usually the smallest, with the precise details of
everything between being up to the chosen compressor.  Default is unset (which
will use whatever the \%\fBdpkg\-source\fP default is, currently '9').
Available to hook scripts as
.nh
.BR DEB_COMPRESS_LEVEL .
.hy

.TP
.B gitpkg.dpkg\-source
May be set to pass arbitrary options verbatim to \fBdpkg\-source\fP(1) when
building the source package.  Use with caution and at your own risk.  To pass
multiple options to \fBdpkg\-source\fP you must set this option multiple times
(ie. using \fBgit\ config\ \-\-add\fP for each option) due to the otherwise
amusing quoting requirements for options such as \%"\-\-format=3.0\ (native)".
Default is empty.  Available to hook scripts as the indexed array
.nh
.BR DPKG_SOURCE_OPTS .
.hy
Do not use this to set the \%\fBdpkg\-source\fP(1) \fB\-Z\fP or \fB\-z\fP options,
they should instead be set using the \fBdeb\-compressor\fP and
\%\fBdeb\-compress\-level\fP options respectively.
This may be overridden on the command line with the
.nh
.BI \-\-dpkg\-source= arg
.hy
option, which likewise must be passed multiple times to set multiple options.

.TP
.B gitpkg.create\-fake\-orig
Sometimes both upstream source and debian support really are intermingled into
a single branch of the repo but you'd still like to make a 'non-native' package
from it.  \fBgitpkg\fP can fake an orig tarball from such a tree out of everything
but the contents of the debian/ directory.  Setting this option to 'true' makes
that behaviour the default if a single treeish is passed to \fBgitpkg\fP and no
corresponding orig tarball is found.  Setting this option to 'false' will make
\fBgitpkg\fP fail, reporting an error, if a single treeish is passed and no orig
tarball with the correct version already exists for it (and none was retrieved
by a hook script prior to it being needed).  If this option is unset then the
user will be prompted for the correct thing to do if this situation arises.
Default is unset.  Available to hook scripts as
.nh
.BR CREATE_FAKE_ORIG .
.hy

.TP
.B gitpkg.force\-overwrite\-orig
This option controls the behaviour of \fBgitpkg\fP if an 'origbranch' treeish is
specified and the corresponding orig.tar for the 'branch' already exists.
If this is set to 'true', then the orig.tar will be overwritten with the repo
source (to reuse an existing orig.tar simply call \fBgitpkg\fP with only the
single debian 'branch' treeish you wish to export).  If this is set to 'false',
then it is a hard error to attempt to export the upstream source again when the
orig.tar already exists, and \fBgitpkg\fP will terminate and scold you if you try.
If unset you will be prompted about whether to overwrite it or not, and the build
will continue using whichever of the two you selected.  Default is unset.
Available to hook scripts as
.nh
.BR FORCE_OVERWRITE_ORIG .
.hy

.TP
.B gitpkg.keep\-unpacked\-source
This option controls whether or not the unpacked source directory is kept after
the package export and exit hook have successfully completed.  If this is set
to 'true', the unpacked source will be retained.  If set to 'false' or unset
then that directory will be removed as the final operation before \fBgitpkg\fP
exits if all prior operations completed successfully.  Default is unset.
Available to hook scripts as
.nh
.BR KEEP_UNPACKED_SOURCE .
.hy
This may be overridden on the command line with the
.nh
.BI \-\-keep\-unpacked\-source= bool
.hy
option (where 'no' or 'false' will not keep it, and any other value, including
nothing, will).


.SH SCRIPT HOOKS
User defined scripts can be invoked from a number of points during the package
build process.  They are sourced into \fBgitpkg\fP as bash shell snippets, in
most cases in a subshell, so they can read state variables and perform external
actions, but cannot alter the running configuration once a build is in progress.
If a hook returns with a non-zero status, then \fBgitpkg\fP will be terminated.
(Hooks that do terminate gitpkg should take some care not to leave too much of a
mess, but also should leave enough clues intact for the user to diagnose and fix
whatever the problem was.  Useful and informative error messages should be barked
to stderr before exiting in this way.)

Hook scripts may be installed on the host system outside of the repo tree, or
sourced from version controlled files in the repo itself.  Both methods have
advantages and risks for different use cases.  Hook scripts are activated by
the local admin, by setting each relevant \fBgit\-config\fP(1) option with the
path to the script to be executed.  Paths may be absolute or relative to the
directory which that hook is called from.  If a hook is set, the script
\fBmust\fP exist when it is called.  Care should be taken to only enable them
for use by trusted source trees when hooking into files in the repo itself.
Usually you should enable them on a per-repo basis with \fBgit\-config\fP(1)
rather than at a \fB\-\-global\fP or \fB\-\-system\fP level.

.SS A brief admonition against getting hooked:
You should avoid complicated in-package hook arrangements becoming essential for
exporting your package source.  If you need them to create a particular package
correctly, and need strict version binding with the source being released, and
they aren't useful to any other package at all ...  then you're quite probably
doing something, or several things, quite wrong.  Else you're in such deep shit
working around some broken build system that you don't need me to tell you about
it.  Either way, local admin has to enable your hooks before they can run, so if
you want to be friendly to others (and yourself), then keep the 'normal' packaging
work strictly inside the usual package building tools, and leave the gitpkg hooks
free for other local admins to wrap whatever automation it is \fIthey\fP need
around things.  If a particular version of the package source needs some particular
actions performed on it prior to the first source package build, then the
.B PREBUILD_TARGET
option from above is most probably what you want rather than one of these hooks.
Other people can use that again later without needing to have gitpkg around.
The aim is for this to Help You.  For some values of All Of You.  So do be
careful to avoid letting it screw other people over if the hook isn't called,
and/or let them know what they need to do instead if it isn't.  Ok then, there's
the barb to watch out for, so back to the point again:

.SS Hook points
The available hook points are listed below in roughly the order that they
would usually be invoked:

.TP
.B gitpkg.package\-config\-hook
This hook runs in the top level directory of the repo \fBgitpkg\fP was invoked
in, prior to any operations taking place, with all \fBgit\-config\fP(1) sourced
options available to it.  No detailed information about the package itself is
available in the hook environment yet, not even its name or version, only the
tree-ish(es) that \fBgitpkg\fP was passed by the user, but the hook may run its
own self-checks based on the current (possibly 'dirty') contents of the working
tree that \fBgitpkg\fP was invoked in.

This hook is able to modify the \fBgitpkg\fP configuration variables for
subsequent operations.  It can perform operations on the repo if needed, but
since it needs to be committed to the repo before it will ever be called, that
may not be so useful here in practice.  Basically, it can do anything it pleases,
it's just a shell script, nothing else has really begun yet, and it has been
sourced into the topmost shell level of \fBgitpkg\fP.

Its operation is different from the \fBadmin\-config\-hook\fP in only one respect,
the path to this hook \fBmust\fP be relative to the TLD of the repo, and the
revision of the file that will be sourced is checked out from the 'branch'
tree-ish that \fBgitpkg\fP was requested to export.  The file must exist in
that version at the path given.

Available to hook scripts as
.nh
.BR PACKAGE_CONFIG_HOOK .
.hy

.TP
.B gitpkg.admin\-config\-hook
This hook is run after the \fBpackage\-config\-hook\fP returns, and differs from
it in operation only by reading a static file from the current filesystem rather
than extracting a version controlled one from the repo being exported.

This can be used by the local admin to override any package specific options,
that may have been set by the \fBpackage\-config\-hook\fP, with site specific
configuration.  This is a policy control, not a security one.  Security was
all over when you let the \fBpackage\-config\-hook\fP run, this just lets you
override it without having to fake up a new commit changing the package hook.

This is the last hook to run that is able to modify the \fBgitpkg\fP
configuration and set environment options that will be visible to later hooks.
Available to hook scripts as
.nh
.BR ADMIN_CONFIG_HOOK .
.hy
This may be overridden on the command line with the
.nh
.BI \-\-admin\-config\-hook= path
.hy
option.

.TP
.B gitpkg.pre\-export\-hook
This hook runs in the top level directory of the repo, after the package name
and version have been determined, and with the final package configuration
including any tweaking by the previous hooks.  It cannot alter any configuration
options, only act upon them or terminate \fBgitpkg\fP.

This can be used to do things like invoke pristine\-tar or prefetch an existing
orig tarball from some foreign source.  It may perform operations on the repo if
any such are desired, or any other last minute check that needs to be done before
we actually get about the task of exporting the source we want packaged.

Available to hook scripts as
.nh
.BR PRE_EXPORT_HOOK .
.hy

.TP
.B gitpkg.deb\-export\-hook
This hook runs in the top level directory of the exported debian source,
immediately after the source has been exported from the requested \fItree-ish\fP,
and immediately prior to the \fBPREBUILD_TARGET\fP being invoked (if provided).
It cannot alter any configuration options, only act upon them or terminate
\fBgitpkg\fP.  If this hook terminates \fBgitpkg\fP, the exported source directory
will be left on the system for the user to inspect.  Subsequent invocations of
\fBgitpkg\fP for the same release version will overwrite it though.
Available to hook scripts as
.nh
.BR DEB_EXPORT_HOOK .
.hy

.TP
.B gitpkg.orig\-export\-hook
This hook runs in the top level directory of the exported 'upstream' source,
immediately after the source has been exported from the provided \fItree-ish\fP,
and prior to it being compressed into a tarball.  It cannot alter any configuration
options, only act upon them or terminate \fBgitpkg\fP.  If this hook terminates
\fBgitpkg\fP, the exported source directory will be left on the system for the user
to inspect.  Subsequent invocations of \fBgitpkg\fP for the same release version
will overwrite it though.

This hook is \fBonly\fP invoked if the upstream 'origbranch' actually is exported
from the repository.  If an existing orig.tar is found or has been created by some
earlier hook (and it is not being overwritten, see \fBforce\-overwrite\-orig\fP above),
then the operations this hook would perform are presumed to have already happened
for this tarball and it is skipped.

It is not safe to assume that this hook will be executed before or after 
\fBdeb\-export\-hook\fP, and it may in fact be run in parallel with it at some
point in the future.  They both will be entered after \fBpre\-export\-hook\fP
returns, and \fBexit\-hook\fP will not begin until (at least) after both have
returned.  What else happens in the middle of all that we make no firm promises
about at this stage.

Available to hook scripts as
.nh
.BR ORIG_EXPORT_HOOK .
.hy

.TP
.B gitpkg.exit\-hook
This hook runs in the directory where the package \fI.dsc\fP was deposited by
\fBdpkg\-source\fP(1), after all internal \fBgitpkg\fP operations have successfully
completed.  It's too late to alter any configuration options, or even to terminate
\fBgitpkg\fP really.  You can pretty much do what you like from this one, anything
that goes wrong from here on is your own doing.  Available to hook scripts as
.nh
.BR EXIT_HOOK .
.hy
This may be overridden on the command line with the
.nh
.BI \-\-exit\-hook= path
.hy
option.


.SS Hook Environment
The following variables are made available for hook scripts, in addition to those
already listed as shadowing a \fBgit\-config\fP option from above.  Not all of them
are valid/useful at all hook points, see the hook documentation above for the
exceptions applying to specific hooks.

.TP 4
.B GITPKG_HOOK_API
Permits hook scripts to query what interfaces are available to them.
Has only two numeric components separated by a '.' of which the number
to the right of point will get incremented every time we add some new
variable a hook might access, or add some new knob it might tweak where
existing interfaces have not have changed.  If we do screw up and need
to change some current interface, the number to the left will get bumped.
The current API version is 0.3

.SS Available in API version 0.1
These variables have been available to hooks since gitpkg version 0.13
.TP 4
.B GITPKG_TREEISH
The user-passed debian 'branch' tree-ish that gitpkg was invoked to export.

.TP
.B GITPKG_ORIG_TREEISH
The 'origbranch' tree-ish that gitpkg was invoked with.  This will be empty
if only a single 'branch' tree-ish was specified.

.TP
.B DEB_SOURCE
The name of the source package to create, without any versioning.
As seen in the Source: field of \fBdpkg\-parsechangelog\fP(1).

.TP
.B DEB_VERSION
The version of the source package to create, without any epoch.
As seen in the name of the .diff.gz and .dsc files.

.TP
.B UPSTREAM_VERSION
The version of the source package to create, without any debian version.
As seen in the name of the orig tarball.  For native packages this will be
the same as \fBDEB_VERSION\fP.

.TP
.B DEB_ORIG
The full versioned filename of the orig tarball to use or create.
This variable is empty for native packages without a Debian version part.

.TP
.B DEB_DSC
The full filename of the package \fI.dsc\fP that will be or has been created.

.TP
.B DEB_PACKAGE
The directory name of the debianised source tree to pass to \fBdpkg\-source\fP(1).

.TP
.B REPO_DIR
An absolute path to the top level directory of the git repo we are exporting from.
Usually, if you need to look out of the tree that you were dropped in, you're
probably doing something (at the) wrong (time), but there are exceptions, and
being able to query \fBgit\-config\fP options is one of them.  That's mostly what
this one is for right now.  See the \fBrepo\-config\-helper\fP documented below.
Be careful if you do use it for much else.


.SS Available in API version 0.2
These variables have been available to hooks since gitpkg version 0.24

.TP 4
.B GITPKG_AOPTS
An associative array containing the command line options not parsed by \fBgitpkg\fP
itself which can be used to override the behaviour of a hook.  The array is keyed
on the names of the options with the '\-\-' removed.  If an option was passed
multiple times, only the last value passed will be stored in this array.
For example:

.nh
.nf
 $ gitpkg \-\-my\-option=foo \-\-option2 \-\-opt=oops \-\-opt='bar baz'

Will give:

 ${GITPKG_AOPTS[my-option]} = 'foo'
 ${GITPKG_AOPTS[option2]}   = ''
 ${GITPKG_AOPTS[opt]}       = 'bar baz'
.fi
.hy

.TP
.B GITPKG_IOPTS
An indexed array containing the command line options not parsed by \fBgitpkg\fP
itself which can be used to override the behaviour of a hook. The array contains
the literal option strings passed and so can be used to access options which are
intended to be passed multiple times.
For example:

.nh
.nf
 $ gitpkg \-\-my\-option=foo \-\-option2 \-\-opt=oops \-\-opt='bar baz'

Will give:

 ${GITPKG_IOPTS[0]} = '\-\-my\-option=foo'
 ${GITPKG_IOPTS[1]} = '\-\-option2'
 ${GITPKG_IOPTS[2]} = '\-\-opt=oops'
 ${GITPKG_IOPTS[3]} = '\-\-opt=bar baz'
.fi
.hy

There are convenience functions in \fBrepo\-config\-helper\fP (see below for
details) which can be used to inspect this array and obtain all the value(s)
for a specific option.


.SS Available in API version 0.3
A range of new support functions were added to \fBrepo\-config\-helper\fP in
gitpkg version 0.30

.RS 2

- require_bash_version()
.br
- trim_array()

- have_commandline_option()
.br
- have_any_of_these_commandline_options()

- extract_values_for()
.br
- extract_value_for()
.br
- extract_bool_for()

- get_option_values()
.br
- get_option_value()
.br
- get_bool_value()

.RE

These are described in more detail in the \fBHook Library Helpers\fP section
below.


.SS Hook Library
There are some canned hook scripts for various tasks available in
.I /usr/share/gitpkg/hooks
which currently include:

.TP 4
.B cowpoke\-exit\-hook
A simple exit hook which sends the exported package off for building using
.BR cowpoke (1).
To enable it:

.nh
.nf
 $ git config gitpkg.exit\-hook /usr/share/gitpkg/hooks/cowpoke\-exit\-hook
.fi
.hy

Additional \fBgit\-config\fP(1) configuration options:

.RS

.TP 4
.B gitpkg\-cowpoke\-exit\-hook.ask\-first
If 'true' and no cowpoke\-specific command line option was passed, then prompt
for confirmation before calling \%\fBcowpoke\fP. Use of a cowpoke option on the
command-line is an implicit acknowledgement that the caller knows and intends
that the exported source package will be sent to cowpoke to be built, and so
will skip this confirmation nagging.

Default is to just go ahead and do it if this hook is set.

.TP
.B gitpkg\-cowpoke\-exit\-hook.options
May include any other options that you wish to pass verbatim to
\%\fBcowpoke\fP(1).  To pass multiple options, set this multiple times,
once for each option.  This may be overridden on the command line with the
.nh
.BI \-\-cowpoke= arg
.hy
option, which likewise must be passed multiple times to set multiple options.

You can use \fB\-\-cowpoke=\fP (or equivalently, either \%\fB\-\-cowpoke\fP or
\%\fB\-\-no\-cowpoke\fP) to override and clear all configured \%\fB.options\fP
without needing to pass some arbitrary new one.  This will not override any
other \%\fB\-\-cowpoke=\fIarg\fR options which are passed on the command line.
As a multi-valued option, all empty values which are passed for it will simply
be ignored aside from causing the configuration file defaults to be ignored.

.TP
.B gitpkg\-cowpoke\-exit\-hook.arch
The default Debian architecture(s) to build for.  Setting this option to <arch>
is equivalent to using
.nh
.BI \-\-arch= <arch>
.hy
in \%\fB.options\fP above, except using \fB\-\-arch\fP on the command line will
only override any architectures set with this option, and
.nh
.BI \-\-cowpoke=\-\-arch= <arch>
.hy
will not override architectures set with this option.  To build for multiple
architectures set this (or use \fB\-\-arch\fP on the command line) multiple
times, once for each <arch>.

If no arch is set or passed on the command line it will default to whatever is
configured in \fBcowpoke.conf\fP, which in turn will default to what
\%\fBdpkg\-architecture\fP(1) returns for \fBDEB_BUILD_ARCH\fP on the machine
that is running \fBgitpkg\fP.

.TP
.B gitpkg\-cowpoke\-exit\-hook.dist
The default Debian distribution(s) to build for.  Setting this option to <dist>
is equivalent to using
.nh
.BI \-\-dist= <dist>
.hy
in \%\fB.options\fP above, except using \fB\-\-dist\fP on the command line will
only override any distributions set with this option, and
.nh
.BI \-\-cowpoke=\-\-dist= <dist>
.hy
will not override distributions set with this option.  To build for multiple
distributions set this (or use \fB\-\-dist\fP on the command line) multiple
times, once for each <dist>.

If no dist is set or passed on the command line it will default to whatever is
configured in \fBcowpoke.conf\fP, and if not set there it will default to
whatever cowbuilder is locally configured for on the remote machine.

The <dist> name used here may also be a locally defined identifier for any
specially configured cowpoke chroot that is available, such as those set up
for building backports or using extra packages only available from a local
repository.  See the \fBcowpoke\fP(1) description of its \fB\-\-dist\fP option
for details of that.

.TP
.B gitpkg\-cowpoke\-exit\-hook.dpkg\-bp
Additional options for use by \fBdpkg\-buildpackage\fP(1).  Setting this option
is equivalent to using
.nh
.BI \-\-dpkg\-bp= option
.hy
in \fB.options\fP above, except using \fB\-\-dpkg\-bp\fP on the command line
will only override the configuration that was set with this option, and
.nh
.BI \-\-cowpoke=\-\-dpkg\-bp= option
.hy
will not override the configuration that is set with this option.  To pass
multiple options to \%\fBdpkg\-buildpackage\fP set this (or use
\fB\-\-dpkg\-bp\fP on the command line) multiple times, once for each
\fIoption\fP.

These options will be appended to any that are specified in \fBDEBBUILDOPTS\fP
in the build host's \fIpbuilderrc\fP.  To clear any already preset options,
first pass it with an empty argument (i.e.
.BI "\-\-dpkg\-bp=\ \-\-dpkg\-bp=" option "\fR\ ...)."

.TP
.B gitpkg\-cowpoke\-exit\-hook.source\-changes
If set to '\fBtrue\fP', '\fByes\fP', '\fBsigned\fP', or set without a value
(or to an empty string), then it is equivalent to adding the \%\fBcowpoke\fP(1)
option \%\fB\-\-sign\-source\-changes\fP to \fB.options\fP above, except it is
independent of the options that would be overridden by \fB\-\-cowpoke\fP on the
command line.  The value \fBsigned\fP has no additional special effect for this
hook, it is supported for equivalence with the values accepted for
\fB.source\-changes\fP in the
.nh
.BR dpkg\-buildpackage\-exit\-hook .
.hy

If set to '\fBfalse\fP' or '\fBno\fP', it is the equivalent of
adding the \fBcowpoke\fP(1) option
.nh
.BR \-\-no\-sign\-source\-changes .
.hy

The default if this option is not set at all is defer to
\fBSIGN_SOURCE_CHANGES\fP in the \fBcowpoke.conf\fP, or if it is not set
to the \fBpbuilder\fP(8) configuration \fBSOURCE_ONLY_CHANGES\fP setting.

All other values passed with this option are an error.

This setting may be overridden on the command line with
.nh
.BR \-\-sign\-source\-changes [ =\fIarg ]
.hy
where legal values for \fIarg\fP and their actions are the same as described
above.  Using \fB\-\-no\-sign\-source\-changes\fP has the equivalent effect to
using
.nh
.BR \-\-sign\-source\-changes=no .
.hy

.TP
.B gitpkg\-cowpoke\-exit\-hook.sign\-key
May be set to the fingerprint of the key to sign packages with.  This will
override the \fBSIGN_KEYID\fP specified for a chroot in the cowpoke
configuration files.  If you use different keys to sign packages built in
different chroots, then you should probably configure the signing key ID in
\fBcowpoke.conf\fP instead, but for individual builds you can override it on
the command line with the
.BI \-\-sign= keyid
option.

The \fB\-\-no\-sign\fP option will cancel the use of any keyid that was set
with \fB.sign\-key\fP in the git config, or by a previous command-line option,
but this just means \fBgitpkg\fP will not pass a keyid to \fBcowpoke\fP, it
does not override cowpoke's own configuration which may still specify a default
key to use for the given arch/dist.  To also override any \fBSIGN_KEYID\fP that
is set in \%\fBcowpoke.conf\fP you can instead use \fB\-\-sign=\fP (with an
empty argument), which will be passed through to cowpoke and clear the signing
keyid, preventing cowpoke from offering the option of signing the packages
after they are built.

.TP
.B gitpkg\-cowpoke\-exit\-hook.upload\-to
The \fBdput\fP(1) \fIHOSTNAME\fP to upload packages to.  This will override
the \fBUPLOAD_QUEUE\fP specified for a chroot in the cowpoke configuration
files.  If you use different upload queues for packages built in different
chroots, then you should configure this in \fBcowpoke.conf\fP instead, but
for individual builds you can override the upload queue on the command line
with the
.nh
.BI \-\-upload= queue
.hy
option.

The \fB\-\-no\-upload\fP option will cancel the use of any upload queue that
was set with \fB.upload\-to\fP in the git config, or by a previous command-line
option, but this just means \fBgitpkg\fP will not pass an upload queue to
\fBcowpoke\fP, it does not override cowpoke's own configuration which may still
specify a default queue to use for the given arch/dist.  To also override any
\fBUPLOAD_QUEUE\fP that is set in \fBcowpoke.conf\fP you can instead use
\fB\-\-upload=\fP (with an empty argument), which will be passed through to
cowpoke and clear the upload queue, preventing cowpoke from offering the option
of uploading the packages after they are signed.

.TP
.B gitpkg\-cowpoke\-exit\-hook.return\-dir
This may be set to a filesystem path on the local host (absolute or relative to
the directory which \fBgitpkg\fP(1) was invoked from) where the packages built
by cowpoke will be copied to once the build is completed.  It may be specified
on (or overridden by) the command line with the
.nh
.BR \-\-return [ =\fIpath ]
.hy
option.  If no path is specified, the (\fBcowpoke\fP) default is the current
directory.

The \fB\-\-no\-return\fP option will cancel a \fB.return\-dir\fP set in the git
config, or by a previous command-line option, but this just means \fBgitpkg\fP
will not pass a return dir to \fBcowpoke\fP, it does not override cowpoke's own
configuration which may still specify a \fBRETURN_DIR\fP. Because \fBcowpoke\fP
recognises \fB\-\-return\fP (with no value assignment) as a discrete option, to
override and clear \%\fBRETURN_DIR\fP that is set in \fBcowpoke.conf\fP from
here you must pass the empty assignment verbatim in the \fB.options\fP
configuration, or on the command line with \fB\-\-cowpoke=\-\-return=\fP which
will bypass the normal \fBgitpkg\fP handling of the \fB\-\-return\fP option.

.RE


.TP
.B dpkg\-buildpackage\-exit\-hook
A simple exit hook to build binary packages locally with
.nh
.BR dpkg\-buildpackage (1).
.hy
To enable it:

.nh
.nf
 $ git config gitpkg.exit\-hook /usr/share/gitpkg/hooks/dpkg\-buildpackage\-exit\-hook
.fi
.hy

Additional \fBgit\-config\fP(1) configuration options:

.RS

.TP 4
.B gitpkg\-dpkg\-buildpackage\-exit\-hook.ask\-first
If 'true' and no dpkg\-buildpackage\-specific command line option was passed,
then prompt for confirmation before calling \%\fBdpkg\-buildpackage\fP. Use of
a dpkg\-buildpackage option on the command-line is an implicit acknowledgement
that the caller knows and intends that the exported source package will be
built with \fBdpkg\-buildpackage\fP(1) and so will skip this confirmation
nagging.

Default is to just do it if this hook is set.

.TP
.B gitpkg\-dpkg\-buildpackage\-exit\-hook.options
May include any other options that you wish to pass verbatim to
\%\fBdpkg\-buildpackage\fP.  To pass multiple options, set this multiple times,
once for each option. This may be overridden on the command line with the
.nh
.BI \-\-dpkg\-bp= arg
.hy
option, which likewise must be passed multiple times to set multiple options.

You can use \fB\-\-dpkg\-bp=\fP (or equivalently, either \%\fB\-\-dpkg\-bp\fP
or \%\fB\-\-no\-dpkg\-bp\fP) to override and clear all configured
\%\fB.options\fP without needing to pass some arbitrary new one.  This will not
override any other \%\fB\-\-dpkg\-bp=\fIarg\fR options which are passed on the
command line.  As a multi-valued option, all empty values which are passed for
it will simply be ignored aside from causing the configuration file defaults to
be ignored.

.TP
.B gitpkg\-dpkg\-buildpackage\-exit\-hook.source\-changes
If '\fBtrue\fP' or '\fByes\fP' then a \fI<package>_source.changes\fP file,
suitable for a "source only" upload, will be generated (independently of any
changes file that \%\fBdpkg\-buildpackage\fP creates according to the options
passed to it).  If the \fB\-uc\fP or \%\fB\-\-unsigned\-changes\fP option was
passed to \%\fBdpkg\-buildpackage\fP then this changes file will not be signed
either.

If set to the special value '\fBsigned\fP' then the
\%\fI<package>_source.changes\fP file, and any \fB.dsc\fP or \fB.buildinfo\fP
files referenced by it, will be signed regardless of any
.BR \-uc ", " \-us ", " \-ui
options being used to suppress signing of the files created by
\%\fBdpkg\-buildpackage\fP.  This makes it possible to do a full binary build,
creating source and \fB.deb\fP files for inspection and testing, but then sign
only the files needed to do a source only upload to another build farm.

If set without a value (or to an empty string), then the behaviour is the same
as if it was set to '\fBsigned\fP' and
.nh
.BI \-\-dpkg\-bp= \-uc "\ \-\-dpkg-bp=" \-us
.hy
were passed.  i.e. Only the \%\fI<package>_source.changes\fP file (and the
files referenced by it) will be signed, not the binary files created by the
build. This is probably what most people want when exporting a package with
the intent of doing a "source only" upload.

The default if unset is the same as setting this option to '\fBfalse\fP'
or '\fBno\fP', no \fI<package>_source.changes\fP file will be created by this
hook and the behaviour is simply what would be expected from
\%\fBdpkg\-buildpackage\fP(1) with any otherwise configured options passed
to it.

All other values passed with this option are an error.

This setting may be overridden on the command line with
.nh
.BR \-\-sign\-source\-changes [ =\fIarg ]
.hy
where legal values for \fIarg\fP and their actions are the same as described
above.  Using \%\fB\-\-no\-sign\-source\-changes\fP has the equivalent effect
to using
.nh
.BR \-\-sign\-source\-changes=no .
.hy

.TP
.B gitpkg\-dpkg\-buildpackage\-exit\-hook.sign\-key
May be set to the fingerprint of the key to use for signing exported and built
package files.  If not set then the signing key derived by (or set in other
configuration for) \%\fBdpkg\-buildpackage\fP(1) will be used when signing
binary changes files, with the defaults for \fBdebsign\fP(1) being used in the
case where a "source only upload" changes is being signed.

Since those two tools don't use the same configuration, that may not be
the same key for all users on all machines, but we do respect and use
\fBDEB_SIGN_KEYID\fP from the environment (if it is set with no other
overriding configuration), when calling \fBdebsign\fP, as it would otherwise
ignore that configuration option from \fBdpkg\-buildpackage\fP.  The usual
debsign default is instead \fBDEBSIGN_KEYID\fP and set in the
\%\fBdevscripts.conf\fP file.

You can override the signing key on the command line with the
.BI \-\-sign= keyid
option.  The \fB\-\-no\-sign\fP option will cancel the use of any keyid that
was set with \fB.sign\-key\fP in the git config, or by a previous command-line
option, but this just means \fBgitpkg\fP will not pass a keyid to
\%\fBdpkg\-buildpackage\fP(1) and it will revert to its own determination of
what key should be used for signing.  To actually not sign a package you'll
want to use something like
.nh
.BI \-\-dpkg-bp= -uc " \-\-dpkg-bp=" -us \fR
.hy
to explicitly disable signing.

.TP
.B gitpkg\-dpkg\-buildpackage\-exit\-hook.build\-log
If set 'false' don't save a log of the build process, the default is to
record one.  This may be overridden on the command line with the
.BR \-\-build\-log [ =\fIbool-value "] or " \-\-no\-build\-log
option.

.RE


.TP
.B pristine\-tar\-pre\-export\-hook
A hook to extract an orig tarball using pristine\-tar.  Which orig to extract
is determined by the package version of the 'branch' tree-ish.
To enable it:

.nh
.nf
 $ git config gitpkg.pre\-export\-hook /usr/share/gitpkg/hooks/pristine\-tar\-pre\-export\-hook
.fi
.hy

If a pristine\-tar branch is not found in the repo, then gitpkg will be terminated.


.TP
.B quilt\-patches\-deb\-export\-hook
This hook reads a list of revision ranges suitable for \fBgit\-format\-patch\fP(1)
from the file \fIdebian/source/git\-patches\fP, one per line, and exports them to
the \fIdebian/patches\fP directory in a form suitable for (format 3.0) quilt
packages.  It is not required for creating such packages, but permits you to
separate out individual patches however you please from the default single patch
that is otherwise created by \fBdpkg\-source\fP.

To enable it:

.nh
.nf
 $ git config gitpkg.deb\-export\-hook /usr/share/gitpkg/hooks/quilt\-patches\-deb\-export\-hook
.fi
.hy

The contents of \fIdebian/source/git\-patches\fP may include comments (on any
line beginning with a #), empty lines, and expressions of a range of commits.
The revision ranges may include \fB$DEB_VERSION\fP, \fB$UPSTREAM_VERSION\fP,
\fB$DEB_REF\fP or \fB$UPSTREAM_REF\fP.  The first pair will be substituted
with the version of the package being exported, the second pair with those
version strings after mangling by \fBsanitise_git_ref\fP to remap them to a
legal git \fIrefname\fP.  Using the sanitised versions is to be preferred in
most cases.  For example:

.nh
.nf
 # Export all commits between these two treeishes,
 # based on the version of the package being exported.

 upstream/$UPSTREAM_REF..patches/$DEB_REF
.fi
.hy


.TP
.B debcherry\-deb\-export\-hook
This hook invokes \fBgit\-debcherry\fP(1) to find and export patches to the
upstream source in a form suitable for use with (format 3.0) quilt packages.
It allows for a more natural (and automatic) workflow than the quilt\-patches
hook above by searching for patches made to the packaging branch that have
not yet been applied upstream.

To enable it:

.nh
.nf
 $ git config gitpkg.deb\-export\-hook /usr/share/gitpkg/hooks/debcherry\-deb\-export\-hook
.fi
.hy

In order to use this hook, a \fB${DEB_ORIG}.commit\fP file must be created which
contains the treeish of the exported upstream source in the repository.  This will
be created automatically (if this hook is enabled) when you export an upstream
tarball by passing both \fIbranch\fP and \fIorigbranch\fP to \fBgitpkg\fP, or if
you use the \fBpristine\-tar\-pre\-export\-hook\fP, which determines an appropriate
commit corresponding to the tarball.  If your upstream tarball is created using
some other mechanism you will need to ensure that file is created yourself.

If using this hook, you may wish to document that in your repository with
something similar to the text in
\%\fI/usr/share/doc/\:gitpkg/\:examples/\:README.debcherry\-export\fP as a
convenience to other users. Your package will still be exportable without this
hook enabled, it just won't have the upstream patches individually separated
out into a quilt series.


.SS Hook Library Helpers
These are additional shell code snippet files which are also found in
\%\fI/usr/share/\:gitpkg/hooks\fP, for operations which may usefully be shared by
several hook scripts.  Usually these would be sourced by other scripts rather
than being hooked to directly.

.TP 4
.B repo\-config\-helper
This file provides functions for querying configuration options which may be
set in the project \fBgit\-config\fP, or overridden by command line arguments.

.RS

.TP 4
.B repo_config()
Provides a simple wrapper around `\fBgit config\fP`, which ensures it is called
from the repo tree where any repo-specific config options may be stored.  Useful
to scripts which aren't called from inside the repo tree, but which do have
\fBgit\-config\fP(1) options of their own to query.

.TP
.B sanitise_git_ref()
Remaps character strings that are illegal to use in a git refname.

.TP
.B require_bash_version()
Allows a hook script to assert a minimum bash version needed to provide all the
functionality its implementation requires.

.TP
.B trim_array()
Removes all empty elements from an array.  This can be useful for, among other
things, filtering option values where an empty value should not propagate as an
argument word.

.TP
.B have_commandline_option()
A Simple true or false test of whether some \fB\-\-\fIoption\fR or its
counterpart \%\fB\-\-no\-\fIoption\fR were passed on the command line, which
evaluates to \fBfalse\fP if neither of them were.

.TP
.B have_any_of_these_commandline_options()
Convenience function to call \fBhave_commandline_option\fP for multiple
options, returning \fBtrue\fP if any of them were passed, or \fBfalse\fP if
none of them were.

.TP
.B extract_values_for()
This is a refinement of the older (and now deprecated)
\%\fBextract_values_for_option()\fP function which is much cleaner to use, but
depends on functionality that was introduced in \fBbash\fP version 4.3 (which
has been available since Jessie, so it shouldn't practically limit backports of
this \fBgitpkg\fP release).

It is designed to query multi-valued command line options, filling an array
with all of the values passed to \fBgitpkg\fP for some option which were
recorded in \fBGITPKG_IOPTS\fP (or any similar array).

.TP
.B extract_value_for()
More suited for single-valued options, this sets a variable to the value of
the final overriding instance of a command line option.

.TP
.B extract_bool_for()
Like \fBextract_value_for()\fP, but intended for options where all values are
expected to be either true or false.

.TP
.B get_option_values()
Fill a multi-valued array with optional hard-coded default values, overriding
those defaults with a (multi-valued) configuration option from git-config, and
overriding both of those if any values were passed for it on the command line.

.TP
.B get_option_value()
Assign a single-valued variable with an optional hard-coded default value,
overriding that default with a configuration option from git-config, and
overriding both of those if a value was passed on the command line.

.TP
.B get_bool_value()
Like \fBget_option_value()\fP except all values set are either true or false.

.PP
See the content of that file itself for more detailed documentation on these
functions, their operation, and calling conventions.

.RE


.SH INTERACTIVIY
If you intend to call \fBgitpkg\fP from your own scripts, then you should note
that there are two situations when it may prompt interactively by default.
There is no One True Sane Default for these cases, so it's better to just ask
the user and continue than to make them start the whole process again in the
likely case where they have called \%\fBgitpkg\fP directly.  For details, see
the \%\fBgitpkg.force\-overwrite\-orig\fP and \%\fBgitpkg.create\-fake\-orig\fP
config options above.  You should set both explicitly to the behaviour that you
desire from them if \%\fBgitpkg\fP should never become interactive.

.SH WORKFLOW
Though \fBgitpkg\fP explicitly does not try to force any particular workflow
procedure upon you in order to make full use of it, it probably is worth making
quick mention of at least one simple way to manage Debian packages in git.

One common repo structure is to keep pristine upstream source on one branch,
which is updated either directly from an upstream repo or by importing tar
archives to it periodically, with the Debian patched source on another branch.
In this situation the task of preparing a new upstream release from a tarball
might look a bit like this:

   Check out the upstream branch
 $ cd myrepo
 $ git checkout upstream

   Remove all old upstream files from the repo
 $ rm \-rf $(all_files_except .git)

   Unpack the new tarball in their place
 $ tar zxf $new_upstream.tar.gz

   Let git figure out what is renamed/new/gone by itself.
   Make sure you don't have things like vim .swp files lurking
   in the tree still at this point.
 $ git add .
 $ git commit \-a
 $ git tag v$upstream_version

   Prepare the Debian branch
 $ git checkout debian
 $ git merge upstream
 $ $(update changelog and other debian patches etc.)
 $ git commit \-a
 $ git tag v${upstream_version}\-$debian_version

   Make a release
 $ gitpkg v${upstream_version}\-$debian_version v$upstream_version
 $ cd ../deb\-packages/mypackage && dpkg\-buildpackage ...

.SH SEE ALSO
.nh
.BR git\-debimport (1),
.BR git\-debcherry (1),
.BR git (1),
.BR git\-archive (1),
.BR git\-config (1),
.BR git\-format\-patch (1),
.BR gitattributes (5),
.BR dpkg\-source (1),
.BR cowpoke (1).
.hy

.SH AUTHOR
.B gitpkg
was written by Ron <ron@debian.org>.