X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=87ad0fce4b8f589f38ec85d378567d632cf9ffca;hp=ebba8b656cb15939209a731589afc388d9d8f9e9;hb=eefe676b1f2bb245710f17e7b7694b420d0a00db;hpb=0b6f44d83523b8fcfff46ecf716ebbbf6ada71f6 diff --git a/dgit.1 b/dgit.1 index ebba8b65..87ad0fce 100644 --- a/dgit.1 +++ b/dgit.1 @@ -126,18 +126,17 @@ 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 -passed on to sbuild. Changes files matching -.IB package _ version _*.changes -in the parent directory will be removed; the output is left in +binary changes files. Options and arguments after sbuild will be +passed on to sbuild. +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 ... +\fBdgit gbp-build\fR ... Runs .B git-buildpackage -with some suitable options. Options and argumments after git-build +with some suitable options. Options and arguments after gbp-build will be passed on to git-buildpackage. Tagging, signing and actually uploading should be left to dgit push. @@ -198,13 +197,27 @@ 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 . -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 @@ -243,7 +256,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). @@ -278,7 +295,7 @@ This is like but it also removes any subdirectories containing different git trees (which only unusual packages are likely to create). .TP -.BR --clean=check " | " -wn +.BR --clean=check " | " -wc Merely check that the tree is clean (does not contain uncommitted files), before building a source package. .TP @@ -302,8 +319,10 @@ The build-dependencies are not checked (due to 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. +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. @@ -342,7 +361,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 @@ -370,11 +389,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 -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 @@ -410,6 +429,7 @@ Specifies alternative programs to use instead of .BR gpg , .BR ssh , .BR dgit , +.BR git , or .BR mergechanges . @@ -456,10 +476,19 @@ this applies only when the program is invoked directly by dgit. Usually, for passing options to dpkg-genchanges, you should use .BR --ch: \fIoption\fR. +Specifying --git not effective for some lower-level read-only git +operations performed by dgit, and also not when git is invoked by +another program run by dgit. + 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 @@ -478,15 +507,13 @@ 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 dgit push looks for single .changes file in the parent directory whose -filename suggests it is for the right package and version - or, -if there is a _multi.changes file, dgit uses that. +filename suggests it is for the right package and version. If the specified .I changesfile @@ -497,10 +524,22 @@ otherwise, the changes file is expected in that directory (by default, in .BR .. ). .TP +.B --rm-old-changes +When doing a build, delete any changes files matching +.IB package _ version _*.changes +before starting. This ensures that +dgit push (and dgit sbuild) will be able to unambigously +identify the relevant changes files from the most recent build, even +if there have been previous builds with different tools or options. +The default is not to remove, but +.B \-\-no-rm-old-changes +can be used to override a previous \-\-rm-old-changes +or the .rm-old-changes configuration setting. +.TP .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 @@ -531,12 +570,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. @@ -565,7 +606,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). @@ -579,7 +620,7 @@ 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 +dgit remote tracking branch, check it out and say .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. @@ -599,19 +640,37 @@ Settings likely to be useful for an end user include: 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.default.distro " distro" The default distro for an unknown suite. .TP +.BR dgit.default. * +for each +.BR dgit-distro. \fIdistro\fR . *, +the default value used if there is no distro-specific setting. +.TP +.BR dgit-distro. \fIdistro\fR .clean-mode +One of the values for the command line --clean= option; used if +--clean is not specified. +.TP +.BR dgit-distro. \fIdistro\fR .quilt-mode +One of the values for the command line --quilt= option; used if +--quilt is not specified. +.TP +.BR dgit-distro. \fIdistro\fR .rm-old-changes +Boolean, used if neither \-\-rm-old-changes nor \-\-no-rm-old-changes +is specified. The default is not to remove. +.TP .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 +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 +See also +.BR -k . .TP .BI dgit-distro. distro .mirror " url" .TP @@ -620,6 +679,37 @@ Not relevant for Debian. .TP .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 @@ -656,6 +746,8 @@ or when pushing and .TP .BI dgit-distro. distro .archive-query-default-component .TP +.BI dgit-distro. distro .dgit-tag-format +.TP .BI dgit-distro. distro .ssh .TP .BI dgit-distro. distro .sshpsql-dbname @@ -663,10 +755,6 @@ or when pushing and .BR dgit-distro. \fIdistro\fR . ( git | sshpsql ) - ( user | host | user-force ) .TP .BI dgit-distro. distro .backports-quirk -.TP -.BR dgit.default. * -for each -.BR dgit-distro. \fIdistro\fR . * .SH ENVIRONMENT VARIABLES .TP .BR DGIT_SSH ", " GIT_SSH @@ -678,6 +766,10 @@ 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 @@ -713,8 +805,6 @@ There should be an option which arranges for the `3.0 (quilt)' autocommit(s) to not appear on your HEAD, but instead only in the remote tracking suite branch. -The option parser requires values to be cuddled to the option name. - --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. @@ -727,4 +817,4 @@ non-dry-run dgit fetch first will help. \fBgit-buildpackage\fP(1), \fBdpkg-buildpackage\fP(1), .br -https://wiki.debian.org/Alioth +https://browse.dgit.debian.org/