X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=dgit.1;h=14b7d1ed42e88973a68e841557390e39a867db3c;hb=08a4cefb989b93dec53d5357e3b40d04340884cc;hp=9a9f32e2730633b64eca7949df7aa4ccbc72917e;hpb=2c790fefb4b5d606005a9161faaf740d0377756b;p=dgit.git diff --git a/dgit.1 b/dgit.1 index 9a9f32e2..14b7d1ed 100644 --- a/dgit.1 +++ b/dgit.1 @@ -12,12 +12,15 @@ dgit \- git integration with the Debian archive [\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 +[\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,31 +32,155 @@ 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. +.TP +\fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir] +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/ \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/ suite +into the current branch. +.TP +\fBdgit build\fR ... +Runs +.B git-buildpackage +with some suitable options. Options and argumments after build +will be passed on to git-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 and signing should be left to dgit push. +.TP +\fBdgit sbuild\fR ... +Constructs the source package, and uses 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. +.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 +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. -.SH MODEL AND WORKFLOW + +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 if necessary. +You can explicitly request that dgit do just this +dgit quilt-fixup. + +dgit push always uses the package, suite and version specified in the +debian/changelog and the .dsc, which must agree. +.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). + +It is not normally necessary to run dgit quilt-fixup explicitly; +where necessary it is done as part of 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 +.RB ( "git checkout dgit/" \fIsuite\fR) +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. + +If you are lucky the other uploaders have also used dgit and +integrated the other relevant git history; if not you can fetch it +into your tree and cherry-pick etc. as you wish. +.SH WORKFLOW - INTEGRATING BETWEEN DGIT AND OTHER GIT HISTORY +If you are the maintainer of a package dealing with uploads made +without dgit, you will probably want to merge the synthetic commits +(made by dgit to represent the uploads) into your git history. +Normally you can just merge the dgit branch into your own master, or +indeed if you do your work on the dgit local suite branch +.BI dgit/ suite +you can just use dgit pull. + +However the first time dgit is used it will generate a new origin +commit from the archive which won't be linked into the rest of your +git history. You will need to merge this. + +If last upload was in fact made with git, you should usually proceed +as follows: identify the commit which was actually used to build the +package. (Hopefully you have a tag for this.) Check out the dgit +branch +.RB ( "git checkout dgit/" \fIsuite\fR) +and merge that other commit +.RB ( "git merge debian/" \fIversion\fR). +Hopefully this merge will be trivial because the two trees should +be the same. The resulting branch head can be merged into your +working branches +.RB ( "git checkout master && git merge dgit/" \fIsuite\fR). + +If last upload was not made with git, a different approach is required +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 +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; +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 +.BR "dgit push" +to actually upload the result. +.SH MODEL You may use any suitable git workflow with dgit, provided you satisfy dgit's requirements: @@ -73,6 +200,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. @@ -93,6 +225,39 @@ dgit expects repos that it works with to have a 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. + +dgit does not (currently) represent the orig tarball(s) in git; nor +does it represent the patch statck of a `3.0 (quilt)' package. The +orig tarballs are downloaded and kept in the parent directory, as with +a traditional (non-gitish) dpkg-source workflow. + +To a user looking at the archive, changes pushed using dgit look like +changes made in an NMU: in a `3.0 (quilt)' package the delta from the +previous upload is recorded in a new patch constructed by dpkg-source. +.SH PACKAGE SOURCE FORMATS +If you are not the maintainer, you do not need to worry about the +source format of the package. You can just make changes as you like +in git. If the package is a `3.0 (quilt)' package, the patch stack +will usually not be represented in the git history. + +If you are the maintainer of a non-native package, you currently have +two sensible options: + +Firstly, you can regard your git history as primary, and the archive +as an export format. For example, you could maintain topic branches +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 some braindamage in way dpkg-source handles +changes made to this format. See also the BUGS section. We recommend +against the use of `3.0 (quilt)'. .SH OPTIONS .TP .BR --dry-run | -n @@ -128,13 +293,26 @@ 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. +.RI \fB--dget=\fR program |\fB--dput=\fR program |... +Specifies alternative programs to use instead of +.BR dget , +.BR dput , +.BR debsign , +.BR dpkg-buildpackage +.BR sbuild , +or +.BR mergechanges . .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--dget:\fR option |\fB--dput:\fR option |... +Specifies a single additional option to pass to +.BR dget , +.BR dput , +.BR debsign , +.BR dpkg-buildpackage +.BR sbuild , +or +.BR mergechanges . +Can be repeated as necessary. .TP .BI -C changesfile Specifies the .changes file which is to be uploaded. By default @@ -146,10 +324,21 @@ 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 +we guess .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. +or use the value of this option. +.TP +.BR -h | --help +Print a usage summary. +.SH SEE ALSO +\fBdget\fP(1), +\fBdput\fP(1), +\fBdebsign\fP(1), +\fBgit-config\fP(1), +\fBgit-buildpackage\fP(1), +\fBdpkg-buildpackage\fP(1), +.br +https://wiki.debian.org/Alioth .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 @@ -161,10 +350,12 @@ on the dgit command line. .TP .BI dgit.default.distro .TP -.BI dgit.default.username +.BI dgit-distro. distro .username .TP .BI dgit-distro. distro .git-url .TP +.BI dgit-distro. distro .git-user +.TP .BI dgit-distro. distro .git-host .TP .BI dgit-distro. distro .git-proto @@ -183,6 +374,12 @@ on the dgit command line. .TP .BI dgit-distro. distro .archive-query-default-component .TP +.BI dgit-distro. distro .sshdakls-user +.TP +.BI dgit-distro. distro .sshdakls-host +.TP +.BI dgit-distro. distro .sshdakls-dir +.TP .BI dgit-distro. distro .ssh .TP .BR dgit.default. * @@ -199,11 +396,15 @@ to an unavailable commit). The method of canonicalising suite names is bizarre. See the .B --existing-package -option for one of the implication.s +option for one of the implications. dgit push should perhaps do `git push origin', or something similar, by default. +Debian does not have a working rmadison server, so to find out what +version of a package is in the archive, or to canonicalise suite +names, we ssh directly into the ftpmaster server. + 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. @@ -233,8 +434,22 @@ 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. +`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. + +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.