Man Linux: Main Page and Category List

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