diff options
Diffstat (limited to 'dgit.1')
| -rw-r--r-- | dgit.1 | 244 |
1 files changed, 244 insertions, 0 deletions
@@ -0,0 +1,244 @@ +.TH dgit 1 "" "Debian Project" "dgit" +.SH NAME +dgit \- git integration with the Debian archive +. +.SH SYNOPSIS +.B dgit +[\fIdgit\-opts\fP] \fBclone\fP [\fIdgit\-opts\fP] +\fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir] +.br +.B dgit +[\fIdgit\-opts\fP] \fBfetch\fP|\fBpull\fP [\fIdgit\-opts\fP] +[\fIsuite\fP] +.br +.B dgit +[\fIdgit\-opts\fP] \fBbuild\fP +[\fIgit\-buildpackage\-opts\fP|\fIdpkg\-buildpackage\-opts\fp] +.br +.B dgit +[\fIdgit\-opts\fP] \fBpush\fP [\fIdgit\-opts\fP] +[\fIsuite\fP] +.SH DESCRIPTION +.B dgit +treats the Debian archive as a version control system, and +bidirectionally gateways between the archive and git. The git view of +the package can contain the usual upstream git history, and will be +augmented by commits representing uploads done by other developers not +using dgit. This git history is stored in a canonical location known +as +.B dgit-repos +which lives outside the Debian archive (currently, on Alioth). + +.B dgit clone +and +.B dgit fetch +consult the archive and dgit-repos and fetch and/or construct the +git view of the history. With clone, the destination directory (by +default, the package name in the current directory) will be created, +and the new directory's `origin' remote will be set up to point to +the package's dgit-repos tree. + +.B dgit build +runs +.B git-buildpackage +with some suitable options. Options after +.B build +will be passed on to git-buildpackage. It is not necessary to +use dgit build; it is OK to use any approach which ensures that +the generated source package corresponds to the relevant git commit. +Tagging and signing should be left to dgit push. + +.B dgit push +does an `upload', pushing the current HEAD to the archive (as a source +package) and to dgit-repos (as git commits). This also involves +making a signed git tag, and signing the files to be uploaded to the +archive. +.SH MODEL AND WORKFLOW +You may use any suitable git workflow with dgit, provided you +satisfy dgit's requirements: + +dgit maintains a pseudo-remote called +.BR dgit , +with one branch per suite. This remote cannot be used with +plain git. + +The +.B dgit-repos +repository for each package contains one ref per suite named +\fBrefs/dgit/\fR\fIsuite\fR. These should be pushed to only by +dgit. They are fast forwarding. Each push on this branch +corresponds to an upload (or attempted upload). + +However, it is perfectly fine to have other branches in dgit-repos; +normally the dgit-repos repo for the package will be accessible via +the remote name `origin'. + +dgit push can operate on any commit which is a descendant of the +current dgit/suite tip in dgit-repos. + +Uploads made by dgit contain an additional field +.B Vcs-Dgit-Master +in the source package .dsc. (This is added by dgit push.) +This specifies a commit (an ancestor of the dgit/suite +branch) whose tree is identical to the unpacked source upload. + +Uploads not made by dgit are represented in git by commits which are +synthesised by dgit. The tree of each such commit corresponds to the +unpacked source; the single parent is the last known upload - that is, +the contents of the dgit/suite branch. + +dgit expects repos that it works with to have a +.B dgit +remote. This refers to the well-known dgit-repos location +(currently, the dgit-repos project on Alioth). dgit fetch updates +the remote tracking branch for dgit/suite. +.SH OPTIONS +.TP +.BR --dry-run | -n +Go through the motions, fetching all information needed, but do not +actually update the output(s). For push, dgit does +the required checks and leaves the new .dsc in a temporary file, +but does not sign, tag, push or upload. +.TP +.BI -k keyid +Use +.I keyid +for signing the tag and the upload. +.TP +.BR --no-sign +does not sign tags or uploads (meaningful only with push). +.TP +.TP +.BI -p package +Specifies that we should process source package +.I package +rather than looking in debian/control or debian/changelog. +Valid with dgit fetch and dgit pull, only. +.TP +.BR -N | --new +The package may be new in this suite. Without this, dgit will +refuse to push. +.TP +.BI -D +Prints debugging information to stderr. Repeating the option produces +more output (currently, up to -DD is meaningfully different). +.TP +.BI -c name = value +Specifies a git configuration option. dgit itself is also controlled +by git configuration options. +.TP +.RI \fB--dget=\fR program |\fB--dput=\fR program |\fB--debsign=\fR program +Specifies alternative programs to use instead of dget, dput +or debsign. +.TP +.RI \fB--dget:\fR option |\fB--dput:\fR option |\fB--debsign:\fR option +Specifies a single additional option to pass to dget, dput or +debsign. Use repeatedly if multiple additional options are required. +.TP +.BI -C changesfile +Specifies the .changes file which is to be uploaded. By default +dgit push looks for single .changes file in the parent directory whose +filename suggests it is for the right package and version. +.TP +.BI --existing-package= package +dgit push needs to canonicalise the suite name. But currently +there is no way to ask the archive to do this without knowing the +name of an existing package. Without --new we can just use the +package we are trying to push. But with --new that will not work, so +we guess that +.B dpkg +exists in the target suite. If it doesn't, you can use this option to +specify a package which does. If the suite is empty, bad luck. +.SH CONFIGURATION +dgit looks at the following git config keys to control its behaviour. +You may set them with git-config (either in system-global or per-tree +configuration), or provide +.BI -c key = value +on the dgit command line. +.TP +.BI dgit-suite. suite .distro +.TP +.BI dgit.default.distro +.TP +.BI dgit.default.username +.TP +.BI dgit-distro. distro .git-url +.TP +.BI dgit-distro. distro .git-host +.TP +.BI dgit-distro. distro .git-proto +.TP +.BI dgit-distro. distro .git-path +.TP +.BI dgit-distro. distro .git-check +.TP +.BI dgit-distro. distro .git-create +.TP +.BI dgit-distro. distro .upload-host +.TP +.BI dgit-distro. distro .mirror +.TP +.BI dgit-distro. distro .archive-query +.TP +.BI dgit-distro. distro .archive-query-default-component +.TP +.BI dgit-distro. distro .ssh +.TP +.BR dgit.default. * +for each +.BR dgit-distro. \fIdistro\fR . * +.SH BUGS +We should be using some kind of vhost/vpath setup for the git repos on +alioth, so that they can be moved later if and when this turns out to +be a good idea. + +Debian Policy needs to be updated to describe the new Vcs-Dgit-Master +field (and to specify that it is an RC bug for that field to refer +to an unavailable commit). + +The method of canonicalising suite names is bizarre. See the +.B --existing-package +option for one of the implication.s + +dgit push should perhaps do `git push origin', or something similar, +by default. + +The mechanism for checking for and creating per-package repos on +alioth is a hideous bodge. One consequence is that dgit currently +only works for people with push access. + +Debian Maintainers are currently not able to push, as there is not +currently any mechanism for determining and honouring the archive's +ideas about access control. Currently only DDs can push. + +dgit's representation of format `3.0 (quilt)' source packages does not +represent the patch stack. Currently the patch series representation +cannot round trip through the archive. Ideally dgit would represent a +quilty package with an origin commit of some kind followed by the +patch stack as a series of commits followed by a pseudo-merge (to make +the branch fast-forwarding). This would also mean a new `dgit +rebase-prep' command or some such to turn such a fast-forwarding +branch back into a rebasing patch stack, and a `force' option to dgit +push (perhaps enabled automatically by a note left by rebase-prep) +which will make the required pseudo-merge. + +If the dgit push fails halfway through, it should be restartable and +idempotent. However this is not true for the git tag operation. + +dgit's handling of .orig.tar.gz is not very sophisticated. Ideally +the .orig.tar.gz could be transported via the git repo as git tags. +Doing this is made more complicated by the possibility of a `3.0 +(quilt)' package with multiple .orig tarballs. + +The error messages are often unhelpfully terse and tend to refer to +line numbers in dgit. + +The option parser requires values to be cuddled to the option name. + +dgit assumes knowledge of the archive layout. There appears to be no +sane way to find the path in the archive pool of the .dsc for a +particular suite. I'm assured that the archive layout is a +`well known algorithm' by now. + +--dry-run often does not work with fetch, even though this is a +logically plausible request. (It fails, instead.) |