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.
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. Default is
’clean’. This operation may be disabled by explicitly setting
it to an empty string. Available to hook scripts as
PREBUILD_TARGET.
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.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.
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.
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.
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.
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.1
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.
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.
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’ prompt for confirmation before calling cowpoke.
Default is to just go ahead and do it.
gitpkg-cowpoke-exit-hook.options
May include any other options to pass verbatim to cowpoke.
To pass multiple options, set this multiple times, once for
each 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’ prompt for confirmation before calling dpkg-
buildpackage. Default is to just do it.
gitpkg-dpkg-buildpackage-exit-hook.options
May include any other options to pass verbatim to dpkg-
buildpackage. To pass multiple options, set this multiple
times, once for each option.
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.
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.
Hook Library Helpers
These are even more trivial snippets, for operations which may be
shared by several scripts. Also found in /usr/share/gitpkg/hooks.
Usually these would be sourced by other scripts rather than being
hooked to directly.
repo-config-helper
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 options of their own to
query.
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 ...
SEE ALSO
git-debimport(1), git(1), git-archive(1), git-config(1),
gitattributes(5), dpkg-source(1), cowpoke(1).
AUTHOR
gitpkg was written by Ron <ron@debian.org>.
September 21, 2007