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 Let the I<master> branch contain the packaging history uploaded to
14 Debian unstable, and the I<buster-bpo> branch be where you prepare
15 your uploads to the B<buster-backports> suite.
17 A B<merging> backports workflow means that each time an upload
18 migrates to Debian testing and you want to prepare an upload to
19 B<buster-backports>, you do something like this:
23 % git checkout buster-bpo
26 % # any other changes needed for backporting
32 A B<rebasing> backports workflow means that you throw away the history
33 of the I<buster-bpo> branch each time a new version migrates to Debian
34 testing, something equivalent to this:
38 % git checkout -B buster-bpo master
40 % # any other changes needed for backporting
46 If you use a merging backports workflow, your changelog contains
47 entries for each previous upload to B<buster-backports>; in a rebasing
48 workflow, it contains only the latest.
50 =head1 CHOOSING BETWEEN THE TWO WORKFLOWS
52 If backporting involves making no (additional) changes to the upstream
53 source, whether you use a merging or rebasing backports workflow is a
54 matter of personal preference. There are good arguments in favour of
55 both workflows fitting the semantics of the B<*-backports> suites.
57 If you have to make changes to the upstream source to make the package
58 work on machines running Debian stable, it is advisable to choose a
59 rebasing workflow. This ensures that dgit can automatically update
60 the debian/patches directory without any manual intervention.
62 =head1 TIPS FOR A MERGING WORKFLOW
64 =head2 Use dgit's branches
66 If you do not yourself upload the package to Debian unstable, it is
67 usually easiest to use dgit's branches, and ignore the configured
74 % dgit clone foo bullseye
78 for a new backport of package 'foo' to B<buster-backports>, and then
83 % git merge dgit/dgit/bullseye
87 when new versions migrate to Debian testing.
89 =head1 TIPS FOR A REBASING WORKFLOW
91 =head2 Use dgit's branches
93 If you do not yourself upload the package to Debian unstable, it is
94 usually easiest to use dgit's branches, and ignore the configured
95 Vcs-Git repository. For each new version from Debian testing, you
100 % dgit fetch bullseye
101 % git checkout -B buster-bpo dgit/dgit/bullseye
102 % # use git-cherry-pick(1) to (re)apply any needed backporting fixes
108 B<dgit push> tries hard to prevent you from accidentally overwriting
109 uploads that it thinks aren't represented in the git history you are
110 trying to upload. This is mainly to prevent accidentally overwriting
113 With a rebasing backports workflow, dgit will think that every upload
114 of a new version from Debian testing might be accidentally overwriting
115 uploads. You will need to explicitly indicate the upload to
116 B<buster-backports> you wish to overwrite.
118 Suppose that the last upload to B<buster-backports> was versioned
119 I<1.2.2-1~bpo10+1> and you have now prepared I<1.2.3-1~bpo10+1> for
120 upload. When you B<dgit push>, you will need to pass
121 I<--overwrite=1.2.2-1~bpo10+1>.
123 Alternatively, you can perform the pseudomerge that I<--overwrite>
124 would have done yourself:
128 % dgit fetch buster-backports
129 % git merge -s ours dgit/dgit/buster-backports
136 dgit(1), dgit(7), https://backports.debian.org/
140 This manpage was written and is maintained by Sean Whitton
141 <spwhitton@spwhitton.name>.