/usr/share/doc/git-buildpackage/manual-html/gbp.patches.html is in git-buildpackage 0.9.8.
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 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Working with Patches: Building Debian Packages with git-buildpackage</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Building Debian Packages with git-buildpackage">
<link rel="up" href="index.html" title="Building Debian Packages with git-buildpackage">
<link rel="prev" href="gbp.building.hooks.html" title="Invoking external programs">
<link rel="next" href="gbp.patches.newupstream.html" title="Importing a new upstream version">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><img src="up-insensitive.png" width="16" height="16" border="0"></td>
<td><a accesskey="p" href="gbp.building.hooks.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="gbp.patches.newupstream.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter">
<div class="titlepage"><div><div><h1 class="title">
<a name="gbp.patches"></a>Working with Patches</h1></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="sect1"><a href="gbp.patches.html#gbp.patches.workflow">Basic Workflow</a></span></dt>
<dt><span class="sect1"><a href="gbp.patches.newupstream.html">Importing a new upstream version</a></span></dt>
<dt><span class="sect1"><a href="gbp.patches.firstpatch.html">Adding your first patch</a></span></dt>
<dt><span class="sect1"><a href="gbp.patches.team.html">Team maintenance</a></span></dt>
</dl></div>
<p>
<span class="command"><strong>gbp pq</strong></span> can be used to manage patches that modify the upstream
source inside
<code class="filename">debian/patches/</code>. This is mostly intended for
3.0 (quilt) format source packages.
</p>
<p>
The basic idea is that patches are imported from you
<code class="option">debian-branch</code> to a patch-queue branch with one patch file
in <code class="filename">debian/patches/</code> becoming one commit on the
the patch-queue branch. The created branch will be named after
the branch you imported from
with <code class="filename">patch-queue/</code> prepended. So if you do
your <span class="productname">Debian</span>™ packaging on <code class="filename">debian/sid</code> and do
a
</p>
<pre class="programlisting">
<span class="command"><strong>gbp pq <code class="option">import</code></strong></span>
</pre>
<p>
then the newly created branch will be
called <code class="filename">patch-queue/debian/sid</code>.
</p>
<p>On the patch-queue branch you can work on the commits using
familiar <span class="productname">Git</span>™ commands (rebase, commit --amend, etc). When done,
<span class="command"><strong>gbp pq</strong></span> will be used to turn the commits on the patch-queue
branch into patch in <code class="filename">debian/patches/</code> files
again.
</p>
<p>
This workflow facilitates e.g. the cherry-picking of patches for
stable releases, the forward-porting of patches to new upstream
versions by using git rebase on the patch-queue branch (patches
already applied upstream are detected automatically) as well as
the reordering, dropping and renaming of patches without having to
resort to <span class="command"><strong>quilt</strong></span>. The generated patches
in <code class="filename">debian/patches/</code> have all the necessary
information to forward them upstream since they use a format similar
to <span class="command"><strong>git-format-patch</strong></span>.
</p>
<p>
The main drawback of this workflow is the lack of history on the
patch-queue branch since it is frequently droppend and
recreated. But there is full history on
the your <code class="option">debian-branch</code>, of course.
</p>
<p>
Also, beware that <span class="command"><strong>gbp pq</strong></span> currently has incomplete support for
<a class="ulink" href="http://dep.debian.net/deps/dep3/" target="_top">DEP3</a> headers.
Initially, parsing with <span class="command"><strong>git-mailinfo(1)</strong></span> is attempted,
which supports only the <code class="computeroutput">From</code> and
<code class="computeroutput">Subject</code> fields. If neither of these are
present, <span class="command"><strong>gbp pq</strong></span> will attempt to convert the patch from DEP3 format into
a <span class="command"><strong>git-mailinfo(1)</strong></span> compatible format. This involves first
loading <code class="computeroutput">From</code> using the
<code class="computeroutput">Author</code> field and
<code class="computeroutput">Subject</code> using the first line of the
<code class="computeroutput">Description</code> field. Then, any additional
fields (such as <code class="computeroutput">Origin</code> and
<code class="computeroutput">Forwarded</code>), and the remainder of the
<code class="computeroutput">Description</code> (if any), will be appended to
the body.
</p>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="gbp.patches.workflow"></a>Basic Workflow</h2></div></div></div>
<p>
This example assumes you're working on a source 3.0 (quilt)
format package with patches
in <code class="filename">debian/patches</code> parseable
by <span class="command"><strong>git-quiltimport(1)</strong></span>. The git branch
currently checked out is named <code class="filename">debian/sid</code>.
</p>
<div class="mediaobject">
<img src="images/pq-unapplied.png"><div class="caption"><p>
The <code class="option">debian-branch</code> we start from.
</p></div>
</div>
<p>Let's first create the patch-queue branch and import the
contents of <code class="filename">debian/patches</code> onto it using
<span class="command"><strong>gbp pq</strong></span>
</p>
<pre class="programlisting">
<span class="command"><strong>cd <em class="replaceable"><code>REPO</code></em></strong></span>
<span class="command"><strong>gbp pq</strong></span> import
</pre>
<p>
This will generate output like:
</p>
<pre class="screen">
gbp:info: Trying to apply patches at 'aaa1011bfd5aa74fea43620aae94709de05f80be'
gbp:info: 18 patches listed in 'debian/patches/series' imported on 'patch-queue/debian/sid'
</pre>
<p>
What happened is that <span class="command"><strong>gbp pq</strong></span> imported each patch file and switched
you to the newly created patch-queue branch
(<code class="filename">patch-queue/debian/sid</code>) automatically.
</p>
<div class="mediaobject">
<img src="images/pq-applied.png"><div class="caption"><p>
The patch-queue branch with patches
from <code class="filename">debian/patches</code> applied.
</p></div>
</div>
<p>
Now you can work on the patch-queue branch (add, remove, rebase,
test) to get your patches into shape:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>
To add what will later become a patch
in <code class="filename">debian/patches/</code> simply make a
commit. The first line of the commit message will become the
patch name later. The following lines include the details of
what the patch does.
</p></li>
<li class="listitem"><p>
To remove or edit commits use git rebase -i . The git
documentation explains how to work with git-rebase.
</p></li>
</ul></div>
<p>
</p>
<p>
Once satisfied with the commits let's regenerate the patches
in <code class="filename">debian/patches/</code> using <span class="command"><strong>gbp pq</strong></span>. This will
switch you back to the branch <code class="filename">debian/sid</code> and
regenerate the patches using a method similar
to <span class="command"><strong>git-format-patch</strong></span>:
</p>
<pre class="programlisting">
<span class="command"><strong>gbp pq</strong></span> export
</pre>
<p>You can now commit the result by using:</p>
<pre class="programlisting">
<span class="command"><strong>git</strong></span> add debian/patches
<span class="command"><strong>git</strong></span> commit
</pre>
<p>
If you don't want to commit the result by hand each time you can also
pass <code class="option">--commit</code> to the <span class="command"><strong>gbp</strong></span> <code class="option">export</code>
command above.
</p>
<p>
Next you can update <code class="filename">debian/changelog</code> (e.g. by
running "<span class="command"><strong>gbp dch</strong></span> <code class="option">-S</code> <code class="option">-a</code>") and
build the package as usual.
</p>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc</div>
</body>
</html>
|