Ubuntu Manpage: gitpkg - export a Debian source package from nominated git revisions

NAME

       gitpkg - export a Debian source package from nominated git revisions

SYNOPSIS

       gitpkg branch [origbranch]

DESCRIPTION

       If  gitpkg  is  run  in  a git(1) repo with a single 'branch' specified, then it will do a
       git-archive export of that branch to the DEB_DIR 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
       gitpkg.create-fake-orig configuration option (described below).

       If gitpkg 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 gitpkg.force-overwrite-orig configuration option (described below).

       The  'branch'  should  always  have  a  debian/ dir and may be any tree-ish object that is
       accepted by git-archive(1).  The 'origbranch', if supplied,  should  usually  not  have  a
       debian/ dir.

CONFIGURATION OPTIONS

Almost all gitpkg configuration is handled using git-config(1) now. The following
configuration options are supported:

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

gitpkg.build-rootcmd
May be set to override the default command used to get root for package build
operations. Default is 'fakeroot'. Available to hook scripts as BUILD_ROOTCMD.

gitpkg.prebuild-target
May be set to a target or targets from debian/rules 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 'clean' 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 PREBUILD_TARGET.

gitpkg.export-submodules
If a git repository contains submodules, then the submodule managed directories
will not be automatically exported by git-archive(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 gitpkg 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 gitpkg 0.31 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 gitpkg must be run from a directory that is
directly managed by the superproject, not one that belongs to a submodule. Any git
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
gitpkg.allow-subproject-export option below for more on this.

Available to hook scripts as EXPORT_SUBMODULES.

gitpkg.allow-subproject-export
If gitpkg is invoked from a working directory that is managed by some submodule of
a superproject then all git 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 gitpkg 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
gitpkg 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 gitpkg 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 must 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 debian directories and control
files nested in the superproject source.

Available to hook scripts as ALLOW_SUBPROJECT_EXPORT. 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.

gitpkg.orig-compressor
May be set to override the default compression for an exported package.orig.tar.
Default is 'gzip'. For format 3.0 packages, valid values also include xz and
bzip2. Available to hook scripts as ORIG_COMPRESSOR.

gitpkg.orig-compress-level
An optional compression level to use with gitpkg.orig-compressor. 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
ORIG_COMPRESS_LEVEL.

gitpkg.orig-gz-opts
gitpkg.orig-xz-opts
gitpkg.orig-bz2-opts
May be set to pass arbitrary options verbatim to gzip, xz or bzip2 when compressing
the orig tarball. If not specified explicitly, gitpkg.orig-gz-opts will default to
include the --no-name 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 git config --add for each option to use).

gitpkg.deb-compressor
May be set to override the default compression used by dpkg-source(1) for exported
packages. Default (if unset) is to use whatever dpkg-source wants to use. For
format 3.0 packages, valid values also include xz and bzip2. Available to hook
scripts as DEB_COMPRESSOR.

gitpkg.deb-compress-level
An optional compression level to use with gitpkg.deb-compressor. 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 dpkg-source default is, currently '9'). Available to hook scripts as
DEB_COMPRESS_LEVEL.

gitpkg.dpkg-source
May be set to pass arbitrary options verbatim to dpkg-source(1) when building the
source package. Use with caution and at your own risk. To pass multiple options
to dpkg-source you must set this option multiple times (ie. using git config --add
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 DPKG_SOURCE_OPTS. Do not use this to set the dpkg-source(1) -Z or -z
options, they should instead be set using the deb-compressor and deb-compress-level
options respectively. This may be overridden on the command line with the
--dpkg-source=arg option, which likewise must be passed multiple times to set
multiple options.

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. gitpkg 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 gitpkg and no corresponding
orig tarball is found. Setting this option to 'false' will make gitpkg 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 CREATE_FAKE_ORIG.

gitpkg.force-overwrite-orig
This option controls the behaviour of gitpkg 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 gitpkg 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
gitpkg 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
FORCE_OVERWRITE_ORIG.

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 gitpkg exits if all prior
operations completed successfully. Default is unset. Available to hook scripts as
KEEP_UNPACKED_SOURCE. This may be overridden on the command line with the
--keep-unpacked-source=bool option (where 'no' or 'false' will not keep it, and any
other value, including nothing, will).

SCRIPT HOOKS

User defined scripts can be invoked from a number of points during the package build
process. They are sourced into gitpkg 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 gitpkg 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 git-config(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 must 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 git-config(1) rather than at a --global or --system
level.

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 they 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 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:

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

gitpkg.package-config-hook
This hook runs in the top level directory of the repo gitpkg was invoked in, prior
to any operations taking place, with all git-config(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 gitpkg
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 gitpkg was invoked in.

This hook is able to modify the gitpkg 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 gitpkg.

Its operation is different from the admin-config-hook in only one respect, the path
to this hook must 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 gitpkg was
requested to export. The file must exist in that version at the path given.

Available to hook scripts as PACKAGE_CONFIG_HOOK.

gitpkg.admin-config-hook
This hook is run after the package-config-hook 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 package-config-hook, with site specific configuration.
This is a policy control, not a security one. Security was all over when you let
the package-config-hook 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 gitpkg configuration and
set environment options that will be visible to later hooks. Available to hook
scripts as ADMIN_CONFIG_HOOK. This may be overridden on the command line with the
--admin-config-hook=path option.

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 gitpkg.

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 PRE_EXPORT_HOOK.

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 tree-ish, and
immediately prior to the PREBUILD_TARGET being invoked (if provided). It cannot
alter any configuration options, only act upon them or terminate gitpkg. If this
hook terminates gitpkg, the exported source directory will be left on the system
for the user to inspect. Subsequent invocations of gitpkg for the same release
version will overwrite it though. Available to hook scripts as DEB_EXPORT_HOOK.

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 tree-ish, and
prior to it being compressed into a tarball. It cannot alter any configuration
options, only act upon them or terminate gitpkg. If this hook terminates gitpkg,
the exported source directory will be left on the system for the user to inspect.
Subsequent invocations of gitpkg for the same release version will overwrite it
though.

This hook is only 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 force-overwrite-orig 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
deb-export-hook, and it may in fact be run in parallel with it at some point in the
future. They both will be entered after pre-export-hook returns, and exit-hook
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 ORIG_EXPORT_HOOK.

gitpkg.exit-hook
This hook runs in the directory where the package .dsc was deposited by
dpkg-source(1), after all internal gitpkg operations have successfully completed.
It's too late to alter any configuration options, or even to terminate gitpkg
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 EXIT_HOOK.
This may be overridden on the command line with the --exit-hook=path option.

Hook Environment
The following variables are made available for hook scripts, in addition to those already
listed as shadowing a git-config 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.

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

Available in API version 0.1
These variables have been available to hooks since gitpkg version 0.13

GITPKG_TREEISH
The user-passed debian 'branch' tree-ish that gitpkg was invoked to export.

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.

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

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.

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
DEB_VERSION.

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.

DEB_DSC
The full filename of the package .dsc that will be or has been created.

DEB_PACKAGE
The directory name of the debianised source tree to pass to dpkg-source(1).

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 git-config options is one of them. That's mostly what this one is for right
now. See the repo-config-helper documented below. Be careful if you do use it for
much else.

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

GITPKG_AOPTS
An associative array containing the command line options not parsed by gitpkg 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:

$ 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'

GITPKG_IOPTS
An indexed array containing the command line options not parsed by gitpkg 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:

$ 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'

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

Available in API version 0.3
A range of new support functions were added to repo-config-helper in gitpkg version 0.30

- require_bash_version()
- trim_array()

- have_commandline_option()
- have_any_of_these_commandline_options()

- extract_values_for()
- extract_value_for()
- extract_bool_for()

- get_option_values()
- get_option_value()
- get_bool_value()

These are described in more detail in the Hook Library Helpers section below.

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

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

$ git config gitpkg.exit-hook /usr/share/gitpkg/hooks/cowpoke-exit-hook

Additional git-config(1) configuration options:

gitpkg-cowpoke-exit-hook.ask-first
If 'true' and no cowpoke-specific command line option was passed, then prompt for
confirmation before calling cowpoke. 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.

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

You can use --cowpoke= (or equivalently, either --cowpoke or --no-cowpoke) to
override and clear all configured .options without needing to pass some arbitrary
new one. This will not override any other --cowpoke=arg 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.

gitpkg-cowpoke-exit-hook.arch
The default Debian architecture(s) to build for. Setting this option to <arch> is
equivalent to using --arch=<arch> in .options above, except using --arch on the
command line will only override any architectures set with this option, and
--cowpoke=--arch=<arch> will not override architectures set with this option. To
build for multiple architectures set this (or use --arch 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 cowpoke.conf, which in turn will default to what
dpkg-architecture(1) returns for DEB_BUILD_ARCH on the machine that is running
gitpkg.

gitpkg-cowpoke-exit-hook.dist
The default Debian distribution(s) to build for. Setting this option to <dist> is
equivalent to using --dist=<dist> in .options above, except using --dist on the
command line will only override any distributions set with this option, and
--cowpoke=--dist=<dist> will not override distributions set with this option. To
build for multiple distributions set this (or use --dist 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 cowpoke.conf, 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 cowpoke(1) description of its --dist option for details of that.

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

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

gitpkg-cowpoke-exit-hook.source-changes
If set to 'true', 'yes', 'signed', or set without a value (or to an empty string),
then it is equivalent to adding the cowpoke(1) option --sign-source-changes to
.options above, except it is independent of the options that would be overridden
by --cowpoke on the command line. The value signed has no additional special
effect for this hook, it is supported for equivalence with the values accepted for
.source-changes in the dpkg-buildpackage-exit-hook.

If set to 'false' or 'no', it is the equivalent of adding the cowpoke(1) option
--no-sign-source-changes.

The default if this option is not set at all is defer to SIGN_SOURCE_CHANGES in
the cowpoke.conf, or if it is not set to the pbuilder(8) configuration
SOURCE_ONLY_CHANGES setting.

All other values passed with this option are an error.

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

gitpkg-cowpoke-exit-hook.sign-key
May be set to the fingerprint of the key to sign packages with. This will
override the SIGN_KEYID 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 cowpoke.conf instead, but for
individual builds you can override it on the command line with the --sign=keyid
option.

The --no-sign option will cancel the use of any keyid that was set with .sign-key
in the git config, or by a previous command-line option, but this just means
gitpkg will not pass a keyid to cowpoke, 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 SIGN_KEYID that is set in cowpoke.conf you can
instead use --sign= (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.

gitpkg-cowpoke-exit-hook.upload-to
The dput(1) HOSTNAME to upload packages to. This will override the UPLOAD_QUEUE
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 cowpoke.conf instead, but for individual builds you can override the
upload queue on the command line with the --upload=queue option.

The --no-upload option will cancel the use of any upload queue that was set with
.upload-to in the git config, or by a previous command-line option, but this just
means gitpkg will not pass an upload queue to cowpoke, 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 UPLOAD_QUEUE that is set in cowpoke.conf
you can instead use --upload= (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.

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 gitpkg(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 --return[=path] option. If no path is
specified, the (cowpoke) default is the current directory.

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

dpkg-buildpackage-exit-hook
A simple exit hook to build binary packages locally with dpkg-buildpackage(1). To
enable it:

$ git config gitpkg.exit-hook /usr/share/gitpkg/hooks/dpkg-buildpackage-exit-hook

Additional git-config(1) configuration options:

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 dpkg-buildpackage. 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
dpkg-buildpackage(1) and so will skip this confirmation nagging.

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

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

You can use --dpkg-bp= (or equivalently, either --dpkg-bp or --no-dpkg-bp) to
override and clear all configured .options without needing to pass some arbitrary
new one. This will not override any other --dpkg-bp=arg 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.

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

If set to the special value 'signed' then the <package>_source.changes file, and
any .dsc or .buildinfo files referenced by it, will be signed regardless of any
-uc, -us, -ui options being used to suppress signing of the files created by
dpkg-buildpackage. This makes it possible to do a full binary build, creating
source and .deb 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 'signed' and --dpkg-bp=-uc --dpkg-bp=-us were passed. i.e. Only
the <package>_source.changes 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 'false' or 'no', no
<package>_source.changes file will be created by this hook and the behaviour is
simply what would be expected from dpkg-buildpackage(1) with any otherwise
configured options passed to it.

All other values passed with this option are an error.

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) dpkg-buildpackage(1) will be used when signing binary changes
files, with the defaults for debsign(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 DEB_SIGN_KEYID from
the environment (if it is set with no other overriding configuration), when
calling debsign, as it would otherwise ignore that configuration option from
dpkg-buildpackage. The usual debsign default is instead DEBSIGN_KEYID and set in
the devscripts.conf file.

You can override the signing key on the command line with the --sign=keyid option.
The --no-sign option will cancel the use of any keyid that was set with .sign-key
in the git config, or by a previous command-line option, but this just means
gitpkg will not pass a keyid to dpkg-buildpackage(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 --dpkg-bp=-uc --dpkg-bp=-us to
explicitly disable signing.

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 --build-log[=bool-value]
or --no-build-log option.

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:

$ git config gitpkg.pre-export-hook /usr/share/gitpkg/hooks/pristine-tar-pre-export-hook

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

quilt-patches-deb-export-hook
This hook reads a list of revision ranges suitable for git-format-patch(1) from the
file debian/source/git-patches, one per line, and exports them to the debian/patches
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 dpkg-source.

To enable it:

$ git config gitpkg.deb-export-hook /usr/share/gitpkg/hooks/quilt-patches-deb-export-hook

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

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

upstream/$UPSTREAM_REF..patches/$DEB_REF

debcherry-deb-export-hook
This hook invokes git-debcherry(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:

$ git config gitpkg.deb-export-hook /usr/share/gitpkg/hooks/debcherry-deb-export-hook

In order to use this hook, a ${DEB_ORIG}.commit 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 branch and origbranch to gitpkg, or if you use the pristine-tar-pre-export-hook,
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 /usr/share/doc/gitpkg/examples/README.debcherry-export 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.

Hook Library Helpers
These are additional shell code snippet files which are also found in /usr/share/
gitpkg/hooks, 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.

repo-config-helper
This file provides functions for querying configuration options which may be set in
the project git-config, or overridden by command line arguments.

repo_config()
Provides a simple wrapper around `git config`, 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 git-config(1)
options of their own to query.

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

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

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.

have_commandline_option()
A Simple true or false test of whether some --option or its counterpart
--no-option were passed on the command line, which evaluates to false if neither
of them were.

have_any_of_these_commandline_options()
Convenience function to call have_commandline_option for multiple options,
returning true if any of them were passed, or false if none of them were.

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

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

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.

extract_bool_for()
Like extract_value_for(), but intended for options where all values are expected
to be either true or false.

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.

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.

get_bool_value()
Like get_option_value() except all values set are either true or false.

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

INTERACTIVIY

       If you intend to call gitpkg 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 gitpkg
       directly.  For details, see the  gitpkg.force-overwrite-orig  and  gitpkg.create-fake-orig
       config  options  above.   You  should set both explicitly to the behaviour that you desire
       from them if gitpkg should never become interactive.

WORKFLOW

       Though gitpkg 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 ...

AUTHOR

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

                                        September 29, 2023                              GITPKG(1)