git-dpm: debian packages in git manager

Contents

Short Introduction

[image of an example history of a git-dpm project]

The above image shows an idealized example of a history how git-dpm produces it. Each filled circle is a commit. The colored lines mean the commit to the left is an parent of the commit to the right.

The red commits are the commits in the upstream branch. That matches what is in your .orig.tar.(gz/bz2) file.

Then there are patches to the upstream sources. Those are managed as a normal branch you plan to submit upstream is: Rebased to every new upstream release, commits amended or interactively rebased to keep it in a proper shape to maximize the chances it is acceptable by upstream or useful to others:
[image of only upstream and patches]

If you look at only those patches, you see the problem git has with the history of such branches: Every rebase loses the previous state. Old history can be referenced by tags, but if only tagging meaningful states loses intermediate ones. Also pulling and pushing those around is a constant nightmare.

Now look at the first picture again: The blue commits are the debian branch, which in this example is master. The only changes done in this branch in a git-dpm work-flow are changes to the debian/ directory (with some exceptions, see the manpage), while all changes to the upstream sources are done in the patched branch.

After you have changed the patches, you call git-dpm update-patches, which will update the debian/patches/ directory in your debian branch and update the upstream files in the debian branch, so you can just call dpkg-buildpackage in there. The respective patched branch is a parent of the commit in the debian branch, so its history is preserved and by pushing and pulling the debian branch around, those commits are, too, so every team member has the full history and nothing is private to your repository.

But how to you manage such a setup with git-dpm? Assume you have cloned a git-dpm managed branch:

[image of beginning repository after clone]

First you call git-dpm prepare to check/get the proper .orig.tar file and mark the upstream branch:

[image after git-dpm prepare]

If you want to change something of the source, you call git-dpm checkout-patched:

[image after git-dpm checkout-patched]

You simply do your modifications and git commit them:

[image after git commit]

Now you call git-dpm update-patches to record those changes in your debian branch:

[image after git-dpm update-patches]

Now you build it and if everything is OK, you can push it, though you might want to git-dpm tag it:

[image after git-dpm tag]

Next consider there is a new upstream version.

First you need to update the upstream branch (git-dpm import-new-upstream will do this and the next step for you):

[image with new upstream]

Then record this new upstream with git-dpm new-upstream:

[image with new upstream recorded]

Then you rebase the patches on top of it. (git-dpm rebase-patched will help you with this, or give --rebase to the new-upstream or import-new-upstream calls):

[image with new upstream recorded]

After checking those patches still look good, record them with update-patches

[image with new upstream recorded]

Now you can push it, or tag and push it:

[image with tags for the new upstream added]

But of course in reality, the development of the changes will not be that linear.

Let's assume you found patch b is incomplete/improvable. Then you again call git-dpm checkout-patched:

[image with patched branch visible again]

Then you do your changes and call git commit --amend:

[image with amended patched branch]

And record this change using git-dpm update-patches:

[image with amended patched branch merged back]

If that improvement does not justify a new upload, you can just push it. Now assume another problem is found this time in the first modification. So you (or some team member -- remember this state can be pushed and pulled without problems) again call git-dpm checkout-patched:

[image with patched branch visible again]

Now you can either do a git rebase -i upstream, mark the first commit to be edited and amend it. Or you add a new commit:

[image with patched branch visible again]

And then use git rebase -i to squash the third into the first commit:

[image with patched branch visible again]

And them run git-dpm update-patches again and possibly tag it:

[the full image again]

Note that a real example will usually have much more commits in the debian branch master. (While one can amend all changes to get an image exactly as this, there will usually be other changes to the files in debian/ necessary, which usually will be put in their own commits).

Get git-dpm

Until there are debian packages, you can get it with:
git clone git://git.debian.org/git/git-dpm/git-dpm.git
You just need the git-dpm.sh and you want want to look at the manpage git-dpm.1 and the examples.html. You can ignore the rest of the files.

Documentation and examples

There is the manpage(PDF). And there are some examples. Also take a look in the Debian Wiki pages about git-dpm.

Mailing lists

There are two mailing lists: