3 dgit-downstream-dsc - tutorial for downstreams publishing source packages
7 This document is aimed at downstreams of Debian.
8 It explains how you can
9 publish your packages' source code
10 both as traditional Debian source packages,
13 Your users will be able to get the source with B<dgit clone>,
14 or with traditional tools such as B<apt-get source>.
16 Note that often it is unnecessary to
17 publish traditional source packages.
18 Source packages are complex, idiosyncratic and difficult to work with.
19 You should avoid them if you can.
20 If you do not need to publish source packages,
21 you can work as a Debian downstream purely using dgit and git branches.
22 You can push your source code as a git branch to an ordinary git server.
27 You need to choose some names.
33 dgit understands each thing it interacts with as a B<distro>.
34 So in dgit terms, you are setting up a distro.
36 You need a name for yourself (ie for your distro).
37 The name will appear in the git tags made by your tools,
38 and in configuration settings.
40 You could choose your organisation's domain name,
41 or a part of it if you think that is going to be very unique.
43 The distro name may contain alphanumerics and B<. + ->,
44 although B<-> may be confusing and probably best avoided.
47 if you were the Free Software Foundation Europe (fsfe.org)
48 you might call your distro fsfe or fsfe.org.
49 In the rest of this document we will write
50 I<you> for your distro name.
54 In dgit and Debian archive terminology, a B<suite> is a line of
55 development, and/or a Debian release.
56 For example, at the time of writing, Debian has suites like
57 sid> aka unstable>, buster aka testing,
59 There are also ancillary suites like stretch-security.
61 If your releases align with Debian's releases,
62 then your suites should contain the Debian suite names.
63 B<Do not> use just the Debian names.
64 That will cause confusion.
65 Instead, prepend your organisation's name and a hyphen.
66 For example, FSFE might end up with suites like fsfe-stretch.
68 Suite names end up in git ref and branch names,
69 and on dgit command lines.
70 Suite names can contain alphanumerics and C<->.
71 Other characters may work but is not recommended.
77 You will need to run two parallel services:
83 This will hold the git branches accessed by dgit.
85 Everyone who will use dgit push needs to be able to update
87 (note, not B<refs/heads/dgit/>I<suite>) on that server,
89 I<you>B</>I<version> and B<archive/>I<you>B</>I<version>.
91 The server may host other branches and tags too.
92 So this might be your ordinary git server,
93 or an instance of a git hosting system.
95 Everyone who obtains one of your source packages,
96 or who will run B<dgit clone> and B<dgit fetch>,
97 needs to have at least read access to the git server.
99 Debian's dgit git server has special access control rules,
100 implemented in B<dgit-repos-server> and B<dgit-repos-policy-debian>
101 in the package B<dgit-infrastructure>.
102 but in most installations this is not needed.
103 If there is no or little distinction between
104 (i) developers who are entitled to upload (push) and
105 (ii) repository administrators,
106 then a git server with ordinary access control will do.
108 =item Debian-format archive (repository)
110 This holds the source packages.
111 You will probably use the same archive to host your binaries,
112 and point your B<apt> at it.
114 dgit uses the term B<archive> for this.
116 There are a variety of tools for
117 creating and managing a Debian-format archive.
118 In this document we will assume you are using B<reprepro>.
120 Setting up reprepro is not covered in this tutorial.
121 Instead, we assume you already have reprepro working.
123 You should also write appropriate dput configuration,
124 since dgit uses dput to upload packages to the archive.
125 This will involve choosing a dput host name.
126 That's probably your distro name, I<you>.
132 When you have all of the above set up,
133 you are ready to explain to dgit how to access your systems.
135 dgit is configured via git's configuration system,
136 so this is done with git configuration.
137 See L<git-config(1)>.
141 =item git url structure
143 The format of the readonly unauthenticated urls
144 (hopefully https, but http or git will do)
145 for your packages' git repos.
146 These will be of the form:
147 C<git-url>I<package-name>C<git-url-suffix>.
151 B<dgit-distro.>I<you>B<.git-url> = C<git-url>
153 B<dgit-distro.>I<you>B<.git-url-suffix> = C<git-url-suffix> (if any)
155 =item git server access via ssh
157 dgit push will either
158 B<ssh> I<localusername>B<@>C<push.git-host>
160 B<ssh> C<push.git-user-force>B<@>C<push.git-host>
164 B<dgit-distro.>I<you>B</push.git-url> ""
166 B<dgit-distro.>I<you>B</push.git-host> C<push.git-host>
168 dgit-distro.I<you>/push.git-user-force C<push.git-user-force>
169 (eg you would set this too B<git> if your hosting service
170 expects every user to ssh to git@service)
172 C<dgit-distro.>I<you>B</push.git-proto> B<git+ssh://>
174 C<dgit-distro.>I<you>B</push.git-path> "/dgit/I<you>/repos"
176 =item git repository existence testing
187 its name for sshing into it,
188 and the path on the server
190 Assuming your git server package
194 dgit-distro.I<you>.git-url-suffix .git
197 dgit-distro.I<you>.git-check "true"
199 dgit-distro.I<you>.git-check-suffix "/info/refs"
201 dgit-distro.I<you>/push.git-check "ssh-cmd"
203 dgit-distro.I<you>/push.git-create "true"
205 dgit-distro.I<you>.upload-host I<you>
207 dgit-distro.I<you>.mirror http://archive.I<you>.org/I<you>
209 dgit-distro.I<you>.archive-query "aptget:"
211 dgit-suite.wheezy-staging.distro I<you>
213 dgit-suite.jessie-staging.distro I<you>
215 dgit-suite.stretch-staging.distro I<you>
219 If you do not want or need to
224 B<dgit push> can be used.
226 B<dgit> can be incorporated into a
227 git-buildpackage(1) package-maintenance workflow. This should be read
228 jointly with git-buildpackage(1)'s documentation. Some reasons why
229 you might want to incorporate B<dgit> into your existing workflow:
235 Benefit from dgit's safety catches. In particular, ensure that your
236 upload always matches exactly your git HEAD.
240 Provide a better, more detailed git history to downstream dgit users,
241 such as people using dgit to do an NMU (see dgit-nmu-simple(7) and
246 Note that we assume a patches-unapplied repository: the upstream
247 source committed to the git repository is unpatched.
248 git-buildpackage(1) can work with patched-applied repositories, but is
249 normally used with patches-unapplied.
251 =head1 GIT CONFIGURATION
257 % git config dgit.default.quilt-mode gbp
261 in your repository, you can omit I<--gbp> wherever it occurs below.
263 Note that this does require that you always work from your gbp master
264 branch, never the dgit patches-applied branch.
268 You can perform builds like this:
272 % dgit [--allow-dirty] gbp-build [OPTIONS]
276 where I<--allow-dirty> is needed for testing uncommitted changes, and
277 I<OPTIONS> are any further options to be passed on to
280 When you are ready to build for upload, you will probably want to use
281 sbuild(1) or pbuilder(1), or do a source-only upload. Either
285 % dgit --rm-old-changes --gbp sbuild
293 % dgit --rm-old-changes gbp-build --git-pbuilder
301 % dgit --rm-old-changes --gbp build-source
305 We use I<--rm-old-changes> to ensure that there is exactly one changes
306 file corresponding to this package, so we can be confident we're
307 uploading what we intend (though B<dgit push> will do some safety
310 Note that all of the commands in this section are not required to
311 upload with dgit. You can invoke gbp-buildpackage(1), pbuilder(1) and
312 sbuild(1) directly. However, the defaults for these tools may leave
313 you with something that dgit will refuse to upload because it doesn't
314 match your git HEAD. As a general rule, leave all signing and tagging
319 Don't use I<--git-tag>: B<dgit push> will do this for you. To upload:
327 This will push your git history to the dgit-repos, but you probably
328 want to follow it up with a push to alioth.
330 You will need to pass I<--overwrite> if the previous upload was not
333 If this is first ever dgit push of the package, consider passing
334 I<--deliberately-not-fast-forward> instead of I<--overwrite>. This
335 avoids introducing a new origin commit into the dgit view of your git
336 history. (This origin commit would represent the most recent non-dgit
337 upload of the package, but this should already be represented in your
340 =head1 INCORPORATING NMUS
342 B<dgit pull> can't yet incorporate NMUs into patches-unapplied gbp
343 branches. You can just apply the NMU diff the traditional way. The
344 next upload will require I<--overwrite>.
352 This tutorial was written and is maintained by Sean Whitton <spwhitton@spwhitton.name>.