3 git-debpush - create & push a git tag with metadata for an ftp-master upload
7 B<git debpush> [I<option>...]
11 B<git-debpush> is a wrapper around git-tag(1) and git-push(1). It
12 helps you create and push a specially formatted signed tag which
13 indicates that the tagged commit should be pushed (or "uploaded") to a
16 Typically, your git server will be configured to notify an
17 intermediary service of the new tag that you pushed. That service
18 will then fetch your tag, check your PGP signature, do any conversion
19 that's needed (such as producing and signing a B<.dsc> and
20 B<.changes>), and upload the result to the Debian-style archive.
22 B<git-debpush> is only for source-only uploads.
26 B<git-debpush> is designed such that for regular uploads of your
27 package, you should be able to just invoke it without passing any
28 command line arguments. After you've built and tested some .debs, run
29 dch(1) to finalise your changelog and committed the result, just type
30 "git debpush", and the intermediary service and your distribution's
31 autobuilder network will take care of the rest.
33 The most common exception to this is the first time you use
34 B<git-debpush> for a non-native package. You will need to pass a
35 quilt mode option to inform the intermediary service which git branch
36 format you are using, for example
44 if you are using the git branch format typically used with gbp(1).
45 See "QUILT MODE OPTIONS", below, for the available quilt mode options.
47 Aside from a few sanity checks to help avoid broken uploads,
48 B<git-debpush> does not do anything with the information provided by
49 the quilt mode option. It simply embeds the corresponding quilt mode
50 in its generated tag, for use by the intermediary service.
52 Future invocations of B<git-debpush> will try to read the quilt mode
53 out of the tag generated by B<git-debpush> for your previous upload.
54 You can override that on the command line by passing a quilt mode
55 option, which always takes precedence.
57 =head1 SETUP FOR SOURCE FORMAT 1.0
59 B<git-debpush> needs to tell the intermediary git service whether this
60 is a native or non-native package. Given historical Debian practices,
61 it is not sufficient for either B<git-debpush> or the intermediary
62 service to rely on the version number in debian/changelog.
64 If you are using one of the 3.0 source package formats, B<git-debpush>
65 will just look in debian/source/format to determine whether the
66 package is native or non-native, and you can ignore this section of
69 If you are using the 1.0 source package format -- either
70 debian/source/format does not exist, or contains the string "1.0" --
71 then B<git-debpush> must be told whether the package is native or
72 non-native. We do this using debian/source/options. If your package
73 is non-native, execute
77 % echo "-sn" >>debian/source/options
81 If your package is native, execute
85 % echo "-sk" >>debian/source/options
89 (With source format 1.0, dpkg-source(1) decides whether the package is
90 native or non-native based on the presence of absence of an orig.tar
91 in B<..>, but B<git-debpush> is a pure git tool that never looks at
94 =head1 QUILT MODE OPTIONS
98 =item B<--quilt=gbp>|B<--gbp>
100 You are using the 'unapplied' branch format, typically used with
103 =item B<--quilt=dpm>|B<--dpm>
105 You are using git-dpm(1)'s branch format.
107 =item B<--quilt=baredebian[+git]>|B<--baredebian[+git]>
109 You are using the 'bare debian' branch format, with the upstream
110 source in the form of an upstream tag.
112 =item B<--quilt=linear>
114 You are using the 'manually maintained applied' branch format or
115 similar, and each commit touching the upstream source not already
116 represented in debian/patches should be added as a new patch.
118 =item B<--quilt=smash>
120 You are using the 'manually maintained applied' branch format or
121 similar, and you want all changes to the upstream source to be
122 squashed into a single patch in debian/patches.
124 =item B<--quilt=auto>
126 Tell the intermediary service to try B<--quilt=linear>, and if that
127 cannot succeed, fall back to B<--quilt=smash>.
129 =item B<--quilt=nofix>
131 You are using the 'manually maintained applied' branch format or
132 similar, and you don't want debian/patches to be touched by the
133 intermediary service.
135 If all commits touching the upstream source are not already
136 represented in debian/patches, the intermediary service will fail to
145 =item B<--no-push>|B<-n>
147 Just tag, don't push.
151 Passed on to git-tag(1).
153 =item B<--branch=>I<BRANCH>
155 Where to place the tag, i.e., what you want to release. If
156 unspecified, we put the tag on whatever HEAD points to.
158 Note that this need not actually be a branch, but any committish (see
159 gitglossary(7)). The option name is chosen to fit what is by far the
162 =item B<--upstream=>I<TAG>
164 When pushing a non-native package,
165 B<git-debpush> needs a tag for the upstream part of your package.
167 By default B<git-debpush> asks git-deborig(1),
168 which searches for a suitable tag
169 based on the upstream version in debian/changelog.
171 =item B<--remote=>I<REMOTE>
173 Where to push tags and branches. If unspecified, use the remote which
174 git would use if you typed "git push BRANCH".
176 =item B<--distro=>I<DISTRO>
178 What distribution name to embed in the signed tag. Defaults to
181 =item B<--force>|B<-f>
183 Ignore the results of all checks designed to prevent broken uploads.
185 =item B<--force>=I<check>[,I<check>] ...
187 Override individual checks designed to prevent broken uploads. May be
188 specified more than once. Valid values for I<check> are:
194 Permit uploading to a different suite than the target of the most
195 recent upload made with B<git-debpush> (e.g. when uploading to
196 Debian unstable after uploading to Debian experimental).
198 =item B<upstream-nonancestor>
200 Ignore the fact that the upstream tag is not an ancestor of the branch
201 to be tagged (skipping this check is implied by B<--quilt=baredebian>).
203 =item B<upstream-nonidentical>
205 Ignore any differences between the upstream source in the upstream tag
206 and the upstream source in the branch to be tagged (this check is only
207 run when using B<--quilt=gbp> or B<--quilt=unapplied>).
209 =item B<patches-applicable>
211 Ignore any failures of the following two checks:
217 With B<--quilt=gbp>, B<--quilt=unapplied>, B<--quilt=baredebian>,
218 B<--quilt=dpm>, and B<--quilt=nofix>, the quilt patches should apply
219 cleanly to the upstream source with git-apply(1).
223 With B<--quilt=dpm> and B<--quilt=nofix>, applying the quilt patches
224 to the upstream source should produce exactly the source tree to be
231 Permit upload to a suite called UNRELEASED.
235 Ignore apparently pushing the dgit view of a package (as produced by
236 B<dgit clone>) to the maintainer branch, where the dgit view and the
237 maintainer view of the package are not identical.
241 Ignore the fact that the branch to be pushed seems to be a
242 git-debrebase(1) branch in an unstitched state (see git-debrebase(5)).
248 Ignore the fact that HEAD is to be tagged, but HEAD is detached (this
249 check is only run when B<--branch=HEAD> or no B<--branch> option is
256 Git branch formats in use by Debian maintainers:
257 <https://wiki.debian.org/GitPackagingSurvey>
261 B<git-debpush> and this manpage were written by Sean Whitton
262 <spwhitton@spwhitton.name> with much input from Ian Jackson
263 <ijackson@chiark.greenend.org.uk>.