X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=dgit.1;h=90ed69eb9163a42778ff7a64a52d7e6d2fece4b7;hb=5cbfd93057610740cf7954ce3d29a2d14bacd603;hp=092c6e98fdb2f55e4a5ab08f20a18f705ff487dc;hpb=e98a72a30420115e2e51b2317287f83a38daddba;p=dgit.git diff --git a/dgit.1 b/dgit.1 index 092c6e98..90ed69eb 100644 --- a/dgit.1 +++ b/dgit.1 @@ -27,24 +27,22 @@ dgit \- git integration with the Debian archive [\fIdgit\-opts\fP] \fIaction\fR ... .SH DESCRIPTION .B dgit -allows you to treats the Debian archive as if it were a git +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. dgit clone or fetch +1. \fBdgit clone\fR or \fBfetch\fR; .br -2. make, dev test and commit changes in git as desired +2. make, do dev tests, and commit changes in git as desired; .br -3. run dgit build, dgit sbuild or -dgit build-source, or generate the source and binary packages for upload -some other way +3. build packages for upload, using e.g. \fBdgit sbuild\fR .br -4. do pre-upload tests of the proposed upload +4. do pre-upload tests of the proposed upload; .br -5. dgit push. +5. \fBdgit push\fR. .SH OPERATIONS .TP \fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR] @@ -98,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 @@ -200,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 @@ -261,7 +267,20 @@ 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. +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=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 @@ -273,6 +292,15 @@ 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 --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 may be new in this suite. Without this, dgit will refuse to push. @@ -314,7 +342,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 @@ -342,11 +370,11 @@ 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 -DDD 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 @@ -450,9 +478,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 @@ -472,7 +499,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 @@ -559,49 +586,82 @@ Then run .BR "dgit push" to actually upload the result. .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. +it then looks .TP -.BI dgit-suite. suite .distro +.BI dgit.default.distro " distro" +The default distro for an unknown suite. .TP -.BI dgit.default.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-distro. distro .keyid +.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. +.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 .sshpsql-user +.BI dgit-distro. distro .madison-distro .TP -.BI dgit-distro. distro .sshpsql-host +.BI dgit-distro. distro .archive-query-default-component +.TP +.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 @@ -622,26 +682,6 @@ 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. @@ -674,10 +714,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.