X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=dgit.1;h=50cc3a6f7c4532b60da6a9efe3da340fb808e90b;hb=6162f69f8f3611b2da125a11d5ac24cf11045e96;hp=5895458a1722b0bf360662382f355b4577871344;hpb=12dc1b71aa58bd4d044077b4f921580cedb0c347;p=dgit.git diff --git a/dgit.1 b/dgit.1 index 5895458a..50cc3a6f 100644 --- a/dgit.1 +++ b/dgit.1 @@ -4,29 +4,30 @@ dgit \- git integration with the Debian archive . .SH SYNOPSIS .B dgit -[\fIdgit\-options\fP] \fBclone\fP [\fIdgit\-options\fP] -\fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdest-dir|\fB/\fP\fIdest-dir] +[\fIdgit\-opts\fP] \fBclone\fP [\fIdgit\-opts\fP] +\fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir] .br .B dgit -[\fIdgit\-options\fP] \fBfetch\fP|\fBpull\fP [\fIdgit\-options\fP] +[\fIdgit\-opts\fP] \fBfetch\fP|\fBpull\fP [\fIdgit\-opts\fP] [\fIsuite\fP] .br .B dgit -[\fIdgit\-options\fP] \fBbuild\fP -[\fIgit\-buildpackage\-options\fP|\fIdpkg\-buildpackage\-options\fp] +[\fIdgit\-opts\fP] \fBbuild\fP +[\fIgit\-buildpackage\-opts\fP|\fIdpkg\-buildpackage\-opts\fp] .br .B dgit -[\fIdgit\-options\fP] \fBpush\fP [\fIdgit\-options\fP] +[\fIdgit\-opts\fP] \fBpush\fP [\fIdgit\-opts\fP] [\fIsuite\fP] .SH DESCRIPTION .B dgit treats the Debian archive as a version control system, and bidirectionally gateways between the archive and git. The git view of the package can contain the usual upstream git history, and will be -augmented by commits representing uploads done without using dgit. -This git history is stored in a canonical location +augmented by commits representing uploads done by other developers not +using dgit. This git history is stored in a canonical location known +as .B dgit-repos -which lives outside the Debian archive. +which lives outside the Debian archive (currently, on Alioth). .B dgit clone and @@ -56,7 +57,7 @@ archive. You may use any suitable git workflow with dgit, provided you satisfy dgit's requirements: -dgit maintains what looks a bit like a remote called +dgit maintains a pseudo-remote called .BR dgit , with one branch per suite. This remote cannot be used with plain git. @@ -64,7 +65,7 @@ plain git. The .B dgit-repos repository for each package contains one ref per suite named -\fBdrefs/git/\fR\fIsuite\fR. These should be pushed to only by +\fBrefs/dgit/\fR\fIsuite\fR. These should be pushed to only by dgit. They are fast forwarding. Each push on this branch corresponds to an upload (or attempted upload). @@ -111,11 +112,12 @@ does not sign tags or uploads (meaningful only with push). .BI -p package Specifies that we should process source package .I package -rather than looking in debian/control. Valid with dgit fetch -and dgit pull, only. +rather than looking in debian/control or debian/changelog. +Valid with dgit fetch and dgit pull, only. .TP .BI -D -Spew debugging information to stderr. +Prints debugging information to stderr. Repeating the option produces +more output (currently, up to -DD is meaningfully different). .TP .BI -c name = value Specifies a git configuration option. dgit itself is also controlled @@ -132,7 +134,7 @@ debsign. Use repeatedly if multiple additional options are required. .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 they it is for the right package and version. +filename suggests it is for the right package and version. .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 @@ -162,6 +164,8 @@ on the dgit command line. .TP .BI dgit-distro. distro .mirror .TP +.BI dgit-distro. distro .archive-query +.TP .BI dgit-distro. distro .ssh .TP .BR dgit.default. * @@ -175,10 +179,16 @@ dgit assumes knowledge of the archive layout. There appears to be no sane way to find the path in the archive pool of the .dsc for a particular suite. +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. + Debian Policy needs to be updated to describe the new Vcs-Git-Master field (and to specify that it is an RC bug for that field to refer to an unavailable commit). +dgit cannot currently introduce a package into a suite. + dgit push should perhaps do `git push origin', or something similar, by default. @@ -190,19 +200,21 @@ 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 representation of format `3.0 (quilt)' source packages (even if -they were supported) would not represent the patch stack. Currently -the patch series representation cannot round trip through 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) which will make -the required pseudo-merge. +dgit's representation of format `3.0 (quilt)' source packages does not +represent the patch stack. Currently the patch series representation +cannot round trip through 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. 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. The error messages are often unhelpfully terse and tend to refer to line numbers in dgit.