X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=a26f6bc0dea545af6d7742829fd6303f7d4e27e3;hp=93183cfcbe7b2e5c0264452a87769e73c46bf3a7;hb=cb809d942c58dea5dfba6ad8b7e3298338ebb24e;hpb=6359817c2baf67249782dc428c34c97e6a633b3b diff --git a/dgit.1 b/dgit.1 index 93183cfc..a26f6bc0 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: using a merging git workflow +dgit-maint-gbp(7) for maintainers: 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] @@ -429,6 +433,24 @@ 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 @@ -844,71 +866,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 @@ -1057,42 +1014,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),