git-dpm examples

Contents

• Adding a new patch
• Switching to a new upstream version
• Create a new project
• Switching an existing project to git-dpm

Adding a new patch

First get the master branch:

git clone git://git.debian.org/users/brlink/xwit.git

Then create upstream branch and see if the .orig.tar is ready (if you have pristine-tar installed, it will recreate the file for you):

git-dpm prepare

Create the patched branch and check it out:

git-dpm checkout-patched

Do some changes, apply some patches, commit them. (Remember the commit message will be the patch description. So use a proper one. The first line will be the Subject and part of the patch filename, so make it precise).

vim xwit.c
git commit -a

If your modification fixes a previous change (and that is not the last commit, otherwise you could have used --amend to commit), 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

(Note how update-patched put you back into the master branch and deleted the patched branch, so it will not be outdated in case you pull the master branch again later).

Perhaps change something else in debian/:

vim debian/control
dch
git commit -a

Then push the whole thing back (will not work in this example, you would have had to checkout over git+ssh:// and have permissions to that repository...)

git push

Switching to a new upstream version

First get a new .orig.tar file. In this example it will be stuff_newversion.orig.tar.gz.

Prepare a new upstream branch. There are many ways to do this, depending how you want your repository organized. Either

• Just import the new upstream tar file:

  git-dpm import-new-upstream --rebase ../stuff_newversion.orig.tar.gz
  

  You can also use --detached to not add the old upstream branch as parent to your new upstream branch, or -p to add commits as additional branches (like the corresponding upstream commit of this release, if you already have it in some other branch of your commit).
• Create the new upstream branch yourself, for example based on upstream's git branch you have fetched. Note that it is your responsibility that this branch looks sufficiently equal to the contents of the upstream tar ball that after debian/rules clean dpkg-buildpackage will not notice any difference. (I.e. you might need to add some files from the upstream tar ball in many cases). Then tell git-dpm the upstream branch is in shape for the new file with:

  git-dpm new-upstream --rebase ../stuff_newversion.orig.tar.gz
  

Note that the --rebase also told git-dpm to rebase your patched branch to the new upstream branch. This might cause some conflicts which you have to resolve as with usual git rebases, i.e. continue

vim conflicting files
git add resolved files
git rebase --continue

until the rebase is done.

After rebase is run (with some luck even in the first try), and you made sure it still looks good, merge them into your debian branch again.

git-dpm update-patches

And record the new upstream version in the Debian changelog:

dch -v newversion-1 "new upstream version"
git commit --amend -a

Do other debian/ changes, if there is anything:

vim debian/control
dch "Bump Standards-Version (no changes needed)"
git commit -a

You might want to use pristine tar to store your new tar, too:

pristine-tar commit ../stuff_newversion.orig.tar.gz upstream

Then push the whole thing back:

git push

Create 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 tar ball 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*"

Now 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 because 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

Switching an existing project to git-dpm

In this example about porting an existing repository to git-dpm, let's use some realistic example: xorg-server.

First check it out:

git clone git://git.debian.org/pkg-xorg/xserver/xorg-server.git
cd xorg-server

To make this example reproducible, let's switch to an specific point, namely version 2:1.7.3.902-1:

git checkout -b master 6fad5b26289e6b13aebfd9e684942743d2384439

First, let's also get the upstream tar ball (That might need snapshot.debian.net or something like that instead in the future).

(cd .. && wget http://ftp.debian.org/debian/pool/main/x/xorg-server/xorg-server_1.7.3.902.orig.tar.gz)

First we need an upstream branch with contents similar enough to the upstream tar ball. The easiest way it to just use that:

git-dpm import-tar -p d1320f4f2908fd3a248a79314bd78f76b03c71c5 ../xorg-server_1.7.3.902.orig.tar.gz
git checkout -b upstream

(The -p adds the appropriate point in remotes/origin/upstream-unstable history as parent to this one). Note the many files added here and also some files deleted.

Then we can just try (if that succeeds, we could be finished):

git-dpm init ../xorg-server_1.7.3.902.orig.tar.gz upstream

This gives a long list of files that are added or modified in our current debian branch master, so we have to investigate. (It suggests --patched-applied, but it's easy to say the patches in debian/patches/ are not yet applied, so this will not help).

First remember that there were also files deleted when importing the .tar.gz. Some seem to be only in the repository as they are also in upstream's repository. Let's try to delete them (Of course that means one has later to verify they are really not needed in the build or even the final packages):

git checkout master
git rm -f hw/xquartz/GL/glcontextmodes.c hw/xquartz/GL/glcontextmodes.h hw/xfree86/doc/README.modes config/dbus-api doc/c-extensions hw/kdrive/Xkdrive.man hw/kdrive/ephyr/ephyrhostproxy.c hw/kdrive/ephyr/ephyrhostproxy.h hw/kdrive/ephyr/ephyrproxyext.c hw/kdrive/ephyr/ephyrproxyext.h hw/kdrive/fbdev/Xfbdev.man 'hw/xquartz/bundle/Resources/*.lproj/locversion.plist' 'hw/xquartz/bundle/Resources/*.lproj/main.nib/designable.nib' hw/xwin/xlaunch/Makefile hw/xwin/xlaunch/config.h
git commit -m "remove unused files not in the upstream tar.gz"

Trying again to see what is left:

git-dpm init ../xorg-server_1.7.3.902.orig.tar.gz upstream

Looking with gitk for commits touching those paths, shows us that one file is from some cherry-picked commit directly applied in the debian branch, so tell git-dpm about it:

git checkout upstream
git checkout -b pre
git cherry-pick cd192850fc73aa43432e1068503699ebdaa2cb83
git checkout master
git-dpm init ../xorg-server_1.7.3.902.orig.tar.gz upstream pre

Only one file left. Looking at this shows it is empty and no longer referenced anywhere in the source, so some other artefact.

git checkout master
git rm -f hw/xfree86/osandcommon.c
git commit -m "remove empty files left in the debian branch"

Trying again:

git-dpm init ../xorg-server_1.7.3.902.orig.tar.gz upstream pre

show that is worked this time. So get rid of the temporary branch:

git branch -d pre