1 Using TopGit to generate quilt series for Debian packaging
2 ----------------------------------------------------------
4 You have been referred to this document probably because a source package you
5 are working on uses TopGit to generate a quilt series to encapsulate
6 differences between upstream and the source code used for the Debian package.
8 Please make sure that you have a recent version of TopGit (>= 0.5) installed
9 before trying any of this.
11 Where appropriate, the examples use the topgit package itself to illustrate
12 the use. I trust you to be able to make the appropriate amendments for your
15 1. Cloning the repository
16 ~~~~~~~~~~~~~~~~~~~~~~~~~
17 Cloning a TopGit repository requires an additional step to normal Git cloning:
19 1. git clone ssh://git.debian.org/git/collab-maint/topgit.git
21 3. tg remote --populate origin
23 You can also use the debcheckout tool from the devscripts package:
27 which will do all the above for you automatically.
31 The following branches are in use in the topgit package. You are free to
32 deviate from this set for the package you are working on, but then please
33 document it accordingly in your README.source.
35 - upstream: tracks the upstream Git repository
36 - fixes/*: patches fixing problems with upstream
37 - features/*: patches providing new features, targetted upstream
38 - master: the main Debianisation branch
39 - debian/*: Debian-specific patches
41 upstream and master are regular Git branches, while the others are TopGit
42 branches. The reason why master is not a TopGit branch itself is so that it's
43 possible to export all TopGit-managed branches into the quilt series, without
44 having to make an exception for master.
46 2. Developing a new feature
47 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
48 If you want to develop a new feature (or bug fix), first consider whether the
49 patch is intended to go upstream or is a Debian-specific change. Choose the
50 namespace accordingly and base it off upstream or master respectively. If the
51 patch depends on another patch, obviously base it off the respective TopGit
54 The following are the steps required to add a feature branch/patch:
56 1. tg create features/new-feature upstream
58 tg create debian/new-debian-stuff master
60 2. edit .topmsg and make the subject line be a short description, optionally
61 add a longer description to the body
63 3. git add .topmsg && git commit
65 3. Obtaining the upstream tarball
66 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
67 The upstream tarball for the topgit package $VERSION can be obtained using
70 pristine-tar checkout ../topgit_$VERSION.orig.tar.gz
72 4. Building the package
73 ~~~~~~~~~~~~~~~~~~~~~~~
74 Building the package is trivial, thanks to the inclusion of the tg2quilt.mk
75 snippet at the top of debian/rules.
77 Unless you set the TG_BRANCHES variable before the include statement (or when
78 you invoke debian/rules (or make), tg2quilt will simply export all TopGit
79 branches into the quilt series. You can set the variable TG_BRANCHES to
80 a space- or comma-separated list (but not comma and space) of feature branches
83 TG_BRANCHES := branch1,branch2
84 TG_BRANCHES := 'branch3 branch4 branch 5'
86 Building the package requires no additional steps over other Debian packages.
88 Since it is currently not possible to access TopGit branches for previous
89 versions of a package (#500656), it is a good idea to maintain a build branch,
90 into which you merge the master (Debianisation) branch whenever making a new
91 release, and where you simply track the contents of the debian/patches
92 directory. This can conveniently become the branch from which you build:
96 3. ./debian/rules tg-cleanexport
97 4. git add debian/patches
98 5. git commit -m'preparing $VERSION'
99 6. build, test, upload, tag ('debian/topgit-$VERSION')
101 TODO: add a debian/NEWS entry to get people to switch to using this approach.
103 5. Importing a new upstream version
104 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105 To import a new upstream, update the remote, merge the tag you want to merge
106 into the master branch, ideally together with an update to debian/changelog,
107 then update all TopGit branches:
110 2. git checkout master
111 3. git merge <new-upstream-tag>
113 Now proceed as in the next step.
115 6. Making changes to the master branch
116 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
117 If you make changes to the master branch (the "debianisation" branch), follow
121 2. for every branch that is prefixed with 'D' in the output:
122 git checkout $BRANCH && tg update
124 7. Building an upstream tarball
125 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
126 If you are using pristine-tar, the follopwing can be used to commit an
127 upstream tarball to the repository. It makes sense to rename it according to
128 the Debian-standard package_version.orig.tar.gz convention first.
130 1. pristine-tar commit ../topgit_$VERSION.orig.tar.gz <upstream-tag>
132 If upstream does not provide tarballs, you can create the orig.tar.gz file and
133 commit is as follows:
135 1. git checkout topgit-$VERSION
136 2. git archive --prefix=$(git describe HEAD)/ --verbose HEAD \
137 | gzip -9 > ../$(git describe HEAD | sed s,-,_,).orig.tar.gz
138 3. pristine-tar commit ../$(git describe HEAD | sed s,-,_,).orig.tar.gz \
140 4. git checkout master
144 All comments and suggestions are welcome, especially those pertaining to
145 auto-generating debian/changelog from commit logs.
147 -- martin f. krafft <madduck@debian.org> Wed, 19 Nov 2008 15:16:03 +0100