git-debpush.1.pod

   1 =head1 NAME
   2
   3 git-debpush - create & push a git tag with metadata for an ftp-master upload
   4
   5 =head1 SYNOPSIS
   6
   7 B<git debpush> [I<option>...]
   8
   9 =head1 DESCRIPTION
  10
  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
  14 Debian-style archive.
  15
  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.
  21
  22 B<git-debpush> is only for source-only uploads.
  23
  24 =head1 TYPICAL USAGE
  25
  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.
  32
  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
  37
  38 =over 4
  39
  40     % git debpush --gbp
  41
  42 =back
  43
  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.
  46
  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.
  51
  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.
  56
  57 =head1 SETUP FOR SOURCE FORMAT 1.0
  58
  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.
  63
  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
  67 the manpage.
  68
  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
  74
  75 =over 4
  76
  77     % echo "-sn" >>debian/source/options
  78
  79 =back
  80
  81 If your package is native, execute
  82
  83 =over 4
  84
  85     % echo "-sk" >>debian/source/options
  86
  87 =back
  88
  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
  92 tarballs.)
  93
  94 =head1 QUILT MODE OPTIONS
  95
  96 =over 4
  97
  98 =item B<--quilt=gbp>|B<--gbp>
  99
 100 You are using the 'unapplied' branch format, typically used with
 101 gbp(1).
 102
 103 =item B<--quilt=dpm>|B<--dpm>
 104
 105 You are using git-dpm(1)'s branch format.
 106
 107 =item B<--quilt=baredebian[+git]>|B<--baredebian[+git]>
 108
 109 You are using the 'bare debian' branch format, with the upstream
 110 source in the form of an upstream tag.
 111
 112 B<--quilt=baredebian+git> is an alias for B<--quilt=baredebian>.
 113
 114 =item B<--quilt=linear>
 115
 116 You are using the 'manually maintained applied' branch format or
 117 similar, and each commit touching the upstream source not already
 118 represented in debian/patches should be added as a new patch.
 119
 120 =item B<--quilt=smash>
 121
 122 You are using the 'manually maintained applied' branch format or
 123 similar, and you want all changes to the upstream source to be
 124 squashed into a single patch in debian/patches.
 125
 126 =item B<--quilt=auto>
 127
 128 Tell the intermediary service to try B<--quilt=linear>, and if that
 129 cannot succeed, fall back to B<--quilt=smash>.
 130
 131 =item B<--quilt=nofix>
 132
 133 You are using the 'manually maintained applied' branch format or
 134 similar, and you don't want debian/patches to be touched by the
 135 intermediary service.
 136
 137 If all commits touching the upstream source are not already
 138 represented in debian/patches, the intermediary service will fail to
 139 upload your package.
 140
 141 =back
 142
 143 =head1 OTHER OPTIONS
 144
 145 =over 4
 146
 147 =item B<--no-push>|B<-n>
 148
 149 Just tag, don't push.
 150
 151 =item B<-u> I<keyid>
 152
 153 Passed on to git-tag(1).
 154
 155 =item B<--branch=>I<BRANCH>
 156
 157 Where to place the tag, i.e., what you want to release.  If
 158 unspecified, we put the tag on whatever HEAD points to.
 159
 160 Note that this need not actually be a branch, but any committish (see
 161 gitglossary(7)).  The option name is chosen to fit what is by far the
 162 most common case.
 163
 164 =item B<--upstream=>I<TAG>
 165
 166 When pushing a non-native package,
 167 B<git-debpush> needs a tag for the upstream part of your package.
 168
 169 By default B<git-debpush> asks git-deborig(1),
 170 which searches for a suitable tag
 171 based on the upstream version in debian/changelog.
 172
 173 =item B<--remote=>I<REMOTE>
 174
 175 Where to push tags and branches.  If unspecified, use the remote which
 176 git would use if you typed "git push BRANCH".
 177
 178 =item B<--distro=>I<DISTRO>
 179
 180 What distribution name to embed in the signed tag.  Defaults to
 181 "debian".
 182
 183 =item B<--force>|B<-f>
 184
 185 Ignore the results of all checks designed to prevent broken uploads.
 186
 187 =item B<--force>=I<check>[,I<check>] ...
 188
 189 Override individual checks designed to prevent broken uploads.  May be
 190 specified more than once.
 191
 192 Using B<--force> or B<--force=>I<check> might cause the upload to fail
 193 at some later point in the process.
 194
 195 Valid values for I<check> are:
 196
 197 =over 4
 198
 199 =item B<suite>
 200
 201 Permit uploading to a different suite than the target of the most
 202 recent upload made with B<git-debpush> (e.g. when uploading to
 203 Debian unstable after uploading to Debian experimental).
 204
 205 =item B<upstream-nonancestor>
 206
 207 Ignore the fact that the upstream tag is not an ancestor of the branch
 208 to be tagged (skipping this check is implied by B<--quilt=baredebian>).
 209
 210 =item B<upstream-nonidentical>
 211
 212 Ignore any differences between the upstream source in the upstream tag
 213 and the upstream source in the branch to be tagged (this check is only
 214 run when using B<--quilt=gbp> or B<--quilt=unapplied>).
 215
 216 =item B<patches-applicable>
 217
 218 Ignore any failures of the following two checks:
 219
 220 =over 4
 221
 222 =item
 223
 224 With B<--quilt=gbp>, B<--quilt=unapplied>, B<--quilt=baredebian>,
 225 B<--quilt=dpm>, and B<--quilt=nofix>, the quilt patches should apply
 226 cleanly to the upstream source with git-apply(1).
 227
 228 =item
 229
 230 With B<--quilt=dpm> and B<--quilt=nofix>, applying the quilt patches
 231 to the upstream source should produce exactly the source tree to be
 232 tagged.
 233
 234 =back
 235
 236 =item B<unreleased>
 237
 238 Permit upload to a suite called UNRELEASED.
 239
 240 =item B<dgit-view>
 241
 242 Ignore apparently pushing the dgit view of a package (as produced by
 243 B<dgit clone>) to the maintainer branch, where the dgit view and the
 244 maintainer view of the package are not identical.
 245
 246 =item B<unstitched>
 247
 248 Ignore the fact that the branch to be pushed seems to be a
 249 git-debrebase(1) branch in an unstitched state (see git-debrebase(5)).
 250
 251 =back
 252
 253 =item B<detached>
 254
 255 Ignore the fact that HEAD is to be tagged, but HEAD is detached (this
 256 check is only run when B<--branch=HEAD> or no B<--branch> option is
 257 specified).
 258
 259 =back
 260
 261 =head1 SEE ALSO
 262
 263 Git branch formats in use by Debian maintainers:
 264 <https://wiki.debian.org/GitPackagingSurvey>
 265
 266 =head1 AUTHOR
 267
 268 B<git-debpush> and this manpage were written by Sean Whitton
 269 <spwhitton@spwhitton.name> with much input from Ian Jackson
 270 <ijackson@chiark.greenend.org.uk>.