/usr/share/doc/git-dpm/examples.html is in git-dpm 0.8.0-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 | <HTML><HEAD><TITLE>git-dpm examples</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; }
/-->
</STYLE>
</HEAD>
<BODY>
<H1>git-dpm examples</H1>
<H2>Contents</H2>
<UL>
<LI><A href="#update">Adding a new patch</A></LI>
<LI><A href="#newupstream">Switching to a new upstream version</A></LI>
<LI><A href="#createnew">Create a new project</A></LI>
<LI><A href="#createold">Switching an existing project to git-dpm</A></LI>
</UL>
<H2><A name="update">Adding a new patch</A></H2>
<p>
First get the master branch:
<pre class="commandline">
git clone git://git.debian.org/users/brlink/xwit.git
</pre>
</p>
<p>
Then create upstream branch and see if the .orig.tar is ready
(if you have <a href="http://packages.debian.org/pristine-tar">pristine-tar</a> installed,
it will recreate the file for you):
<pre class="commandline">
git-dpm prepare
</pre>
</p>
<p>
Create the patched branch and check it out:
<pre class="commandline">
git-dpm checkout-patched
</pre>
</p>
<p>
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).
<pre class="commandline">
vim xwit.c
git commit -a
</pre>
</p>
<p>
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:
<pre class="commandline">
git rebase -i upstream
</pre>
</p>
<p>
Merge your changes into the debian branch and create patches:
<pre class="commandline">
git-dpm update-patches
dch -i
git commit --amend -a
</pre>
(Note how <tt>update-patched</tt> 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).
</p>
<p>
Perhaps change something else in debian/:
<pre class="commandline">
vim debian/control
dch
git commit -a
</pre>
</p>
<p>
Then push the whole thing back (will not work in this example,
you would have had to checkout over <tt>git+ssh://</tt> and have
permissions to that repository...)
<pre class="commandline">
git push
</pre>
</p>
<H2><A name="newupstream">Switching to a new upstream version</A></H2>
<p>
First get a new .orig.tar file.
In this example it will be <tt>stuff_newversion.orig.tar.gz</tt>.
</p>
<p>
Prepare a new upstream branch.
There are many ways to do this, depending how you want your
repository organized. Either
<ul>
<li>Just import the new upstream tar file:
<pre class="commandline">
git-dpm import-new-upstream --rebase ../stuff_newversion.orig.tar.gz
</pre>
You can also use <tt>--detached</tt> to not add the old upstream branch
as parent to your new upstream branch, or <tt>-p</tt> 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).
<p>
<li>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 <tt>debian/rules clean</tt> 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:
<pre class="commandline">
git-dpm new-upstream --rebase ../stuff_newversion.orig.tar.gz
</pre>
</ul>
</p>
<p>
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
<pre class="commandline">
vim conflicting files
git add resolved files
git rebase --continue
</pre>
until the rebase is done.
</p>
<p>
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.
<pre class="commandline">
git-dpm update-patches
</pre>
</p>
<p>
And record the new upstream version in the Debian changelog:
<pre class="commandline">
dch -v newversion-1 "new upstream version"
git commit --amend -a
</pre>
</p>
<p>
Do other debian/ changes, if there is anything:
<pre class="commandline">
vim debian/control
dch "Bump Standards-Version (no changes needed)"
git commit -a
</pre>
</p>
<p>
You might want to use pristine tar to store your new tar, too:
<pre class="commandline">
pristine-tar commit ../stuff_newversion.orig.tar.gz upstream
</pre>
</p>
<p>
Then push the whole thing back:
<pre class="commandline">
git push
</pre>
</p>
<H2><A name="createnew">Create a new project</A></H2>
<p>
Create an upstream (or upstream-whatever) branch containing
the contents of your orig.tar file:
<pre class="commandline">
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
</pre>
</p>
<p>
You might want to use pristine tar to store your tar:
<pre class="commandline">
pristine-tar commit ../example_0.orig.tar.gz upstream-unstable
</pre>
</p>
<p>
Then let git-dpm know what tar ball your upstream branch belongs to:
<pre class="commandline">
git-dpm init ../example_0.orig.tar.gz
</pre>
</p>
<p>
Do the rest of the packaging:
<pre class="commandline">
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"
</pre>
</p>
<p>
Then add some patches:
<pre class="commandline">
git-dpm checkout-patched
vim ...
git commit -a
git-dpm update-patches
dch "fix ... (Closes: num)"
git commit --amend -a
</pre>
</p>
<p>
Then build your package:
<pre class="commandline">
git-dpm status &&
dpkg-buildpackage -rfakeroot -us -uc -I".git*"
</pre>
</p>
<p>
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.
</p>
<p>
Continue the last few steps until the package is finished.
Then push your package:
<pre class="commandline">
git-dpm tag
git push --tags target unstable:unstable pristine-tar:pristine-tar
</pre>
</p>
<H2><A name="createold">Switching an existing project to git-dpm</A></H2>
<p>
In this example about porting an existing repository to git-dpm,
let's use some realistic example: xorg-server.
</p>
<p>
First check it out:
<pre class="commandline">
git clone git://git.debian.org/pkg-xorg/xserver/xorg-server.git
cd xorg-server
</pre>
</p>
<p>
To make this example reproducible, let's switch to an specific point,
namely version 2:1.7.3.902-1:
<pre class="commandline">
git checkout -b master 6fad5b26289e6b13aebfd9e684942743d2384439
</pre>
</p>
<p>
First, let's also get the upstream tar ball (That might need snapshot.debian.net
or something like that instead in the future).
<pre class="commandline">
(cd .. && wget http://ftp.debian.org/debian/pool/main/x/xorg-server/xorg-server_1.7.3.902.orig.tar.gz)
</pre>
</p>
<p>
First we need an upstream branch with contents similar enough to the upstream tar ball.
The easiest way it to just use that:
<pre class="commandline">
git-dpm import-tar -p d1320f4f2908fd3a248a79314bd78f76b03c71c5 ../xorg-server_1.7.3.902.orig.tar.gz
git checkout -b upstream
</pre>
(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.
</p>
<p>
Then we can just try (if that succeeds, we could be finished):
<pre class="commandline">
git-dpm init ../xorg-server_1.7.3.902.orig.tar.gz upstream
</pre>
This gives a long list of files that are added or modified in our current debian
branch <tt>master</tt>, so we have to investigate.
(It suggests <tt>--patched-applied</tt>, but it's easy to say the patches in debian/patches/ are not yet applied, so this will not help).
</p>
<p>
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):
<pre class="commandline">
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"
</pre>
</p>
<p>
Trying again to see what is left:
<pre class="commandline">
git-dpm init ../xorg-server_1.7.3.902.orig.tar.gz upstream
</pre>
</p>
<p>
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:
<pre class="commandline">
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
</pre>
</p>
<p>
Only one file left.
Looking at this shows it is empty and no longer referenced anywhere in the source,
so some other artefact.
<pre class="commandline">
git checkout master
git rm -f hw/xfree86/osandcommon.c
git commit -m "remove empty files left in the debian branch"
</pre>
</p>
<p>
Trying again:
<pre class="commandline">
git-dpm init ../xorg-server_1.7.3.902.orig.tar.gz upstream pre
</pre>
show that is worked this time. So get rid of the temporary branch:
<pre class="commandline">
git branch -d pre
</pre>
</p>
|