dgit.1

   1 .TH dgit 1 "" "Debian Project" "dgit"
   2 .SH NAME
   3 dgit \- git integration with the Debian archive
   4 .
   5 .SH SYNOPSIS
   6 .B dgit
   7 [\fIdgit\-opts\fP] \fBclone\fP [\fIdgit\-opts\fP]
   8 \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir]
   9 .br
  10 .B dgit
  11 [\fIdgit\-opts\fP] \fBfetch\fP|\fBpull\fP [\fIdgit\-opts\fP]
  12 [\fIsuite\fP]
  13 .br
  14 .B dgit
  15 [\fIdgit\-opts\fP] \fBbuild\fP|\fBsbuild\fP
  16 [\fIbuild\-opts\fp]
  17 .br
  18 .B dgit
  19 [\fIdgit\-opts\fP] \fBpush\fP [\fIdgit\-opts\fP]
  20 [\fIsuite\fP]
  21 .br
  22 .B dgit
  23 [\fIdgit\-opts\fP] \fIaction\fR ...
  24 .SH DESCRIPTION
  25 .B dgit
  26 treats the Debian archive as a version control system, and
  27 bidirectionally gateways between the archive and git.  The git view of
  28 the package can contain the usual upstream git history, and will be
  29 augmented by commits representing uploads done by other developers not
  30 using dgit.  This git history is stored in a canonical location known
  31 as
  32 .B dgit-repos
  33 which lives outside the Debian archive (currently, on Alioth).
  34
  35 The usual workflow is: 1. clone or fetch; 2. make and commit changes
  36 in git as desired; 3. run dgit build or dgit sbuild, or generate the
  37 source and binary packages for upload some other way; 4. do
  38 pre-upload tests of the proposed upload; 5. run dgit push.
  39 .TP
  40 \fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir]
  41 Consults the archive and dgit-repos to construct the git view of
  42 history for
  43 .I package
  44 in
  45 .I suite
  46 .RB ( sid
  47 by default)
  48 in a new directory (named
  49 .BI ./ package
  50 by default);
  51 also, downloads any necessary orig tarballs.
  52
  53 The suite's git tip is
  54 left on the local branch
  55 .BI dgit/ suite
  56 ready for work, and on the corresponding dgit remote tracking branch.
  57 Also, the
  58 .B origin
  59 remote will be set up to point to the package's dgit-repos tree
  60 for the distro to which
  61 .I suite
  62 belongs.
  63 .TP
  64 \fBdgit fetch\fR [\fIsuite\fP]
  65 Consults the archive and git-repos to update the git view of
  66 history for a specific suite (and downloads any necessary orig
  67 tarballs), and updates the remote tracking branch
  68 .BR remotes/dgit/ \fIsuite\fR.
  69 If the current branch is
  70 .BI dgit/ suite
  71 then dgit fetch defaults to
  72 .IR suite ;
  73 otherwise it parses debian/changelog and uses the suite specified
  74 there.
  75 .TP
  76 \fBdgit pull\fR [\fIsuite\fP]
  77 Does dgit fetch, and then merges the new head of the remote tracking
  78 branch
  79 .BI remotes/dgit/ suite
  80 into the current branch.
  81 .TP
  82 \fBdgit build\fR ...
  83 Runs
  84 .B git-buildpackage
  85 with some suitable options.  Options and argumments after build
  86 will be passed on to git-buildpackage.  It is not necessary to use
  87 dgit build when using dgit; it is OK to use any approach which ensures
  88 that the generated source package corresponds to the relevant git
  89 commit.  Tagging and signing should be left to dgit push.
  90 .TP
  91 \fBdgit sbuild\fR ...
  92 Constructs the source package, and uses sbuild to do a binary
  93 build, and uses mergechanges to merge the source and binary
  94 changes files.  Options and argumments after sbuild will be passed on
  95 to sbuild.  Changes files matching
  96 .IB package _ version _*.changes
  97 in the parent directory will be removed; the output is left in
  98 .IR package \fB_\fR version \fB_multi.changes\fR.
  99 .TP
 100 .B dgit push
 101 Does an `upload', pushing the current HEAD to the archive (as a source
 102 package) and to dgit-repos (as git commits).  The package must already
 103 have been built ready for upload, with the .dsc and .changes
 104 left in the parent directory.
 105
 106 In more detail: dgit push checks that the current HEAD corresponds to
 107 the .dsc.  It then pushes the HEAD to the suite's dgit-repos branch,
 108 makes a signed git tag, edits the .dsc to contain the dgit metadata
 109 field, runs debsign to sign the upload (.dsc and .changes), pushes the
 110 signed tag, and finally uses dput to upload the .changes to the
 111 archive.
 112
 113 For a format `3.0 (quilt)' source package, dgit push
 114 may also have to make a commit on your current branch to contain
 115 quilt metadata.  It will do this automatically if necessary.
 116 You can explicitly request that dgit do just this
 117 dgit quilt-fixup.
 118
 119 dgit push always uses the package, suite and version specified in the
 120 debian/changelog and the .dsc, which must agree.
 121 .TP
 122 .B dgit quilt-fixup
 123 Looks to see if there is quilt patch metadata left over by dpkg-source
 124 -b, and if so makes a git commit of it.  This is normally done
 125 automatically by dgit push.  dgit quilt-fixup takes no additional
 126 arguments.  Note that it will only process a patch generated by
 127 dpkg-source for the most recent version (according to the
 128 debia/changelog).
 129
 130 It is not normally necessary to run dgit quilt-fixup explicitly;
 131 where necessary it is done as part of dgit push.
 132 .SH WORKFLOW - SIMPLE
 133 It is always possible with dgit to clone or fetch a package, make
 134 changes in git (using git-commit) on the suite branch
 135 .RB ( "git checkout dgit/" \fIsuite\fR)
 136 and then dgit push.  You can use whatever gitish techniques you like
 137 to construct the commit to push; the only requirement is that it is a
 138 descendant of the state of the archive, as provided by dgit in the
 139 remote tracking branch
 140 .BR remotes/dgit/ \fIsuite\fR.
 141
 142 If you are lucky the other uploaders have also used dgit and
 143 integrated the other relevant git history; if not you can fetch it
 144 into your tree and cherry-pick etc. as you wish.
 145 .SH WORKFLOW - INTEGRATING BETWEEN DGIT AND OTHER GIT HISTORY
 146 If you are the maintainer of a package dealing with uploads made
 147 without dgit, you will probably want to merge the synthetic commits
 148 (made by dgit to represent the uploads) into your git history.
 149 Normally you can just merge the dgit branch into your own master, or
 150 indeed if you do your work on the dgit local suite branch
 151 .BI dgit/ suite
 152 you can just use dgit pull.
 153
 154 However the first time dgit is used it will generate a new origin
 155 commit from the archive which won't be linked into the rest of your
 156 git history.  You will need to merge this.
 157
 158 If last upload was in fact made with git, you should usually proceed
 159 as follows: identify the commit which was actually used to build the
 160 package.  (Hopefully you have a tag for this.)  Check out the dgit
 161 branch
 162 .RB ( "git checkout dgit/" \fIsuite\fR)
 163 and merge that other commit
 164 .RB ( "git merge debian/" \fIversion\fR).
 165 Hopefully this merge will be trivial because the two trees should
 166 be the same.  The resulting branch head can be merged into your
 167 working branches
 168 .RB ( "git checkout master && git merge dgit/" \fIsuite\fR).
 169
 170 If last upload was not made with git, a different approach is required
 171 to start using dgit.  First, do
 172 .B dgit fetch
 173 (or clone) to obtain a git history representation of what's in the
 174 archive and record it in the
 175 .BI remotes/dgit/ suite
 176 tracking branch.  Then somehow, using your other git history
 177 plus appropriate diffs and cherry picks from the dgit remote tracking
 178 branch, construct a git commit whose tree corresponds to the tree to use for the
 179 next upload.  If that commit-to-be-uploaded is not a descendant of the
 180 dig remote tracking branch, check it out and say
 181 .BR "git merge -s ours remotes/dgit/" \fIsuite\fR;
 182 that tells git that we are deliberately throwing away any differences
 183 between what's in the archive and what you intend to upload.
 184 Then run
 185 .BR "dgit push"
 186 to actually upload the result.
 187 .SH MODEL
 188 You may use any suitable git workflow with dgit, provided you
 189 satisfy dgit's requirements:
 190
 191 dgit maintains a pseudo-remote called
 192 .BR dgit ,
 193 with one branch per suite.  This remote cannot be used with
 194 plain git.
 195
 196 The
 197 .B dgit-repos
 198 repository for each package contains one ref per suite named
 199 \fBrefs/dgit/\fR\fIsuite\fR.  These should be pushed to only by
 200 dgit.  They are fast forwarding.  Each push on this branch
 201 corresponds to an upload (or attempted upload).
 202
 203 However, it is perfectly fine to have other branches in dgit-repos;
 204 normally the dgit-repos repo for the package will be accessible via
 205 the remote name `origin'.
 206
 207 dgit push will also (by default) make signed tags called
 208 .BI debian/ version
 209 and push them to dgit-repos, but nothing depends on these tags
 210 existing.
 211
 212 dgit push can operate on any commit which is a descendant of the
 213 current dgit/suite tip in dgit-repos.
 214
 215 Uploads made by dgit contain an additional field
 216 .B Vcs-Dgit-Master
 217 in the source package .dsc.  (This is added by dgit push.)
 218 This specifies a commit (an ancestor of the dgit/suite
 219 branch) whose tree is identical to the unpacked source upload.
 220
 221 Uploads not made by dgit are represented in git by commits which are
 222 synthesised by dgit.  The tree of each such commit corresponds to the
 223 unpacked source; there is an origin commit with the contents, and a
 224 psuedo-merge from last known upload - that is, from the contents of
 225 the dgit/suite branch.
 226
 227 dgit expects repos that it works with to have a
 228 .B dgit
 229 remote.  This refers to the well-known dgit-repos location
 230 (currently, the dgit-repos project on Alioth).  dgit fetch updates
 231 the remote tracking branch for dgit/suite.
 232
 233 dgit does not (currently) represent the orig tarball(s) in git; nor
 234 does it represent the patch statck of a `3.0 (quilt)' package.  The
 235 orig tarballs are downloaded and kept in the parent directory, as with
 236 a traditional (non-gitish) dpkg-source workflow.
 237
 238 To a user looking at the archive, changes pushed using dgit look like
 239 changes made in an NMU: in a `3.0 (quilt)' package the delta from the
 240 previous upload is recorded in a new patch constructed by dpkg-source.
 241 .SH PACKAGE SOURCE FORMATS
 242 If you are not the maintainer, you do not need to worry about the
 243 source format of the package.  You can just make changes as you like
 244 in git.  If the package is a `3.0 (quilt)' package, the patch stack
 245 will usually not be represented in the git history.
 246
 247 If you are the maintainer of a non-native package, you currently have
 248 two sensible options:
 249
 250 Firstly, you can regard your git history as primary, and the archive
 251 as an export format.  For example, you could maintain topic branches
 252 in git and a fast-forwarding release branch; or you could do your work
 253 directly in a merging way on the
 254 .BI dgit/ suite
 255 branches.  If you do this you should probably use a `1.0' format
 256 source package.  In the archive, the delta between upstream will be
 257 represented in the single Debian patch.
 258
 259 Secondly, you can regard your quiltish patch stack in the archive as
 260 primary.  You will have to use other tools besides dgit to import and
 261 export this patch stack.  For `3.0 (quilt)' packages, dgit has to do
 262 more work to work around some braindamage in way dpkg-source handles
 263 changes made to this format.  See also the BUGS section.  We recommend
 264 against the use of `3.0 (quilt)'.
 265 .SH OPTIONS
 266 .TP
 267 .BR --dry-run | -n
 268 Go through the motions, fetching all information needed, but do not
 269 actually update the output(s).  For push, dgit does
 270 the required checks and leaves the new .dsc in a temporary file,
 271 but does not sign, tag, push or upload.
 272 .TP
 273 .BI -k keyid
 274 Use
 275 .I keyid
 276 for signing the tag and the upload.
 277 .TP
 278 .BR --no-sign
 279 does not sign tags or uploads (meaningful only with push).
 280 .TP
 281 .TP
 282 .BI -p package
 283 Specifies that we should process source package
 284 .I package
 285 rather than looking in debian/control or debian/changelog.
 286 Valid with dgit fetch and dgit pull, only.
 287 .TP
 288 .BR -N | --new
 289 The package may be new in this suite.  Without this, dgit will
 290 refuse to push.
 291 .TP
 292 .BI -D
 293 Prints debugging information to stderr.  Repeating the option produces
 294 more output (currently, up to -DD is meaningfully different).
 295 .TP
 296 .BI -c name = value
 297 Specifies a git configuration option.  dgit itself is also controlled
 298 by git configuration options.
 299 .TP
 300 .RI \fB--dget=\fR program |\fB--dput=\fR program |...
 301 Specifies alternative programs to use instead of
 302 .BR dget ,
 303 .BR dput ,
 304 .BR debsign ,
 305 .BR dpkg-buildpackage
 306 .BR sbuild ,
 307 or
 308 .BR mergechanges .
 309 .TP
 310 .RI \fB--dget:\fR option |\fB--dput:\fR option |...
 311 Specifies a single additional option to pass to
 312 .BR dget ,
 313 .BR dput ,
 314 .BR debsign ,
 315 .BR dpkg-buildpackage
 316 .BR sbuild ,
 317 or
 318 .BR mergechanges .
 319 Can be repeated as necessary.
 320 .TP
 321 .BI -C changesfile
 322 Specifies the .changes file which is to be uploaded.  By default
 323 dgit push looks for single .changes file in the parent directory whose
 324 filename suggests it is for the right package and version.
 325 .TP
 326 .BI --existing-package= package
 327 dgit push needs to canonicalise the suite name.  But currently
 328 there is no way to ask the archive to do this without knowing the
 329 name of an existing package.  Without --new we can just use the
 330 package we are trying to push.  But with --new that will not work, so
 331 we guess
 332 .B dpkg
 333 or use the value of this option.
 334 .TP
 335 .BR -h | --help
 336 Print a usage summary.
 337 .SH SEE ALSO
 338 \fBdget\fP(1),
 339 \fBdput\fP(1),
 340 \fBdebsign\fP(1),
 341 \fBgit-config\fP(1),
 342 \fBgit-buildpackage\fP(1),
 343 \fBdpkg-buildpackage\fP(1),
 344 .br
 345 https://wiki.debian.org/Alioth
 346 .SH CONFIGURATION
 347 dgit looks at the following git config keys to control its behaviour.
 348 You may set them with git-config (either in system-global or per-tree
 349 configuration), or provide
 350 .BI -c key = value
 351 on the dgit command line.
 352 .TP
 353 .BI dgit-suite. suite .distro
 354 .TP
 355 .BI dgit.default.distro
 356 .TP
 357 .BI dgit-distro. distro .username
 358 .TP
 359 .BI dgit-distro. distro .git-url
 360 .TP
 361 .BI dgit-distro. distro .git-user
 362 .TP
 363 .BI dgit-distro. distro .git-host
 364 .TP
 365 .BI dgit-distro. distro .git-proto
 366 .TP
 367 .BI dgit-distro. distro .git-path
 368 .TP
 369 .BI dgit-distro. distro .git-check
 370 .TP
 371 .BI dgit-distro. distro .git-create
 372 .TP
 373 .BI dgit-distro. distro .upload-host
 374 .TP
 375 .BI dgit-distro. distro .mirror
 376 .TP
 377 .BI dgit-distro. distro .archive-query
 378 .TP
 379 .BI dgit-distro. distro .archive-query-default-component
 380 .TP
 381 .BI dgit-distro. distro .sshdakls-user
 382 .TP
 383 .BI dgit-distro. distro .sshdakls-host
 384 .TP
 385 .BI dgit-distro. distro .sshdakls-dir
 386 .TP
 387 .BI dgit-distro. distro .ssh
 388 .TP
 389 .BR dgit.default. *
 390 for each
 391 .BR dgit-distro. \fIdistro\fR . *
 392 .SH BUGS
 393 We should be using some kind of vhost/vpath setup for the git repos on
 394 alioth, so that they can be moved later if and when this turns out to
 395 be a good idea.
 396
 397 Debian Policy needs to be updated to describe the new Vcs-Dgit-Master
 398 field (and to specify that it is an RC bug for that field to refer
 399 to an unavailable commit).
 400
 401 The method of canonicalising suite names is bizarre.  See the
 402 .B --existing-package
 403 option for one of the implications.
 404
 405 dgit push should perhaps do `git push origin', or something similar,
 406 by default.
 407
 408 Debian does not have a working rmadison server, so to find out what
 409 version of a package is in the archive, or to canonicalise suite
 410 names, we ssh directly into the ftpmaster server.
 411
 412 The mechanism for checking for and creating per-package repos on
 413 alioth is a hideous bodge.  One consequence is that dgit currently
 414 only works for people with push access.
 415
 416 Debian Maintainers are currently not able to push, as there is not
 417 currently any mechanism for determining and honouring the archive's
 418 ideas about access control.  Currently only DDs can push.
 419
 420 dgit's representation of format `3.0 (quilt)' source packages does not
 421 represent the patch stack.  Currently the patch series representation
 422 cannot round trip through the archive.  Ideally dgit would represent a
 423 quilty package with an origin commit of some kind followed by the
 424 patch stack as a series of commits followed by a pseudo-merge (to make
 425 the branch fast-forwarding).  This would also mean a new `dgit
 426 rebase-prep' command or some such to turn such a fast-forwarding
 427 branch back into a rebasing patch stack, and a `force' option to dgit
 428 push (perhaps enabled automatically by a note left by rebase-prep)
 429 which will make the required pseudo-merge.
 430
 431 If the dgit push fails halfway through, it should be restartable and
 432 idempotent.  However this is not true for the git tag operation.
 433 Also, it would be good to check that the proposed signing key is
 434 available before starting work.
 435
 436 dgit's handling of .orig.tar.gz is not very sophisticated.  Ideally
 437 the .orig.tar.gz could be transported via the git repo as git tags.
 438 Doing this is made more complicated by the possibility of a `3.0
 439 (quilt)' package with multiple .orig tarballs.
 440
 441 `3.0 (quilt)' packages have an additional difficulty: if these are
 442 edited in the most normal way, and then fed to dpkg-buildpackage,
 443 dpkg-source will add extra quilt patch metadata to the source tree
 444 during the source package build.  This extra metadata is then of
 445 course not included in the git history.  So dgit push needs to commit
 446 it for you, to make sure that the git history and archive contents are
 447 identical.  That this is necessary is a bug in the `3.0 (quilt)'
 448 format.
 449
 450 There should be an option which arranges for the `3.0 (quilt)'
 451 autocommit to not appear on your HEAD, but instead only in the
 452 remote tracking suite branch.
 453
 454 There should at the very least be some advice in the manpage about how
 455 to use dgit when the signing key is not available on the same machine
 456 as the build host.
 457
 458 The option parser requires values to be cuddled to the option name.
 459
 460 dgit assumes knowledge of the archive layout.  There appears to be no
 461 sane way to find the path in the archive pool of the .dsc for a
 462 particular suite.  I'm assured that the archive layout is a
 463 `well known algorithm' by now.
 464
 465 --dry-run often does not work with fetch, even though this is a
 466 logically plausible request.  (It fails, instead.)