X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=f97e458fb0b15fe75cffabd64bed9c7812fe46d7;hp=c3fa7f31ba9d8e2bb1bc3ebf78356aa18f72589d;hb=28789232f5edcc1c24bbb4bfe3b5e12119e9886e;hpb=2b5c8f502e49ff9d32d8073f178bf30650b5448d diff --git a/dgit.1 b/dgit.1 index c3fa7f31..f97e458f 100644 --- a/dgit.1 +++ b/dgit.1 @@ -5,19 +5,22 @@ 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] +\fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR] .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] +[\fIdgit\-opts\fP] \fBbuild\fP|\fBsbuild\fP|\fBbuild-source\fP +[\fIbuild\-opts\fp] .br .B dgit [\fIdgit\-opts\fP] \fBpush\fP [\fIdgit\-opts\fP] [\fIsuite\fP] +.br +.B dgit +[\fIdgit\-opts\fP] \fIaction\fR ... .SH DESCRIPTION .B dgit treats the Debian archive as a version control system, and @@ -29,40 +32,122 @@ as .B dgit-repos which lives outside the Debian archive (currently, on Alioth). -.B dgit clone +The usual workflow is: 1. clone or fetch; 2. make and commit changes +in git as desired; 3. run dgit build, dgit sbuild or dgit +build-source, or generate the source and binary packages for upload +some other way; 4. do pre-upload tests of the proposed upload; 5. run +dgit push. +.TP +\fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR] +Consults the archive and dgit-repos to construct the git view of +history for +.I package +in +.I suite +.RB ( sid +by default) +in a new directory (named +.BI ./ package +by default); +also, downloads any necessary orig tarballs. + +The suite's git tip is +left on the local branch +.BI dgit/ suite +ready for work, and on the corresponding dgit remote tracking branch. +Also, the +.B origin +remote will be set up to point to the package's dgit-repos tree +for the distro to which +.I suite +belongs. +.TP +\fBdgit fetch\fR [\fIsuite\fP] +Consults the archive and git-repos to update the git view of +history for a specific suite (and downloads any necessary orig +tarballs), and updates the remote tracking branch +.BR remotes/dgit/dgit/ \fIsuite\fR. +If the current branch is +.BI dgit/ suite +then dgit fetch defaults to +.IR suite ; +otherwise it parses debian/changelog and uses the suite specified +there. +.TP +\fBdgit pull\fR [\fIsuite\fP] +Does dgit fetch, and then merges the new head of the remote tracking +branch +.BI remotes/dgit/dgit/ suite +into the current branch. +.TP +\fBdgit build\fR ... +Runs +.B dpkg-buildpackage +with some suitable options. Options and argumments after build +will be passed on to dpkg-buildpackage. It is not necessary to use +dgit build when using dgit; it is OK to use any approach which ensures +that the generated source package corresponds to the relevant git +commit. + +Tagging, signing and actually uploading should be left to dgit push. +.TP +\fBdgit build-source\fR ... +Builds the source package, and a changes file for a prospective +source-only upload, using +.BR dpkg-source . +The output is left in +.IR package \fB_\fR version \fB.dsc\fR 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 +.IR package \fB_\fR version \fB_source.changes\fR. + +Tagging, signing and actually uploading should be left to dgit push. +.TP +\fBdgit sbuild\fR ... +Constructs the source package, uses +.B sbuild +to do a binary build, and uses mergechanges to merge the source and +binary changes files. Options and argumments after sbuild will be +passed on to sbuild. Changes files matching +.IB package _ version _*.changes +in the parent directory will be removed; the output is left in +.IR package \fB_\fR version \fB_multi.changes\fR. + +Tagging, signing and actually uploading should be left to dgit push. +.TP +\fBdgit git-build\fR ... +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. +with some suitable options. Options and argumments after git-build +will be passed on to git-buildpackage. +Tagging, signing and actually uploading should be left to dgit push. +.TP .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. (For a format `3.0 (quilt)' source package, dgit push -may also have to make a commit on your current branch to contain -quilt metadata. It will do this automatically.) +Does an `upload', pushing the current HEAD to the archive (as a source +package) and to dgit-repos (as git commits). The package must already +have been built ready for upload, with the .dsc and .changes +left in the parent directory. + +In more detail: dgit push checks that the current HEAD corresponds to +the .dsc. It then pushes the HEAD to the suite's dgit-repos branch, +makes a signed git tag, edits the .dsc to contain the dgit metadata +field, runs debsign to sign the upload (.dsc and .changes), pushes the +signed tag, and finally uses dput to upload the .changes to the +archive. +dgit push always uses the package, suite and version specified in the +debian/changelog and the .dsc, which must agree. + +If dgit push fails while uploading, it is fine to simply retry the +dput on the .changes file at your leisure. +.TP .B dgit quilt-fixup -looks to see if there is quilt patch metadata left over by dpkg-source --b, and if so makes a git commit of it. This is normally done -automatically by dgit push. dgit quilt-fixup takes no additional -arguments. Note that it will only process a patch generated by -dpkg-source for the most recent version (according to the -debia/changelog). +Looks to see if the tree is one which dpkg-source cannot properly +represent. If it isn't, dgit will fix it up for you (in quilt terms, +by making a new debian/ patch containing your unquilty changes) and +make a commit of the changes it has made. + +This is normally done automatically by dgit build and dgit push. .SH WORKFLOW - SIMPLE It is always possible with dgit to clone or fetch a package, make changes in git (using git-commit) on the suite branch @@ -71,7 +156,7 @@ and then dgit push. You can use whatever gitish techniques you like to construct the commit to push; the only requirement is that it is a descendant of the state of the archive, as provided by dgit in the remote tracking branch -.BR remotes/dgit/ \fIsuite\fR. +.BR remotes/dgit/dgit/ \fIsuite\fR. If you are lucky the other uploaders have also used dgit and integrated the other relevant git history; if not you can fetch it @@ -106,13 +191,13 @@ to start using dgit. First, do .B dgit fetch (or clone) to obtain a git history representation of what's in the archive and record it in the -.BI remotes/dgit/ suite +.BI remotes/dgit/dgit/ suite tracking branch. Then somehow, using your other git history plus appropriate diffs and cherry picks from the dgit remote tracking branch, construct a git commit whose tree corresponds to the tree to use for the next upload. If that commit-to-be-uploaded is not a descendant of the dig remote tracking branch, check it out and say -.BR "git merge -s ours remotes/dgit/" \fIsuite\fR; +.BR "git merge -s ours remotes/dgit/dgit/" \fIsuite\fR; that tells git that we are deliberately throwing away any differences between what's in the archive and what you intend to upload. Then run @@ -138,6 +223,11 @@ 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 will also (by default) make signed tags called +.BI debian/ version +and push them to dgit-repos, but nothing depends on these tags +existing. + dgit push can operate on any commit which is a descendant of the current dgit/suite tip in dgit-repos. @@ -182,14 +272,34 @@ in git and a fast-forwarding release branch; or you could do your work directly in a merging way on the .BI dgit/ suite branches. If you do this you should probably use a `1.0' format -source package. In the archive, the delta between upstream will be -represented in the single Debian patch. - -Secondly, you can regard your quiltish patch stack in the archive as -primary. You will have to use other tools besides dgit to import and -export this patch stack. For `3.0 (quilt)' packages, dgit has to do -more work to work around quilt braindamage. See also the BUGS -section. We recommend against the use of `3.0 (quilt)'. +source package if you can. In the archive, the delta between upstream +will be represented in the single Debian patch. + +Secondly, you can use `3.0 (quilt)', and regard your quiltish patch +stack in the archive as primary. You will have to use other tools +besides dgit to import and export this patch stack. But see below: +.SH FORMAT 3.0 (QUILT) +For a format `3.0 (quilt)' source package, dgit may have to make a +commit on your current branch to contain metadata used by quilt and +dpkg-source. + +This is because (i) the `3.0 (quilt)' source format cannot represent +certain trees, and (ii) packing up a tree in `3.0 (quilt)' and then +unpacking it does not always yield the same tree. Instead, +dpkg-source insists on the trees having extra quilty metadata and +patch files in the debian/ and .pc/ directories, which dpkg-source +sometimes modifies. + +dgit will automatically work around this braindamage for you when +building and pushing. The only thing you need to know is that dgit +build, sbuild, etc., may make a new commit on your HEAD. If you're +not a quilt user this commit won't contain any changes to files you +care about. + +You can explicitly request that dgit do just this fixup, by running +dgit quilt-fixup. + +We recommend against the use of `3.0 (quilt)'. .SH OPTIONS .TP .BR --dry-run | -n @@ -213,10 +323,40 @@ Specifies that we should process source package rather than looking in debian/control or debian/changelog. Valid with dgit fetch and dgit pull, only. .TP +.BR --clean=git | -wg +The source tree should be cleaned, before building a source package +with one of the build options, using +.BR "git clean -xdf" . +This will delete all files which are not tracked by git. +.TP +.BR --clean=none | -wn +Do not clean the tree before building a source package. If there are +files which are not in git, a subsequent dgit push will fail. +.TP +.BR --clean=dpkg-source | -wd +Use dpkg-buildpackage to do the build, so that the source package +is cleaned by dpkg-source running the package's clean target. +This is the default. It requires the package's build dependencies. +.TP .BR -N | --new The package may be new in this suite. Without this, dgit will refuse to push. .TP +.BR --ignore-dirty +Do not complain if the working tree does not match your git HEAD. +This can be useful with build, if you plan to commit later. (dgit +push will still ensure that the .dsc you upload and the git tree +you push are identical, so this option won't make broken pushes.) + +This option may not work properly on `3.0 (quilt)' packages, as in +that case dgit needs to use and perhaps commit parts of your working +tree. +.TP +.BR --no-quilt-fixup +Do not fix up source format `3.0 (quilt)' metadata. If you use this +option and the package did in fact need fixing up, dgit push will +fail. +.TP .BI -D Prints debugging information to stderr. Repeating the option produces more output (currently, up to -DD is meaningfully different). @@ -225,18 +365,68 @@ more output (currently, up to -DD is meaningfully different). 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. +.RI \fB-v\fR version |\fB-m\fR maintaineraddress +Passed to dpkg-genchanges (eventually). +.TP +.RI \fB--ch:\fR option +Specifies a single additional option to pass, eventually, to +dpkg-genchanges. +.TP +.RI \fB--dget=\fR program |\fB--dput=\fR program |... +Specifies alternative programs to use instead of +.BR dget , +.BR dput , +.BR debsign , +.BR dpkg-source , +.BR dpkg-buildpackage , +.BR dpkg-genchanges , +.BR sbuild , +or +.BR mergechanges . +This applies only when the program is invoked directly by dgit. +.TP +.RI \fB--dget:\fR option |\fB--dput:\fR option |... +Specifies a single additional option to pass to +.BR dget , +.BR dput , +.BR debsign , +.BR dpkg-source , +.BR dpkg-buildpackage , +.BR dpkg-genchanges , +.BR sbuild , +or +.BR mergechanges . +Can be repeated as necessary. +This applies only when the program is invoked directly by dgit. +Usually, for passing options to dpkg-genchanges, use +.BR --ch: \fIoption\fR. +.TP +.BR -d "\fIdistro\fR | " --distro= \fIdistro\fR +Specifies that the suite to be operated on is part of distro +.IR distro . +This overrides the default value found from the git config option +.BR dgit-suite. \fIsuite\fR .distro . +The only effect is that other configuration variables (used +for accessing the archive and dgit-repos) used are +.BR dgit-distro. \fIdistro\fR .* . + +If your suite is part of a distro that dgit already knows about, you +can use this option to make dgit work even if your dgit doesn't know +about the suite. For example, specifying +.B -ddebian +will work when the suite is an unknown suite in the Debian archive. + +To define a new distro it is necessary to define methods and URLs +for fetching (and, for dgit push, altering) a variety of information both +in the archive and in dgit-repos. How to do this is not yet +documented, and currently the arrangements are unpleasant. See +BUGS. .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. +filename suggests it is for the right package and version - or, +if there is a _multi.changes file, dgit uses that. .TP .BI --existing-package= package dgit push needs to canonicalise the suite name. But currently @@ -301,6 +491,8 @@ on the dgit command line. .TP .BI dgit-distro. distro .ssh .TP +.BI dgit-distro. distro .keyid +.TP .BR dgit.default. * for each .BR dgit-distro. \fIdistro\fR . * @@ -353,14 +545,18 @@ 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. -`3.0 (quilt)' packages have an additional difficulty: if these are -edited in the most normal way, and then fed to dpkg-buildpackage, -dpkg-source will add extra quilt patch metadata to the source tree -during the source package build. This extra metadata is then of -course not included in the git history. So dgit push needs to commit -it for you, to make sure that the git history and archive contents are -identical. That this is necessary is a bug in the `3.0 (quilt)' -format. +dgit's build functions, and dgit push, should not make any changes to +your current HEAD. Sadly this is necessary for packages in the `3.0 +(quilt)' source format. This is ultimately due to design problems in +quilt and dpkg-source. + +There should be an option which arranges for the `3.0 (quilt)' +autocommit to not appear on your HEAD, but instead only in the +remote tracking suite branch. + +There should at the very least be some advice in the manpage about how +to use dgit when the signing key is not available on the same machine +as the build host. The option parser requires values to be cuddled to the option name.