X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=13666ea432cf08f14d33abf738d562fd0c1eba06;hp=0e38149f2458cd251eb6af3886c462c8f7982c07;hb=da2456e64add31d0ad28e2905b7a55e0ecb7000d;hpb=90b565569492bd661031af3461a2e7119560696d diff --git a/dgit.1 b/dgit.1 index 0e38149f..13666ea4 100644 --- a/dgit.1 +++ b/dgit.1 @@ -127,19 +127,21 @@ 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 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 +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 arguments after git-build +with some suitable options. Options and arguments after gbp-build will be passed on to git-buildpackage. +By default this uses \-\-quilt=gbp, so HEAD should be a +git-buildpackage style branch, not a patches-applied branch. + Tagging, signing and actually uploading should be left to dgit push. .TP \fBdgit push\fR [\fIsuite\fP] @@ -198,13 +200,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 @@ -246,8 +262,8 @@ Use for signing the tag and the upload. The default comes from the distro's .B keyid -config setting (see CONFIGURATION, below), or failing that, gnupg's -default. +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). @@ -306,8 +322,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. @@ -315,6 +333,38 @@ This can be useful with build, if you plan to commit later. (dgit push will still ensure that the .dsc you upload and the git tree you push are identical, so this option won't make broken pushes.) .TP +.BR --overwrite =\fIprevious-version\fR +Declare that even though your git branch is not a descendant +of the version in the archive +according to the revision history, +it really does contain +all the (wanted) changes from that version. + +This option is useful if you are the maintainer, and you have +incorporated NMU changes into your own git workflow in a way that +doesn't make your branch a fast forward from the NMU. + +.I previous-version +ought to be the version currently in the archive. If +.I previous-version +is not +specified, dgit will check that the version in the archive is +mentioned in your debian/changelog. +(This will avoid losing +changes unless someone committed to git a finalised changelog +entry, and then made later changes to that version.) + +dgit push --overwrite +will make a +pseudo-merge (that is, something that looks like the result +of git merge -s ours) to stitch the archive's version into your own +git history, so that your push is a fast forward from the archive. + +(In quilt mode +.BR gbp ", " dpm " or " unpatched , +implying a split between the dgit view and the +maintainer view, the pseudo-merge will appear only in the dgit view.) +.TP .BI --deliberately- something Declare that you are deliberately doing .IR something . @@ -372,9 +422,57 @@ 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 +.BR --quilt=gbp " | " --quilt=dpm " | " --quilt=unapplied +Tell dgit that you are using a nearly-dgit-compatible git branch, +aka a +.BR "maintainer view" , +and +do not want your branch changed by dgit. + +.B --quilt=gbp +is for use with git-buildpackage. +Your HEAD is expected to be +a patches-unapplied git branch, except that it might contain changes +to upstream .gitignore files. This is the default for dgit gbp-build. + +.B --quilt=dpm +is for use with git-dpm. +Your HEAD is expected to be +a patches-applied git branch, +except that it might contain changes to upstream .gitignore files. + +.B --quilt=unapplied +specifies that your HEAD is a patches-unapplied git branch (and +that any changes to upstream .gitignore files are represented as +patches in debian/patches). + +Instead, dgit quilt-fixup and dgit-push will automatically +convert your git branch into the right form, +and dgit push will push the +dgit-compatible form (the +.BR "dgit view" ) +to the dgit git server. +The dgit view will be visible to you +in the dgit remote tracking branches, but your own branch will +not be modified. +dgit will create a tag +.BI debian/ version +for the maintainer view, and the dgit tag +.BI archive/debian/ version +for the dgit view. + +.B If you have a branch like this it is essential to specify the appropriate --quilt= option! +This is because it is not always possible to tell: a patches-unapplied +git branch of a package with one patch, for example, looks just the +same as a patches-applied branch where the user has used git revert to +undo the patch, expecting to actually revert it. +If you fail to specify the right \-\-quilt option, +and you aren't too lucky, dgit will notice the problem and stop, +with a useful hint. +.TP .BI -D Prints debugging information to stderr. Repeating the option produces -more output (currently, up to -DDD is meaningfully different). +more output (currently, up to -DDDD is meaningfully different). .TP .BI -c name = value Specifies a git configuration option, to be used for this run. @@ -414,18 +512,41 @@ Specifies alternative programs to use instead of .BR gpg , .BR ssh , .BR dgit , +.BR git , +.BR gbp-pq , +.BR gbp-build , or .BR mergechanges . -For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild, +For +.BR dpkg-buildpackage , +.BR dpkg-genchanges , +.B mergechanges +and +.BR sbuild , this applies only when the program is invoked directly by dgit. -For dgit, specifies the command to run on the remote host when dgit +For +.BR dgit , +specifies the command to run on the remote host when dgit rpush needs to invoke a remote copy of itself. (dgit also reinvokes itself as the EDITOR for dpkg-source --commit; this is done using argv[0], and is not affected by --dgit=). -For ssh, the default value is taken from the +.BR gbp-build 's +value +is used instead of gbp build or git-buildpackage. (The default is +the latter unless the former exists on PATH.) +.BR gbp-pq 's +value +is used instead of gbp pq. +In both cases, +unusually, the specified value is split on whitespace +to produce a command and possibly some options and/or arguments. + +For +.BR ssh , +the default value is taken from the .B DGIT_SSH or .B GIT_SSH @@ -451,6 +572,8 @@ Specifies a single additional option to pass to .BR sbuild , .BR ssh , .BR dgit , +.BR gbp-pq , +.BR gbp-build , or .BR mergechanges . Can be repeated as necessary. @@ -460,6 +583,10 @@ 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 @@ -493,8 +620,7 @@ How to set this up is not yet documented. .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 @@ -505,6 +631,18 @@ 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 @@ -588,14 +726,17 @@ archive and record it in the 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/dgit/" \fIsuite\fR; -that tells git that we are deliberately throwing away any differences +next upload. + between what's in the archive and what you intend to upload. Then run .BR "dgit push" to actually upload the result. + +If the commit-to-be-uploaded is not a descendant of the +dgit remote tracking branch, you will need to pass +.B --overwrite +to dgit. .SH CONFIGURATION dgit can be configured via the git config system. You may set keys with git-config (either in system-global or per-tree @@ -613,6 +754,23 @@ which is involved. The config used is thereafter that for the distro. .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 @@ -631,6 +789,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 @@ -667,6 +856,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 @@ -674,10 +865,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 @@ -689,6 +876,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 @@ -724,8 +915,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. @@ -738,4 +927,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/