Building from source
--------------------
Install “git-buildpackage” and “devscripts” then run the following:

  debcheckout --git-track '*' util-linux
  cd util-linux
  git branch -l | grep debian
  git checkout debian-[...]
  git-buildpackage

We recommend you use pbuilder to make sure you build in a clean environment:

  git-buildpackage --git-pbuilder

Patch handling
--------------
The official form of modifications to the upstream source are quilt patches in
debian/patches/, like most Debian packages do. You are welcome to use quilt to
add or modify patches, but you might prefer using a git commit based approach.
gbp-pq provides that by synthesizing a "patch-queue/<branch>" local branch
which represents each quilt patch as git commit. You create this with

  gbp-pq import --force

Then you are in the patch-queue branch and can git log, commit, cherry-pick
upstream commits, rebase, etc. there. After you are done, run

  gbp-pq export

which will put you back into the debian branch and update debian/patches/
(including series). You need to git add etc. new patches, add a changelog
and other packaging changes, and then debcommit as usual.

Rebasing patches to a new upstream version
------------------------------------------
gbp-pq's "rebase" command does not work very conveniently as it fails on merge
conflicts. First, ensure you are in the debian branch:

  git checkout debian-[...]  # in case you aren't already

Fetch new git history from upstream:

  git remote add kzak git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git
  git fetch kzak [upstream-version-tag]

Now, to import a new upstream micro-release into the existing branch,
ie. when updating from v2.24 to v2.24.2,
do:

  gbp-pq import --force
  gbp-pq switch   # switch back to debian branch from patch-queue branch
  git-import-orig --upstream-vcs-tag=v2.24.2 ../tarballs/util-linux-v2.24.2.tar.xz
  gbp-pq switch   # switch to patch-queue branch
  git rebase debian-2.24

Or, to create a new branch for a new upstream major.minor version,
ie, when updating from v2.24.2 to v2.25,
do:

  # create new branches
  git branch --no-track debian-2.25 debian-2.24
  git branch upstream-2.25 v2.25

  # update debian branch to be based on new upstream version
  git checkout debian-2.25
  git rebase --onto upstream-2.25 upstream-2.24

  # set up git-buildpackage to use new branches
  sed -i 's/debian-2.24/debian-2.25/' debian/gbp.conf
  sed -i 's/upstream-2.24/upstream-2.25/' debian/gbp.conf
  git commit -m "Update branch names in debian/gbp.conf" debian/gbp.conf

  # import orig tarball
  git-import-orig --upstream-vcs-tag=v2.25 ../tarballs/util-linux-2.25.tar.xz

  # rebase patch queue on top of new upstream version
  git checkout debian-2.24
  gbp-pq import --force
  git branch -m patch-queue/debian-2.24 patch-queue/debian-2.25
  git rebase -i --onto debian-2.25 debian-2.24

Now resolve all the conflicts, skip obsolete patches, etc. When you are done, run

  gbp-pq export

Note that our debian/gbp.conf disables patch numbers.

Also, don't forget to commit your newly generated patches!

  git commit -v debian/patches

Cherry-picking upstream patches
-------------------------------
You can add the util-linux upstream branch as an additional remote to the Debian
packaging branch. Call it "kzak" or similar to avoid confusing it
with the already existing "upstream" branch from git-buildpackage:

  git remote add kzak git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git
  git fetch kzak -n

Now you can look at the upstream log and cherry-pick patches into the
patch-queue branch:

  gbp-pq import --force
  git log kzak/master
  git cherry-pick 123DEADBEEF
