X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=e8057d8d8e651f8758bdd4fd65ca882cc7d48da7;hp=93183cfcbe7b2e5c0264452a87769e73c46bf3a7;hb=787ba7f819b210277c50a523a16d8dedddecb91d;hpb=6359817c2baf67249782dc428c34c97e6a633b3b diff --git a/dgit.1 b/dgit.1 index 93183cfc..e8057d8d 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 @@ -130,7 +140,11 @@ 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. - +.IP +Note that by default +sbuild does not build arch-independent packages. +You probably want to pass -A, to request those. +.IP Tagging, signing and actually uploading should be left to dgit push. .TP \fBdgit gbp-build\fR ... @@ -166,9 +180,6 @@ archive. dgit push always uses the package, suite and version specified in the debian/changelog and the .dsc, which must agree. If the command line specifies a suite then that must match too. - -If dgit push fails while uploading, it is fine to simply retry the -dput on the .changes file at your leisure. .TP \fBdgit rpush\fR \fIbuild-host\fR\fB:\fR\fIbuild-dir\fR [\fIpush args...\fR] Pushes the contents of the specified directory on a remote machine. @@ -177,15 +188,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 @@ -257,6 +267,16 @@ and it therefore does not make a pseudomerge to bind the import into any existing git history. +Because a .dsc can contain a Dgit field naming a git commit +(which you might not have), +and specifying where to find that commit +(and any history rewrite table), +import-dsc might need online access. +If this is a problem +(or dgit's efforts to find the commit fail), +consider --no-chase-dsc-distro +or --force-import-dsc-with-dgit-field. + There is only only sub-option: .B --require-valid-signature @@ -287,12 +307,6 @@ dgit will stop with an error message. If .I branch does not start with refs/, refs/heads/ is prepended. -The specified branch is unconditionally updated. - -If the specified .dsc contains a Dgit field, -dgit will simply make a branch of that commit. -If you cannot manage to find that commit anywhere, -consider --force-import-dsc-with-dgit-field. .TP .B dgit version Prints version information and exits. @@ -300,6 +314,11 @@ Prints version information and exits. .BI "dgit clone-dgit-repos-server" " destdir" 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. +.TP +.BI "dgit print-dgit-repos-server-source-url" +Prints the url used by dgit clone-dgit-repos-server. +This is hopefully suitable for use as a git remote url. +It may not be useable in a browser. .SH OPTIONS .TP .BR --dry-run " | " -n @@ -429,6 +448,48 @@ 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 --no-chase-dsc-distro +Tells dgit not to look online +for additional git repositories +containing information about a particular .dsc being imported. +Chasing is the default. + +For most operations +(such as fetch and pull), +disabling chasing +means dgit will access only the git server +for the distro you are directly working with, +even if the .dsc was copied verbatim from another distro. +For import-dsc, +disabling chasing +means dgit will work completely offline. + +Disabling chasing can be hazardous: +if the .dsc names a git commit which has been rewritten +by those in charge of the distro, +this option may prevent that rewrite from being effective. +Also, +using it can mean that +dgit fails to find necessary git commits. +.TP .BR --dgit-view-save= \fIbranch\fR|\fIref\fR Specifies that when a split view quilt mode is in operation, and dgit calculates @@ -638,6 +699,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). @@ -688,6 +767,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 @@ -733,6 +814,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 , @@ -844,71 +927,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 @@ -922,10 +940,16 @@ 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. .TP +.BI dgit.default.default-suite " suite" +The default suite (eg for clone). +.TP .BR dgit.default. * for each .BR dgit-distro. \fIdistro\fR . *, @@ -998,6 +1022,12 @@ 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 +.BI dgit-distro. distro .nominal-distro +Shown in git tags, Dgit fields, and so on. +.TP +.BI dgit-distro. distro .alias-canon +Used for all access configuration lookup. +.TP .BR dgit-distro. \fIdistro\fR /push. * If set, overrides corresponding non \fB/push\fR config when .BR readonly=false , @@ -1030,6 +1060,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 @@ -1037,6 +1069,16 @@ or when pushing and .BR dgit-distro. \fIdistro\fR . ( git | sshpsql ) - ( user | host | user-force ) .TP .BI dgit-distro. distro .backports-quirk +.TP +.BI dgit-distro. distro .rewrite-map-enable +.TP +.BI dgit.default.old-dsc-distro +.TP +.BI dgit.dsc-url-proto-ok. protocol +.TP +.BI dgit.dsc-url-proto-ok.bad-syntax +.TP +.BI dgit.default.dsc-url-proto-ok .SH ENVIRONMENT VARIABLES .TP .BR DGIT_SSH ", " GIT_SSH @@ -1057,42 +1099,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),