NAME
git-dpm - debian packages in git manager
SYNOPSIS
git-dpm --help
git-dpm [ options ] command [ per-command-options and -arguments ]
DESCRIPTION
Git-dpm is a tool to handle a debian source package in a git
repository.
Each project contains three branches, a debian branch
(master/whatever), a patched branch (patched/patched-whaterver) and an
upstream branch (upstream/upstream-whatever) and git-dpm helps you
store the information in there so you have your changes exportable as
quilt series.
SHORT EXPLANATION OF THE BRANCHES
the upstream branch (upstream|upstream-whatever)
This branch contains the upstream sources. It contents need to
be equal enough to the contents in your upstream tarball.
the patched branch (patched|patched-whaterver)
This branch contains your patches to the upstream source. Every
commit will be stored as a single patch in the resulting
package.
To help git generate a linear patch series, this should ideal be
a linear chain of commits, whose description are helpful for
other people.
As this branch is regulary rebased, you should not publish it.
the debian branch (master|whaterver)
This is the primary branch.
This branch contains the debian/ directory and has the patched
branch merged in.
Every change not in debian/, .git* or deleting files must be
done in the patched branch.
EXAMPLES
Let’s start with some examples:
Checking out a project
First get the master branch:
git clone URL
Then create upstream branch and see if the .orig.tar is ready:
git-dpm prepare
Create the patched branch and check it out:
git-dpm checkout-patched
Do some changes, apply some patches, commit them..
...
git commit
If your modification fixes a previous change (and that is not
the last commit, otherwise you could have used --amend), you
might want to squash those two commits into one, so use:
git rebase -i upstream
Merge your changes into the debian branch and create patches:
git-dpm update-patches
dch -i
git commit --amend -a
Perhaps change something with the debian package:
...
git commit -a
Then push the whole thing back:
git push
Switching to a new upstream version
Get a new .orig.tar file. Either upgrade your upstream branch
to the contents of that file and call git-dpm new-upstream
../new-stuff.orig.tar.gz or tell git-dpm to import and record
it:
git-dpm import-new-upstream --rebase ../new-stuff.orig.tar.gz
This will rebase the patched branch to the new upstream branch,
perhaps you will need to resolve some conflicts:
vim ...
git add resolved files
git rebase --continue
After rebase is run (with some luck even in the first try):
git-dpm update-patches
Record it in debian/changes:
dch -v newupstream-1 "new upstream version"
git commit --amend -a
Do other debian/ changes:
...
git commit -a
Then push the whole thing back:
git push
Creating a new project
Create an upstream (or upstream-whatever) branch containing the
contents of your orig.tar file:
tar -xvf example_0.orig.tar.gz
cd example-0
git init
git add .
git commit -m "import example_0.orig.tar.gz"
git checkout -b upstream-unstable
You might want to use pristine tar to store your tar:
pristine-tar commit ../example_0.orig.tar.gz upstream-unstable
Then let git-dpm know what tarball your upstream branch belongs
to:
git-dpm init ../example_0.orig.tar.gz
Do the rest of the packaging:
vim debian/control debian/rules
dch --create --package example -v 0-1
git add debian/control debian/rules debian/changelog
git commit -m "initial packaging"
Then add some patches:
git-dpm checkout-patched
vim ...
git commit -a
git-dpm update-patches
dch "fix ... (Closes: num)"
git commit --amend -a
Then build your package:
git-dpm status &&
dpkg-buildpackage -rfakeroot -us -uc -I".git*"
Not take a look what happened, perhaps you want to add some
files to .gitignore (in the unstable branch), or remove some
files from the unstable branch becaus your clean rule removes
them.
Continue the last few steps until the package is finished. Then
push your package:
git-dpm tag
git push --tags target unstable:unstable
pristine-tar:pristine-tar
GLOBAL OPTIONS
--debug
Give verbose output what git-dpm is doing. Mostly only useful
for debugging or when preparing an bug report.
COMMANDS
init [options] tarfile [upstream-commit [preapplied-commit [patched-
commit]]]
Create a new project.
The first argument is an upstream tarball.
You also need to have the contents of those (or similar enough
so dpkg-source will not know the difference) as some branch or
commit in your git repository. This will be stored in the
upstream branch (called upstream or upstream-whatever). If the
second argument is non-existing or empty, that branch must
already exist, otherwise that branch will be initialized with
what that second argument. (It’s your responsiblity that the
contents match. git-dpm does not know what your clean rule does,
so cannot check (and does not even try to warn yet)).
You can already have an debian branch (called master or
whatever). If it does not exist, it will exist afterwards.
Otherwise it can contain a debian/patches/series file, which
git-dpm will import.
The third argument can be a descendant of your upstream branch,
that contains the changes of your debian branch before any
patches are applied (Most people prefer to have none and lintian
warns, but if you have some, commit/cherry pick them in a new
branch/detached head on top of your upstream branch and name
them here). Without --patches-applied, your debian branch may
not have any upstream changes compared to this commit (or if it
is not given, the upstream branch).
If there is no forth argument, git-dpm will apply possible
patches in your debian branch on top of the third argument or
upstream. You can also do so yourself and give that as forth
argument.
The contents of this commit/branch given in the forth commit or
created by applying patches on top of the third/your upstream
branch is then merged into your debian branch and remembered as
patched branch.
Options:
--patches-applied
Denote the debian branch already has the patches applied.
Without this git-dpm will check there are no changes in
the debian branch outside patch management before
applying the patches but instead check there are no
differences after applying the patches.
--create-no-patches
Do not create/override debian/patches directory. You
will have to call update-patches yourself. Useful if you
are importing historical data and keep the original
patches in the debian branch.
--no-commit
Do not commit the new debian/.git-dpm file and possible
debian/patched changes, but only add them to working tree
and index.
prepare
Make sure upstream branch and upstream orig.tar ball are there
and up to date. (Best called after a clone or a pull).
status Check the status of the current project. Returns with non-zero
exit code if something to do is detected.
checkout-patched
Checkout the patched branch (patched|patched-whaterver) after
making sure it exists and is one recorded in the debian/.git-dpm
file.
If the patched branch references an old state (i.e. one that is
already ancestor of the current debian branch), it is changed to
the recorded current one.
Otherwise you can reset it to the last recorded state with the
--force option.
update-patches
After calling merge-patched-into-debian if necessary, update the
contents of debian/patches to the current state of the patched
branch.
Also record in debian/.git-dpm which state of the patched branch
the patches directory belongs to.
Options:
--redo Do something, even if it seems like there is nothing to
do.
--allow-revert
passed on to merge-patched-into-debian
--amend
passed on to merge-patched-into-debian
--keep-branch
do not remove an existing patched branch (usually that is
removed and can be recreated with checkout-patched to
avoid stale copies lurking around.
merge-patched-into-debian
Usually update-patches runs this for you if deemed necessary.
Replace the current contents of the debian branch
(master|whaterver) with the contents of the patched branch
(patched|patched-whaterver), except for everything under
debian/. Also files that are deleted in the debian branch keep
being deleted and files in the root directory starting with
".git" keep their contents from the debian branch, too.
The current state of the patched branch is recorded in
debian/.git-dpm and so is which upstream branch was recorded
patched branch is relative to (to easy future
merge-patched-into-debian operations).
Options:
--allow-revert
Usually reverting to an old state of the patched branch
is not allowed, to avoid mistakes (like having only
pulled the debian branch and forgot to run
checkout-patched). This option changes that so you can
for example drop the last patch in your stack.
--keep-branch
do not remove an existing patched branch (usually that is
removed and can be recreated with checkout-patched to
avoid stale copies lurking around).
--amend
Replace the last commit on your debian branch (as git
commit --amend would do). With the exception that every
parent that is an ancestor of or equal to the new patched
branch or the recorded patched branch is omitted. (That
is, you lose not only the commit on the debian branch,
but also a previous state of the patched branch if your
last commit also merged the patched branch).
import-new-upstream [options] .orig.tar
Import the contents of the given tarfile (as with import-tar)
and record this branch (as with new-upstream).
This is roughly equivalent to:
git-dpm import-tar -p upstream filename
git checkout -b upstream
git-dpm new-upstream filename
--detached
Don’t make the new upstream branch an ancestor of the old
upstream branch (unless you readd that with -p).
-p commit-id|--parent commit-id
Give import-tar additional parents of the new commit to
create.
For example if you track upstream’s git repository in
some branch, you can name that here to make it part of
the history of your debian branch.
--rebase-patched
After recording the new upstream branch, rebase the
patched branch to the new upstream branch.
import-tar [options] .tar-file
Create a new commit containing the contents of the given file.
The commit will not have any parents, unless you give -p
options.
-p commit-id|--parent commit-id
Add the given commit as parent. (Can be specified
multiple times).
new-upstream [--rebase-patched] .orig.tar [commit]
If you changed the upstream branch (upstream|upstream-whatever),
git-dpm needs to know which tarball this branch now corresponds
to and you have to rebase your patched branch
(patched|patched-whaterver) to the new upstream branch.
If there is a second argument, this command first replaces your
upstream branch with the specified commit.
Then the new upstream branch is recorded in your debian branch’s
debian/.git-dpm file.
If you specified --rebase-patched (or short --rebase),
git-dpm rebase-patched will be called to rebase your patched
branch on top of the new upstream branch.
After this (and if the branch then looks like what you want),
you still need to call git-dpm merge-patched-into-debian (or
directly git-dpm update-patches).
WARNING to avoid any misunderstandings: You have to change the
upstream branch before using this command. It’s your
responsibility to ensure the contents of the tarball match those
of the upstream branch.
rebase-patched
Try to rebase your current patched branch
(patched|patched-whaterver) to your current current upstream
branch (upstream|upstream-whatever).
If those branches do not yet exist as git branches, they are
(re)created from the information recorded in debian/.git-dpm
first.
This is only a convenience wrapper around git rebase that first
tries to determine what exactly is to rebase. If there are any
conflicts, git rebase will ask you to resolv them and tell
rebase to continue.
After this is finished (and if the branch then looks like what
you want), you still need merge-patched-into-debian (or directly
update-patches).
tag [ version ]
Add tags to the uptream, patched and debian branches. If no
version is given, it is taken from debian/changelog.
Options:
--refresh
Overwrite the tags if they are already there and differ
(except upstream).
--refresh-upstream
Overwrite the upstream if that is there and differs.
--allow-nonclean
Don’t error out if patches are not up to date. This is
only useful if you are importing historical data and want
to tag it.
apply-patch [ options... ] [ filename ]
Switch to the patched branch (assuming it is up to date, use
checkout-patched first to make sure or get an warning), and
apply the patch given as argument or from stdin.
--author author <email>
Override the author to be recorded.
--defaultauthor author <email>
If no author could be determined from the commit, use
this.
--date date
Date to record this patch originally be from if non
found.
--edit Start an editor before doing the commit (In case you are
too lazy to amend).
cherry-pick [ options... ] commit
Recreate the patched branch and cherry-pick the given commit.
Then merge that back into the debian branch and update the
debian/patches directory (i.e. mostly equivalent to
checkout-patched, git’s cherry-pick, and update-patches).
--merge-only
Only merge the patched branch back into the debian branch
but do not update the patches directory (You’ll need to
run update-patches later to get this done).
-e | --edit
Passed to git’s cherry-pick: edit the commit message
picked.
-s | --signoff
Passed to git’s cherry-pick: add a Signed-off-by header
-x Passed to git’s cherry-pick: add a line describing what
was picked
-m num | --mainline num
Passed to git’s cherry-pick: allow picking a merge by
specifign the parent to look at.
--repick
Don’t abort if the specified commit is already contained.
--allow-nonlinear
passed to merge-patched-into-debian and update-patches.
--keep-branch
do not remove the patched branch when it is no longer
needed.
--amend
passed to merge-patched-into-debian: amend the last
commit in the debian branch.
the debian/.git-dpm file
You should not need to know about the contents if this file except for
debuging git-dpm.
The file contains 8 lines, but future version may contain more.
The first line is hint what this file is about and ignored.
Then there are 4 git commit ids for the recorded states:
First the state of the patched branch when the patches in
debian/patches were last updated.
Then the state of the patched branch when it was last merged
into the debian branch.
Then the state upstream branch when the patched branch was last
merged.
Finally the upstream branch.
The following 3 lines are the filename, the sha1 checksum and the size
of the origtarball belonging to the recorded upstream branch.
BRANCHES
the upstream branch (upstream|upstream-whatever)
This branch contains the upstream sources. It contents need to
be equal enough to the contents in your upstream tarball.
Equal enough means that dpkg-source should see no difference
between your patched tree and and original tarball unpackaged,
the patched applied and debian/rules clean run. Usually it is
easiest to just store the verbatim contents of your orig tarball
here. Then you can also use it for pristine tar.
This branch may contain a debian/ subdirectory, which will
usually be just ignored.
You can either publish that branch or make it only implicitly
visible via the debian/.git-dpm file in the debian branch.
While it usually makes sense that newer upstream branches
contain older ones, this is not needed. You should be able to
switch from one created yourself or by some foreign-vcs
importing tool generated one to an native upstream branch or
vice versa without problems. Note that since the debian branch
has the patched branch as ancestor and the patched branch the
upstream branch, your upstream branches are part of the history
of your debian branch. Which has the advantage that you can
recreate the exact state of your branches from your history
directly (like git checkout -b oldstate
myoldtagorshaofdebianbranchcommit ; git-dpm prepare ; git
checkout unstable-oldstate) but the disadvantage that to remove
those histories from your repository you have to do some manual
work.
the patched branch (patched|patched-whaterver)
This branch contains your patches to the upstream source.
(which of course means it is based on your upstream branch).
Every commit will be stored as a single patch in the resulting
package.
To help git generate a linear patch series, this should ideal be
a linear chain of commits, whose description are helpful for
other people.
As this branch is regulary rebased, you should not publish it.
Instead you can recreate this branch using git-dpm
checkout-patched using the information stored in
debian/.git-dpm.
You are not allowed to change the contents of the debian/
subdirectory in this branch. Renaming files or deleting files
usuall causes unecesary large patches.
the debian branch (master|whaterver)
This is the primary branch.
This branch contains the debian/ directory and has the patched
branch merged in.
Every change not in debian/, .git* or deleting files must be
done in the patched branch.
COPYRIGHT
Copyright © 2009,2010 Bernhard R. Link
This is free software; see the source for copying conditions. There is
NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.
REPORTING BUGS AND ISSUES
You can report bugs or feature suggestions to git-dpm-
devel@lists.alioth.debian.org or tome. Please send questions to git-
dpm-user@lists.alioth.debian.org or to me at brlink@debian.org.