X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=63a70217ce07dc372f97942a35227097589020d8;hp=5367c36adc5f4c2ad3e4e4c1f7032f5815eefe88;hb=dda17d8a6fec27f631653cf8ac63ba6d96e642c3;hpb=1b99def96ddbaec91a0208916f257a1381e446b6 diff --git a/dgit.1 b/dgit.1 index 5367c36a..63a70217 100644 --- a/dgit.1 +++ b/dgit.1 @@ -1,3 +1,4 @@ +'\" t .TH dgit 1 "" "Debian Project" "dgit" .SH NAME dgit \- git integration with the Debian archive @@ -28,21 +29,24 @@ dgit \- git integration with the Debian archive .SH DESCRIPTION .B dgit 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, +repository. + +This is the command line reference. +Please read the tutorial(s): +.TS +lb l. +dgit-user(7) for users: editing, building and sharing packages +dgit-nmu-simple(7) for DDs: doing a straightforward NMU +dgit-maint-native(7) for maintainers of Debian-native packages +dgit-maint-merge(7) for maintainers who want a pure git workflow +dgit-maint-gbp(7) for maintainers already using git-buildpackage +dgit-sponsorship(7) for sponsors and sponsored contributors +.TE +.LP +See \fBdgit(7)\fP 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] @@ -69,6 +73,11 @@ for the distro to which .I suite belongs. +.I suite +may be a combination of several underlying suites in the form +.IR mainsuite \fB,\fR subsuite ...; +see COMBINED SUITES in dgit(7). + For your convenience, the .B vcs-git remote will be set up from the package's Vcs-Git field, if there is @@ -86,6 +95,7 @@ then dgit fetch defaults to .IR suite ; otherwise it parses debian/changelog and uses the suite specified there. +suite may be a combined suite, as for clone. .TP \fBdgit pull\fR [\fIsuite\fP] Does dgit fetch, and then merges the new head of the remote tracking @@ -177,15 +187,14 @@ current directory; however, signing operations are done on the invoking host. This allows you to do a push when the system which has the source code and the build outputs has no access to the key: +.TS +l l. 1. Clone on build host (dgit clone) -.br 2. Edit code on build host (edit, git commit) -.br 3. Build package on build host (dgit build) -.br 4. Test package on build host or elsewhere (dpkg -i, test) -.br 5. Upload by invoking dgit rpush on host with your GPG key. +.TE However, the build-host must be able to ssh to the dgit repos. If this is not already the case, you must organise it separately, for @@ -429,6 +438,45 @@ git history, so that your push is a fast forward from the archive. implying a split between the dgit view and the maintainer view, the pseudo-merge will appear only in the dgit view.) .TP +.BR --delayed =\fIdays\fR +Upload to a DELAYED queue. + +.B WARNING: +If the maintainer responds by cancelling +your upload from the queue, +and does not make an upload of their own, +this will not rewind the git branch on the dgit git server. +Other dgit users will then see your push +(with a warning message from dgit) +even though the maintainer wanted to abolish it. +Such users might unwittingly reintroduce your changes. + +If this situation arises, +someone should make a suitable dgit push +to update the contents of dgit-repos +to a version without the controversial changes. +.TP +.BR --dgit-view-save= \fIbranch\fR|\fIref\fR +Specifies that when a split view quilt mode is in operation, +and dgit calculates +(or looks up in its cache) +a dgit view corresponding to your HEAD, +the dgit view will be left in +.IR ref . +The specified ref is unconditionally overwritten, +so don't specify a branch you want to keep. + +This option is effective only with the following operations: +quilt-fixup; push; all builds. +And it is only effective with +--[quilt=]gbp, +--[quilt=]dpm, +--quilt=unpatched. + +If ref does not start with refs/ +it is taken to to be a branch - +i.e. refs/heads/ is prepended. +.TP .BI --deliberately- something Declare that you are deliberately doing .IR something . @@ -617,6 +665,24 @@ By default, dgit looks in the parent directory .BI --no-rm-on-error Do not delete the destination directory if clone fails. .TP +.BI --dep14tag +Generates a DEP-14 tag (eg +.BR debian/ \fIversion\fR) +as well as a dgit tag (eg +.BR archive/debian/ \fIversion\fR) +where possible. This is the default. +.TP +.BI --no-dep14tag +Do not generate a DEP-14 tag, except in split quilt view mode. +(On servers where only the old tag format is supported, +the dgit tag will have the DEP-14 name. +This option does not prevent that.) +.TP +.BI --dep14tag-always +Insist on generating a DEP-14 tag +as well as a dgit tag. +If the server does not support that, dgit push will fail. +.TP .BI -D Prints debugging information to stderr. Repeating the option produces more output (currently, up to -DDDD is meaningfully different). @@ -667,6 +733,8 @@ Specifies a single additional option to pass to .BR sbuild , .BR ssh , .BR dgit , +.BR apt-get , +.BR apt-cache , .BR gbp-pq , .BR gbp-build , or @@ -712,6 +780,8 @@ Specifies alternative programs to use instead of .BR gpg , .BR ssh , .BR dgit , +.BR apt-get , +.BR apt-cache , .BR git , .BR gbp-pq , .BR gbp-build , @@ -823,71 +893,6 @@ Force on or off the use of the absurd git-apply emulation when running gbp pq import when importing a package from a .dsc. See Debian bug #841867. -.SH WORKFLOW - SIMPLE -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 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 (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. - -If you are lucky the other uploaders have also used dgit and -integrated the other relevant git history; if not you can fetch it -into your tree and cherry-pick etc. as you wish. -.SH WORKFLOW - INTEGRATING BETWEEN DGIT AND OTHER GIT HISTORY -If you are the maintainer of a package dealing with uploads made -without dgit, you will probably want to merge the synthetic commits -(made by dgit to represent the uploads) into your git history. -Normally you can just merge the dgit branch into your own master, or -indeed if you do your work on the dgit local suite branch -.BI dgit/ suite -you can just use dgit pull. - -However the first time dgit is used it will generate a new origin -commit from the archive which won't be linked into the rest of your -git history. You will need to merge this. - -If last upload was in fact made with git, you should usually proceed -as follows: identify the commit which was actually used to build the -package. (Hopefully you have a tag for this.) Check out the dgit -branch -.RB ( "git checkout dgit/" \fIsuite\fR) -and merge that other commit -.RB ( "git merge debian/" \fIversion\fR). -Hopefully this merge will be trivial because the two trees should -be very similar. The resulting branch head can be merged into your -working branches -.RB ( "git checkout master && git merge dgit/" \fIsuite\fR). - -If last upload was not made with git, a different approach is required -to start using dgit. First, do -.B dgit fetch -(or clone) to obtain a git history representation of what's in the -archive and record it in the -.BI remotes/dgit/dgit/ suite -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. - -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 @@ -901,6 +906,9 @@ 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. + +.I suite +may be a glob pattern. .TP .BI dgit.default.distro " distro" The default distro for an unknown suite. @@ -1009,6 +1017,8 @@ or when pushing and .TP .BI dgit-distro. distro .dgit-tag-format .TP +.BR dgit-distro. \fIdistro\fR .dep14tag " " want | no | always +.TP .BI dgit-distro. distro .ssh .TP .BI dgit-distro. distro .sshpsql-dbname @@ -1036,42 +1046,31 @@ and other subprograms and modules used by dgit are affected by various environment variables. Consult the documentaton for those programs for details. .SH BUGS -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. -Ideally dgit would represent a quilty package with an origin commit of -some kind followed by the patch stack as a series of commits followed -by a pseudo-merge (to make the branch fast-forwarding). This would -also mean a new `dgit rebase-prep' command or some such to turn such a -fast-forwarding branch back into a rebasing patch stack, and a `force' -option to dgit push (perhaps enabled automatically by a note left by -rebase-prep) which will make the required pseudo-merge. - -If the dgit push fails halfway through, it should be restartable and -idempotent. However this is not true for the git tag operation. -Also, it would be good to check that the proposed signing key is +There should be +a `dgit rebase-prep' command or some such to turn a +fast-forwarding branch containing pseudo-merges +back into a rebasing patch stack. +It might have to leave a note +for a future dgit push. + +If the dgit push fails halfway through, +it is not necessarily restartable and +idempotent. +It would be good to check that the proposed signing key is available before starting work. -dgit's handling of .orig.tar.gz is not very sophisticated. Ideally -the .orig.tar.gz could be transported via the git repo as git tags. -Doing this is made more complicated by the possibility of a `3.0 -(quilt)' package with multiple .orig tarballs. - -dgit's build functions, and dgit push, should not make any changes to +dgit's build functions, and dgit push, may make changes to your current HEAD. Sadly this is necessary for packages in the `3.0 (quilt)' source format. This is ultimately due to what I consider design problems in quilt and dpkg-source. -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. - --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. +--damp-run is likely to work much better. .SH SEE ALSO \fBdgit\fP(7), -\fBdgit-maint-merge\fP(7), +\fBdgit-*\fP(7), \fBcurl\fP(1), \fBdput\fP(1), \fBdebsign\fP(1),