/usr/share/doc/git-dpm/index.html

<HTML><HEAD><TITLE>git-dpm: debian packages in git manager</TITLE>
<STYLE>
<!--
html { color: #000; background: #fefefe; font-family: serif; margin: 1em; border: 0; padding: 0; line-height: 120%; }
body { margin: 0; border: 0; padding: 0; }
h1, h2, h3 { text-align: left; font-family: sans-serif; background-color: #f0f0ff; color: #3c3c3c; border: #a7a7a7 1px solid;  padding: 10px;}
h1 { text-align: center; font-size: 180%; line-height: 150%; }
h2 { font-size: 150% }
h3 { font-size: 100% }
ul { list-style-type: square; }
img { border: 0pt; }
/-->
</STYLE>
</HEAD>
<BODY>
<H1>git-dpm: debian packages in git manager</H1>
<H2>Contents</H2>
<UL>
<LI><A href="#shortintro">Short Introduction</A></LI>
<LI><A href="#get">Get it</A></LI>
<LI><A href="#docs">Documentation and examples</A></LI>
<LI><A href="#mailinglist">Mailing lists</A></LI>
</UL>
<H2><A name="shortintro">Short Introduction</H2>
<IMG src="image-full.png" title="example history of a git-dpm project">
<P>
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.
</P>
<P>The red commits are the commits in the upstream branch.
That matches what is in your <tt>.orig.tar.(gz/bz2)</tt> file.
</P>
<P>
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:
<BR>
<IMG src="image-patches.png" title="only upstream and patches">
</P>
<P>
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.
</P>
<P>
Now look at the first picture again: The blue commits are the debian branch,
which in this example is <tt>master</tt>.
The only changes done in this branch in a git-dpm work-flow are changes to
the <tt>debian/</tt> directory (with some exceptions, see the manpage), while
all changes to the upstream sources are done in the patched branch.
</P>
After you have changed the patches, you call <tt>git-dpm update-patches</tt>,
which will update the <tt>debian/patches/</tt> directory in your debian branch
and update the upstream files in the debian branch, so you can just call
<tt>dpkg-buildpackage</tt> 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.
</P>
<P>But how to you manage such a setup with git-dpm?
Assume you have cloned a git-dpm managed branch:
</P>
<IMG src="image-cloned.png" title="image of beginning repository after clone">
<P>
First you call <tt>git-dpm prepare</tt> to check/get the proper .orig.tar file
and mark the upstream branch:
</P>
<IMG src="image-prepared.png" title="image after git-dpm prepare">
<P>
If you want to change something of the source, you call <tt>git-dpm checkout-patched</tt>:
</P>
<IMG src="image-checkout.png" title="image after git-dpm checkout-patched">
<P>
You simply do your modifications and <tt>git commit</tt> them:
</P
<IMG src="image-commit.png" title="image after git commit">
<P>
Now you call <tt>git-dpm update-patches</tt> to record those changes in your debian branch:
</P>
<IMG src="image-updated.png" title="image after git-dpm update-patches">
<P>
Now you build it and if everything is OK, you can push it, though you might want to <tt>git-dpm tag</tt> it:
</P>
<IMG src="image-tag.png" title="image after git-dpm tag">
<P>
Next consider there is a new upstream version.
</P>
<P>
First you need to update the upstream branch
(<tt>git-dpm import-new-upstream</tt> will do this and the next step for you):
</P>
<IMG src="image-newupstream.png" title="image with new upstream">
<P>
Then record this new upstream with <tt>git-dpm new-upstream</tt>:
</P>
<IMG src="image-upstreamrecorded.png" title="image with new upstream recorded">
<P>
Then you rebase the patches on top of it. (<tt>git-dpm rebase-patched</tt> will
help you with this, or give <tt>--rebase</tt> to the <tt>new-upstream</tt> or <tt>import-new-upstream</tt> calls):
</P>
<IMG src="image-rebased.png" title="image with new upstream recorded">
<P>
After checking those patches still look good, record them with <tt>update-patches</tt>
</P>
<IMG src="image-rebaserecorded.png" title="image with new upstream recorded">
<P>
Now you can push it, or tag and push it:
</P>
<IMG src="image-newtag.png" title="tags for the new upstream added">
<P>
But of course in reality, the development of the changes will not be that linear.
</P>
<P>
Let's assume you found patch <tt>b</tt> is incomplete/improvable.
Then you again call <tt>git-dpm checkout-patched</tt>:
</P>
<IMG src="image-1.png" title="image with patched branch visible again">
<P>
Then you do your changes and call <tt>git commit --amend</tt>:
</P>
<IMG src="image-2.png" title="image with amended patched branch">
<P>
And record this change using <tt>git-dpm update-patches</tt>:
</P>
<IMG src="image-3.png" title="image with amended patched branch merged back">
<P>
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 <tt>git-dpm checkout-patched</tt>:
</P>
<IMG src="image-4.png" title="image with patched branch visible again">
<P>
Now you can either do a <tt>git rebase -i upstream</tt>, mark the first
commit to be edited and amend it. Or you add a new commit:
</P>
<IMG src="image-5.png" title="image with patched branch visible again">
<P>
And then use <tt>git rebase -i</tt> to squash the third into the first commit:
</P>
<IMG src="image-6.png" title="image with patched branch visible again">
<P>
And them run <tt>git-dpm update-patches</tt> again and possibly tag it:
</P>
<IMG src="image-full.png" title="the full image again">
<P>Note that a real example will usually have much more commits in the debian branch <tt>master</tt>.
(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).
<H2><A name="get">Get git-dpm</A></H2>
<P>
Until there are debian packages, you can get it with:
<BR>
<TT>git clone git://git.debian.org/git/git-dpm/git-dpm.git</TT><BR>
You just need the <tt>git-dpm.sh</tt> and you want want to look at the manpage <tt>git-dpm.1</tt> and the <tt>examples.html</tt>.
You can ignore the rest of the files.
</P>
<H2><A name="docs">Documentation and examples</A></H2>
<P>
There is the <A href="manpage.html">manpage</A>(<A href="manpage.pdf">PDF</A>).
And there are some <A href="examples.html">examples</A>.
Also take a look in the <A href="http://wiki.debian.org/PackagingWithGit/GitDpm">Debian Wiki pages about git-dpm</A>.
</P>
<H2><A name="mailinglist">Mailing lists</A></H2>
<P>
There are two mailing lists:
<UL>
<LI><A href="http://lists.alioth.debian.org/mailman/listinfo/git-dpm-devel">git-dpm-devel</A> for discussing development/enhancements</LI>
<LI><A href="http://lists.alioth.debian.org/mailman/listinfo/git-dpm-user">git-dpm-user</A> for user questions</LI>
</UL>
</P>
</BODY>
</HTML>
git-dpm 0.8.0-1 / usr / share / doc / git-dpm / index.html
