X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=c569347e658bb6480e12072b0985c5dcef4670e1;hp=9ebc7b1694070a5b1387705a6d1a6886912101db;hb=2b5c351f4b03f0110f386e15c3f30b1747cbc62f;hpb=cfd5e47a4a0d485c2cbb93cccad40e8086de52ea diff --git a/dgit.1 b/dgit.1 index 9ebc7b16..c569347e 100644 --- a/dgit.1 +++ b/dgit.1 @@ -29,13 +29,21 @@ dgit \- git integration with the Debian archive .B dgit allows you to treats the Debian archive as if it were a git repository. See \fBdgit\fP(7) for detailed information about the data -model etc. +model, common problems likely to arise with certain kinds of package, +etc. -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. +The usual workflow is: +.br +1. \fBdgit clone\fR or \fBfetch\fR; +.br +2. make, do dev tests, and commit changes in git as desired; +.br +3. build packages for upload, using e.g. \fBdgit sbuild\fR +.br +4. do pre-upload tests of the proposed upload; +.br +5. \fBdgit push\fR. +.SH OPERATIONS .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 @@ -190,6 +198,14 @@ You will need similar enough versions of dgit on the build-host and the invocation host. The build-host needs gnupg installed, with your public key in its keyring (but not your private key, obviously). .TP +.B dgit setup-mergechangelogs +Configures a git merge helper for the file +.B debian/changelog +which uses +.BR dpkg-mergechangelogs . +You can use this in any git repository, not just ones used with +the other dgit operations. +.TP .B dgit quilt-fixup `3.0 (quilt)' format source packages need changes representing not only in-tree but also as patches in debian/patches. dgit quilt-fixup @@ -213,13 +229,13 @@ Tries to fetch a copy of the source code for the dgit-repos-server, as actually being used on the dgit git server, as a git tree. .SH OPTIONS .TP -.BR --dry-run | -n +.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 -.BR --damp-run | -L +.BR --damp-run " | " -L Go through many more of the motions: do everything that doesn't involve either signing things, or making changes on the public servers. @@ -239,7 +255,7 @@ 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 +.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" . @@ -253,17 +269,26 @@ from being run. the downside is simply that git clean may delete files you forgot to git add. .TP -.BR --clean=none | -wn +.BR --clean=git-ff " | " -wgf +The source tree should be cleaned, before building a source package +with one of the build options, using +.BR "git clean -xdff" . +This is like +"git clean -xdf" +but it also removes any subdirectories containing different git +trees (which only unusual packages are likely to create). +.TP +.BR --clean=none " | " -wn Do not clean the tree before building a source package. If there are files which are not in git, or if the build creates such files, a subsequent dgit push will fail. .TP -.BR --clean=dpkg-source | -wd +.BR --clean=dpkg-source " | " -wd Use dpkg-buildpackage to do the clean, 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 +.BR -N " | " --new The package may be new in this suite. Without this, dgit will refuse to push. .TP @@ -325,7 +350,7 @@ because the dgit git tree does not have a .B .pc directory.) .TP -.BR --quilt=nocheck | --no-quilt-fixup +.BR --quilt=nocheck " | " --no-quilt-fixup Do not check whether up source format `3.0 (quilt)' metadata needs fixing up. If you use this option and the metadata did in fact need fixing up, dgit push will fail. @@ -360,7 +385,7 @@ Passed to dpkg-genchanges (eventually). Specifies a single additional option to pass, eventually, to dpkg-genchanges. .TP -.RI \fB--curl=\fR program |\fB--dput=\fR program |... +.RI \fB--curl=\fR program " | \fB--dput=\fR" program " |..." Specifies alternative programs to use instead of .BR curl , .BR dput , @@ -398,7 +423,7 @@ git to access dgit-repos, only git's idea of what ssh to use (eg, .BR GIT_SSH ) is relevant. .TP -.RI \fB--curl:\fR option |\fB--dput:\fR option |... +.RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..." Specifies a single additional option to pass to .BR curl , .BR dput , @@ -612,25 +637,8 @@ and other subprograms and modules used by dgit are affected by various environment variables. Consult the documentaton for those programs for details. .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. - -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 and run psql there to -access the database. - -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. +Debian Maintainers are currently not able to push, as the project +lacks a list of their ssh keys (!) dgit's git representation of format `3.0 (quilt)' source packages does not represent the patch stack as git commits. Currently the patch @@ -664,10 +672,6 @@ remote tracking suite branch. The option parser requires values to be cuddled to the option name. -dgit assumes knowledge of the archive database. (The information dgit -needs is not currently available via any public online service with a -well-defined interface, let alone a secure one.) - --dry-run does not always work properly, as not doing some of the git fetches may result in subsequent actions being different. Doing a non-dry-run dgit fetch first will help.