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:
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:
First you call git-dpm prepare to check/get the proper .orig.tar file and mark the upstream branch:
If you want to change something of the source, you call git-dpm checkout-patched:
You simply do your modifications and git commit them:
Now you call git-dpm update-patches to record those changes in your debian branch:
Now you build it and if everything is OK, you can push it, though you might want to git-dpm tag it:
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):
Then record this new upstream with git-dpm new-upstream:
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):
After checking those patches still look good, record them with update-patches
Now you can push it, or tag and push it:
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:
Then you do your changes and call git commit --amend:
And record this change using git-dpm update-patches:
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:
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:
And then use git rebase -i to squash the third into the first commit:
And them run git-dpm update-patches again and possibly tag it:
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).
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.
There is the manpage(PDF). And there are some examples. Also take a look in the Debian Wiki pages about git-dpm.
There are two mailing lists: