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
  16 [\fIgit\-buildpackage\-opts\fP|\fIdpkg\-buildpackage\-opts\fp]
  17 .br
  18 .B dgit
  19 [\fIdgit\-opts\fP] \fBpush\fP [\fIdgit\-opts\fP]
  20 [\fIsuite\fP]
  21 .SH DESCRIPTION
  22 .B dgit
  23 treats the Debian archive as a version control system, and
  24 bidirectionally gateways between the archive and git.  The git view of
  25 the package can contain the usual upstream git history, and will be
  26 augmented by commits representing uploads done by other developers not
  27 using dgit.  This git history is stored in a canonical location known
  28 as
  29 .B dgit-repos
  30 which lives outside the Debian archive (currently, on Alioth).
  31
  32 .B dgit clone
  33 and
  34 .B dgit fetch
  35 consult the archive and dgit-repos and fetch and/or construct the
  36 git view of the history.  With clone, the destination directory (by
  37 default, the package name in the current directory) will be created,
  38 and the new directory's `origin' remote will be set up to point to
  39 the package's dgit-repos tree.
  40
  41 .B dgit build
  42 runs
  43 .B git-buildpackage
  44 with some suitable options.  Options after
  45 .B build
  46 will be passed on to git-buildpackage.  It is not necessary to
  47 use dgit build; it is OK to use any approach which ensures that
  48 the generated source package corresponds to the relevant git commit.
  49 Tagging and signing should be left to dgit push.
  50
  51 .B dgit push
  52 does an `upload', pushing the current HEAD to the archive (as a source
  53 package) and to dgit-repos (as git commits).  This also involves
  54 making a signed git tag, and signing the files to be uploaded to the
  55 archive.
  56 .SH MODEL AND WORKFLOW
  57 You may use any suitable git workflow with dgit, provided you
  58 satisfy dgit's requirements:
  59
  60 dgit maintains a pseudo-remote called
  61 .BR dgit ,
  62 with one branch per suite.  This remote cannot be used with
  63 plain git.
  64
  65 The
  66 .B dgit-repos
  67 repository for each package contains one ref per suite named
  68 \fBrefs/dgit/\fR\fIsuite\fR.  These should be pushed to only by
  69 dgit.  They are fast forwarding.  Each push on this branch
  70 corresponds to an upload (or attempted upload).
  71
  72 However, it is perfectly fine to have other branches in dgit-repos;
  73 normally the dgit-repos repo for the package will be accessible via
  74 the remote name `origin'.
  75
  76 dgit push can operate on any commit which is a descendant of the
  77 current dgit/suite tip in dgit-repos.
  78
  79 Uploads made by dgit contain an additional field
  80 .B Vcs-Dgit-Master
  81 in the source package .dsc.  (This is added by dgit push.)
  82 This specifies a commit (an ancestor of the dgit/suite
  83 branch) whose tree is identical to the unpacked source upload.
  84
  85 Uploads not made by dgit are represented in git by commits which are
  86 synthesised by dgit.  The tree of each such commit corresponds to the
  87 unpacked source; there is an origin commit with the contents, and a
  88 psuedo-merge from last known upload - that is, from the contents of
  89 the dgit/suite branch.
  90
  91 dgit expects repos that it works with to have a
  92 .B dgit
  93 remote.  This refers to the well-known dgit-repos location
  94 (currently, the dgit-repos project on Alioth).  dgit fetch updates
  95 the remote tracking branch for dgit/suite.
  96 .SH OPTIONS
  97 .TP
  98 .BR --dry-run | -n
  99 Go through the motions, fetching all information needed, but do not
 100 actually update the output(s).  For push, dgit does
 101 the required checks and leaves the new .dsc in a temporary file,
 102 but does not sign, tag, push or upload.
 103 .TP
 104 .BI -k keyid
 105 Use
 106 .I keyid
 107 for signing the tag and the upload.
 108 .TP
 109 .BR --no-sign
 110 does not sign tags or uploads (meaningful only with push).
 111 .TP
 112 .TP
 113 .BI -p package
 114 Specifies that we should process source package
 115 .I package
 116 rather than looking in debian/control or debian/changelog.
 117 Valid with dgit fetch and dgit pull, only.
 118 .TP
 119 .BR -N | --new
 120 The package may be new in this suite.  Without this, dgit will
 121 refuse to push.
 122 .TP
 123 .BI -D
 124 Prints debugging information to stderr.  Repeating the option produces
 125 more output (currently, up to -DD is meaningfully different).
 126 .TP
 127 .BI -c name = value
 128 Specifies a git configuration option.  dgit itself is also controlled
 129 by git configuration options.
 130 .TP
 131 .RI \fB--dget=\fR program |\fB--dput=\fR program |\fB--debsign=\fR program
 132 Specifies alternative programs to use instead of dget, dput
 133 or debsign.
 134 .TP
 135 .RI \fB--dget:\fR option |\fB--dput:\fR option |\fB--debsign:\fR option
 136 Specifies a single additional option to pass to dget, dput or
 137 debsign.  Use repeatedly if multiple additional options are required.
 138 .TP
 139 .BI -C changesfile
 140 Specifies the .changes file which is to be uploaded.  By default
 141 dgit push looks for single .changes file in the parent directory whose
 142 filename suggests it is for the right package and version.
 143 .TP
 144 .BI --existing-package= package
 145 dgit push needs to canonicalise the suite name.  But currently
 146 there is no way to ask the archive to do this without knowing the
 147 name of an existing package.  Without --new we can just use the
 148 package we are trying to push.  But with --new that will not work, so
 149 we guess that
 150 .B dpkg
 151 exists in the target suite.  If it doesn't, you can use this option to
 152 specify a package which does.  If the suite is empty, bad luck.
 153 .SH CONFIGURATION
 154 dgit looks at the following git config keys to control its behaviour.
 155 You may set them with git-config (either in system-global or per-tree
 156 configuration), or provide
 157 .BI -c key = value
 158 on the dgit command line.
 159 .TP
 160 .BI dgit-suite. suite .distro
 161 .TP
 162 .BI dgit.default.distro
 163 .TP
 164 .BI dgit.default.username
 165 .TP
 166 .BI dgit-distro. distro .git-url
 167 .TP
 168 .BI dgit-distro. distro .git-host
 169 .TP
 170 .BI dgit-distro. distro .git-proto
 171 .TP
 172 .BI dgit-distro. distro .git-path
 173 .TP
 174 .BI dgit-distro. distro .git-check
 175 .TP
 176 .BI dgit-distro. distro .git-create
 177 .TP
 178 .BI dgit-distro. distro .upload-host
 179 .TP
 180 .BI dgit-distro. distro .mirror
 181 .TP
 182 .BI dgit-distro. distro .archive-query
 183 .TP
 184 .BI dgit-distro. distro .archive-query-default-component
 185 .TP
 186 .BI dgit-distro. distro .ssh
 187 .TP
 188 .BR dgit.default. *
 189 for each
 190 .BR dgit-distro. \fIdistro\fR . *
 191 .SH BUGS
 192 We should be using some kind of vhost/vpath setup for the git repos on
 193 alioth, so that they can be moved later if and when this turns out to
 194 be a good idea.
 195
 196 Debian Policy needs to be updated to describe the new Vcs-Dgit-Master
 197 field (and to specify that it is an RC bug for that field to refer
 198 to an unavailable commit).
 199
 200 The method of canonicalising suite names is bizarre.  See the
 201 .B --existing-package
 202 option for one of the implication.s
 203
 204 dgit push should perhaps do `git push origin', or something similar,
 205 by default.
 206
 207 The mechanism for checking for and creating per-package repos on
 208 alioth is a hideous bodge.  One consequence is that dgit currently
 209 only works for people with push access.
 210
 211 Debian Maintainers are currently not able to push, as there is not
 212 currently any mechanism for determining and honouring the archive's
 213 ideas about access control.  Currently only DDs can push.
 214
 215 dgit's representation of format `3.0 (quilt)' source packages does not
 216 represent the patch stack.  Currently the patch series representation
 217 cannot round trip through the archive.  Ideally dgit would represent a
 218 quilty package with an origin commit of some kind followed by the
 219 patch stack as a series of commits followed by a pseudo-merge (to make
 220 the branch fast-forwarding).  This would also mean a new `dgit
 221 rebase-prep' command or some such to turn such a fast-forwarding
 222 branch back into a rebasing patch stack, and a `force' option to dgit
 223 push (perhaps enabled automatically by a note left by rebase-prep)
 224 which will make the required pseudo-merge.
 225
 226 If the dgit push fails halfway through, it should be restartable and
 227 idempotent.  However this is not true for the git tag operation.
 228 Also, it would be good to check that the proposed signing key is
 229 available before starting work.
 230
 231 dgit's handling of .orig.tar.gz is not very sophisticated.  Ideally
 232 the .orig.tar.gz could be transported via the git repo as git tags.
 233 Doing this is made more complicated by the possibility of a `3.0
 234 (quilt)' package with multiple .orig tarballs.
 235
 236 The error messages are often unhelpfully terse and tend to refer to
 237 line numbers in dgit.
 238
 239 The option parser requires values to be cuddled to the option name.
 240
 241 dgit assumes knowledge of the archive layout.  There appears to be no
 242 sane way to find the path in the archive pool of the .dsc for a
 243 particular suite.  I'm assured that the archive layout is a
 244 `well known algorithm' by now.
 245
 246 --dry-run often does not work with fetch, even though this is a
 247 logically plausible request.  (It fails, instead.)