3 dgit - tips for maintaining official Debian backports
7 This document describes elements of a workflow for using B<dgit> to
8 maintain an official Debian backport. We do not assume that whoever
9 uploads the package to Debian unstable is using B<dgit>.
13 The first time a package is backported
14 for any particular Debian release,
15 you will have to pass the --new option to dgit.
19 Let the I<master> branch contain the packaging history uploaded to
20 Debian unstable, and the I<buster-bpo> branch be where you prepare
21 your uploads to the B<buster-backports> suite.
23 A B<merging> backports workflow means that each time an upload
24 migrates to Debian testing and you want to prepare an upload to
25 B<buster-backports>, you do something like this:
29 % git checkout buster-bpo
32 % # any other changes needed for backporting
38 A B<rebasing> backports workflow means that you throw away the history
39 of the I<buster-bpo> branch each time a new version migrates to Debian
40 testing, something equivalent to this:
44 % git checkout -B buster-bpo master
46 % # any other changes needed for backporting
52 If you use a merging backports workflow, your changelog contains
53 entries for each previous upload to B<buster-backports>; in a rebasing
54 workflow, it contains only the latest.
56 =head1 CHOOSING BETWEEN THE TWO WORKFLOWS
58 If backporting involves making no (additional) changes to the upstream
59 source, whether you use a merging or rebasing backports workflow is a
60 matter of personal preference. There are good arguments in favour of
61 both workflows fitting the semantics of the B<*-backports> suites.
63 If you have to make changes to the upstream source to make the package
64 work on machines running Debian stable, it is advisable to choose a
65 rebasing workflow. This ensures that dgit can automatically update
66 the debian/patches directory without any manual intervention.
68 =head1 TIPS FOR A MERGING WORKFLOW
70 =head2 Use dgit's branches
72 If you do not yourself upload the package to Debian unstable, it is
73 usually easiest to use dgit's branches, and ignore the configured
80 % dgit clone foo bullseye
84 for a new backport of package 'foo' to B<buster-backports>, and then
89 % git merge dgit/dgit/bullseye
93 when new versions migrate to Debian testing.
95 =head1 TIPS FOR A REBASING WORKFLOW
97 =head2 Use dgit's branches
99 If you do not yourself upload the package to Debian unstable, it is
100 usually easiest to use dgit's branches, and ignore the configured
101 Vcs-Git repository. For each new version from Debian testing, you
106 % dgit fetch bullseye
107 % git checkout -B buster-bpo dgit/dgit/bullseye
108 % # use git-cherry-pick(1) to (re)apply any needed backporting fixes
114 B<dgit push> tries hard to prevent you from accidentally overwriting
115 uploads that it thinks aren't represented in the git history you are
116 trying to upload. This is mainly to prevent accidentally overwriting
119 With a rebasing backports workflow, dgit will think that every upload
120 of a new version from Debian testing might be accidentally overwriting
121 uploads. You will need to explicitly indicate the upload to
122 B<buster-backports> you wish to overwrite.
124 Suppose that the last upload to B<buster-backports> was versioned
125 I<1.2.2-1~bpo10+1> and you have now prepared I<1.2.3-1~bpo10+1> for
126 upload. When you B<dgit push>, you will need to pass
127 I<--overwrite=1.2.2-1~bpo10+1>.
129 Alternatively, you can perform the pseudomerge that I<--overwrite>
130 would have done yourself:
134 % dgit fetch buster-backports
135 % git merge -s ours dgit/dgit/buster-backports
142 dgit(1), dgit(7), https://backports.debian.org/
146 This manpage was written and is maintained by Sean Whitton
147 <spwhitton@spwhitton.name>.