X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=dcf4408a4cccd38fec4d055db2d0225c73e0efad;hp=9705f0af2403abc84d2a07f07410dd6fb80125b0;hb=99f7db251233b9f6fb735e775e5ceb18a46e066d;hpb=e32ec25d687126038f441f4ffa11bc699de847dc diff --git a/dgit.1 b/dgit.1 index 9705f0af..dcf4408a 100644 --- a/dgit.1 +++ b/dgit.1 @@ -27,20 +27,23 @@ dgit \- git integration with the Debian archive [\fIdgit\-opts\fP] \fIaction\fR ... .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). - -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. +allows you to treat the Debian archive as if it were a git +repository. See \fBdgit\fP(7) for detailed information about the data +model, common problems likely to arise with certain kinds of package, +etc. + +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 @@ -93,7 +96,7 @@ into the current branch. \fBdgit build\fR ... Runs .B dpkg-buildpackage -with some suitable options. Options and argumments after build +with some suitable options. Options and arguments 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 @@ -123,7 +126,7 @@ Print a usage summary. 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 +binary changes files. Options and arguments 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 @@ -134,7 +137,7 @@ Tagging, signing and actually uploading should be left to dgit push. \fBdgit git-build\fR ... Runs .B git-buildpackage -with some suitable options. Options and argumments after git-build +with some suitable options. Options and arguments after git-build will be passed on to git-buildpackage. Tagging, signing and actually uploading should be left to dgit push. @@ -195,6 +198,28 @@ 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-new-tree +Configure the current working tree the way that dgit clone would have +set it up. Like running +.B dgit setup-useremail +and +.B setup-mergechangelogs +(but only does each thing if dgit is configured to do it automatically). +You can use these in any git repository, not just ones used with +the other dgit operations. +.TP +.B dgit setup-useremail +Set the working tree's user.name and user.email from the +distro-specific dgit configuration +.RB ( dgit-distro. \fIdistro\fR .user-name " and " .user-email ), +or DEBFULLNAME or DEBEMAIL. +.TP +.B dgit setup-mergechangelogs +Configures a git merge helper for the file +.B debian/changelog +which uses +.BR dpkg-mergechangelogs . +.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 @@ -218,13 +243,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. @@ -232,7 +257,11 @@ servers. .BI -k keyid Use .I keyid -for signing the tag and the upload. +for signing the tag and the upload. The default comes from the +distro's +.B keyid +config setting (see CONFIGURATION, below), or failing that, the +uploader trailer line in debian/changelog. .TP .BR --no-sign does not sign tags or uploads (meaningful only with push). @@ -244,24 +273,57 @@ 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" . -This will delete all files which are not tracked by git. +This will delete all files which are not tracked by git. Also, -wg +causes dgit to pass +.B -nc +to dpkg-buildpackage, which prevents the package's own clean target +from being run. + +--clean=git is useful when the package's clean target is troublesome; +the downside is simply that git clean may delete files you forgot to +git add. --clean=git can also avoid needing the build-dependencies. +.TP +.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 +.BR --clean=check " | " -wc +Merely check that the tree is clean (does not contain uncommitted +files), before building a source package. +.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. +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 -The package may be new in this suite. Without this, dgit will -refuse to push. +.BR --clean=dpkg-source-d " | " -wdd +Use +.B dpkg-buildpackage -d +to do the clean, so that the source package +is cleaned by dpkg-source running the package's clean target. +The build-dependencies are not checked (due to +.BR -d ), +which violates policy, but may work in practice. +.TP +.BR -N " | " --new +The package is or may be new in this suite. Without this, dgit will +refuse to push. It may (for Debian, will) be unable to access the git +history for any packages which have been newly pushed and have not yet +been published. .TP .BR --ignore-dirty Do not complain if the working tree does not match your git HEAD. @@ -300,7 +362,7 @@ as the Debian server will do this automatically when necessary. .BR --quilt=linear When fixing up source format `3.0 (quilt)' metadata, insist on generating a linear patch stack. If such a stack cannot be generated, -fail. +fail. This is the default for Debian. .TP .BR --quilt=auto When fixing up source format `3.0 (quilt)' metadata, prefer to @@ -321,18 +383,18 @@ 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. .TP .BI -D Prints debugging information to stderr. Repeating the option produces -more output (currently, up to -DD is meaningfully different). +more output (currently, up to -DDDD is meaningfully different). .TP .BI -c name = value -Specifies a git configuration option. dgit itself is also controlled -by git configuration options. +Specifies a git configuration option, to be used for this run. +dgit itself is also controlled by git configuration options. .TP .RI \fB-v\fR version "|\fB_\fR | " \fB--since-version=\fR version |\fB_\fR Specifies the @@ -356,7 +418,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 , @@ -394,7 +456,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 , @@ -417,7 +479,12 @@ Usually, for passing options to dpkg-genchanges, you should use See notes above regarding ssh and dgit. NB that --gpg:option is not supported (because debsign does not -have that facility). But see -k. +have that facility). +But see +.B -k +and the +.B keyid +distro config setting. .TP .BR -d "\fIdistro\fR | " --distro= \fIdistro\fR Specifies that the suite to be operated on is part of distro @@ -436,9 +503,8 @@ 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. +in the archive and in dgit-repos. +How to set this up is not yet documented. .TP .BI -C changesfile Specifies the .changes file which is to be uploaded. By default @@ -458,7 +524,7 @@ default, in .BI --build-products-dir= directory Specifies where to find the built files to be uploaded. By default, dgit looks in the parent directory -.BR .. ). +.RB ( .. ). .TP .BI --existing-package= package dgit push needs to canonicalise the suite name. Sometimes, dgit @@ -489,12 +555,14 @@ 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 +to construct the commits to push; +the only requirement is that what you push is a descendant of the state of the archive, as provided by dgit in the remote tracking branch .BR remotes/dgit/dgit/ \fIsuite\fR. -If you are using dgit to do an NMU, and don't know about the +If you are using dgit to do an NMU (in Debian), +and don't know about the maintainers' preferred packaging workflows, you should make your changes as a linear series of (logicially separated) commits on top of what's already in the archive. @@ -523,7 +591,7 @@ branch 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 +be very similar. The resulting branch head can be merged into your working branches .RB ( "git checkout master && git merge dgit/" \fIsuite\fR). @@ -544,188 +612,115 @@ 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: - -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 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. - -Uploads made by dgit contain an additional field -.B Dgit -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; there is an origin commit with the contents, and a -psuedo-merge from last known upload - that is, from 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. - -dgit does not (currently) represent the orig tarball(s) in git. The -orig tarballs are downloaded (by dgit clone) into the parent -directory, as with a traditional (non-gitish) dpkg-source workflow. -You need to retain these tarballs in the parent directory for dgit -build and dgit push. - -dgit repositories could be cloned with standard (git) methods. The -only exception is that for sourcefull builds / uploads the orig -tarball(s) need to be present in the parent directory. - -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 READ-ONLY DISTROS -Distros which do not maintain a set of dgit history git repositories -can still be used in a read-only mode with dgit. Currently Ubuntu -is configured this way. -.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. -.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 `3.0 (quilt)' source format represents the patch stack -as files in debian/patches/ actually inside the source tree. This -means that, taking the whole tree (as seen by git or ls) (i) -dpkg-source 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. - -dgit will automatically work around this for you when building and -pushing. The only thing you need to know is that dgit build, sbuild, -etc., may make new commits 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. - -If you are a quilt user you need to know that dgit's git trees are -`patches applied packaging branches' and do not contain the .pc -directory (which is used by quilt to record which patches are -applied). If you want to manipulate the patch stack you probably want -to be looking at tools like git-dpm. -.SH FILES IN THE SOURCE PACKAGE BUT NOT IN GIT -This section is mainly of interest to maintainers who want to use dgit -with their existing git history for the Debian package. - -Some developers like to have an extra-clean git tree which lacks files -which are normally found in source tarballs and therefore in Debian -source packages. For example, it is conventional to ship ./configure -in the source tarball, but some people prefer not to have it present -in the git view of their project. - -dgit requires that the source package unpacks to exactly the same -files as are in the git commit on which dgit push operates. So if you -just try to dgit push directly from one of these extra-clean git -branches, it will fail. - -As the maintainer you therefore have the following options: -.TP -\(bu -Persuade upstream that the source code in their git history and the -source they ship as tarballs should be identical. Of course simply -removing the files from the tarball may make the tarball hard for -people to use. -.IP -One answer is to commit the (maybe autogenerated) -files, perhaps with some simple automation to deal with conflicts and -spurious changes. This has the advantage that someone who clones -the git repository finds the program just as easy to build as someone -who uses the tarball. -.TP -\(bu -Have separate git branches which do contain the extra files, and after -regenerating the extra files (whenever you would have to anyway), -commit the result onto those branches. -.TP -\(bu -Provide source packages which lack the files you don't want -in git, and arrange for your package build to create them as needed. -This may mean not using upstream source tarballs and makes the Debian -source package less useful for people without Debian build -infrastructure. -.LP -Of course it may also be that the differences are due to build system -bugs, which cause unintended files to end up in the source package. -dgit will notice this and complain. You may have to fix these bugs -before you can unify your existing git history with dgit's. .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 +dgit can be configured via the git config system. +You may set keys with git-config (either in system-global or per-tree configuration), or provide .BI -c key = value on the dgit command line. +.LP +Settings likely to be useful for an end user include: +.TP +.BR dgit-suite. \fIsuite\fR .distro " \fIdistro\fR" +Specifies the distro for a suite. dgit keys off the suite name (which +appears in changelogs etc.), and uses that to determine the distro +which is involved. The config used is thereafter that for the distro. +.TP +.BI dgit.default.distro " distro" +The default distro for an unknown suite. .TP -.BI dgit-suite. suite .distro +.BR dgit-distro. \fIdistro\fR .readonly " " auto | a " | " true | t | y | 1 " | " false | f | n | 0 +Whether you have push access to the distro. +For Debian, it is OK to use auto, which uses readonly mode if you are +not pushing right now; +but, setting this to false will avoid relying on the mirror of the dgit +git repository server. .TP -.BI dgit.default.distro +.BI dgit-distro. distro .keyid +See also +.BR -k . +.TP +.BI dgit-distro. distro .mirror " url" .TP .BI dgit-distro. distro .username +Not relevant for Debian. .TP -.BI dgit-distro. distro .git-url +.BI dgit-distro. distro .upload-host +Might be useful if you have an intermediate queue server. +.TP +.BI dgit-distro. distro .user-name " " dgit-distro. distro .user-email +Values to configure for user.name and user.email in new git trees. If +not specified, the DEBFULLNAME and DEBEMAIL environment variables are +used, respectively. Only used if .setup-usermail is not disabled. +.TP +.BI dgit-distro. distro .setup-useremail +Whether to set user.name and user.email in new git trees. +True by default. Ignored for dgit setup-setup-useremail, which does it anyway. +.TP +.BI dgit-distro. distro .setup-mergechangelogs +Whether to setup a merge driver which uses dpkg-mergechangelogs for +debian/changelog. True by default. Ignored for dgit +setup-mergechangelogs, which does it anyway. +.TP +.BI dgit-distro. distro .cmd- cmd +Program to use instead of +.IR cmd . +Works like +.BR -- \fIcmd\fR = "... ." +.TP +.BI dgit-distro. distro .opts- cmd +Extra options to pass to +.IR cmd . +Works like +.BR -- \fIcmd\fR : "... ." +To pass several options, configure multiple values in git config +(with git config --add). The options for +.BI dgit.default.opts- cmd +.BI dgit-distro. distro /push.opts- cmd +and are all used, followed by options from dgit's command line. +.SH ACCESS CONFIGURATION +There are many other settings which specify how a particular distro's +services (archive and git) are provided. These should not normally be +adjusted, but are documented for the benefit of distros who wish to +adopt dgit. +.TP +.BR dgit-distro. \fIdistro\fR /push. * +If set, overrides corresponding non \fB/push\fR config when +.BR readonly=false , +or when pushing and +.BR readonly=auto . .TP -.BI dgit-distro. distro .git-user +.BI dgit-distro. distro .git-url .TP -.BI dgit-distro. distro .git-host +.BR dgit-distro. \fIdistro\fR .git-url [ -suffix ] .TP .BI dgit-distro. distro .git-proto .TP .BI dgit-distro. distro .git-path .TP -.BI dgit-distro. distro .git-check +.BR dgit-distro. \fIdistro\fR .git-check " " true | false | url | ssh-cmd .TP -.BI dgit-distro. distro .git-create +.BI dgit-distro. distro .git-check-suffix .TP -.BI dgit-distro. distro .upload-host +.BR dgit-distro. \fIdistro\fR .diverts.divert " " new-distro | / \fIdistro-suffix\fR .TP -.BI dgit-distro. distro .mirror +.BI dgit-distro. distro .git-create " " ssh-cmd | true .TP -.BI dgit-distro. distro .archive-query +.BR dgit-distro. \fIdistro\fR .archive-query " " ftpmasterapi: " | " madison: "\fIdistro\fR | " dummycat: "\fI/path\fR | " sshpsql: \fIuser\fR @ \fIhost\fR : \fIdbname\fR .TP -.BI dgit-distro. distro .archive-query-default-component +.BR dgit-distro. \fIdistro\fR .archive-query- ( url | tls-key | curl-ca-args ) +.TP +.BI dgit-distro. distro .madison-distro .TP -.BI dgit-distro. distro .sshpsql-user +.BI dgit-distro. distro .archive-query-default-component .TP -.BI dgit-distro. distro .sshpsql-host +.BI dgit-distro. distro .ssh .TP .BI dgit-distro. distro .sshpsql-dbname .TP -.BI dgit-distro. distro .ssh +.BR dgit-distro. \fIdistro\fR . ( git | sshpsql ) - ( user | host | user-force ) .TP -.BI dgit-distro. distro .keyid +.BI dgit-distro. distro .backports-quirk .TP .BR dgit.default. * for each @@ -741,31 +736,15 @@ interprets it the same way as git does. See also the --ssh= and --ssh: options. .TP +.BR DEBEMAIL ", " DEBFULLNAME +Default git user.email and user.name for new trees. See +.BR "dgit setup-new-tree" . +.TP .BR gpg ", " dpkg- "..., " debsign ", " git ", " curl ", " dput ", " LWP::UserAgent 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. - dgit's git representation of format `3.0 (quilt)' source packages does not represent the patch stack as git commits. Currently the patch series representation cannot round trip between git and the archive. @@ -798,14 +777,11 @@ 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. .SH SEE ALSO +\fBdgit\fP(7), \fBcurl\fP(1), \fBdput\fP(1), \fBdebsign\fP(1),