diff options
author | Ian Jackson <ijackson@chiark.greenend.org.uk> | 2016-10-30 23:56:29 +0000 |
---|---|---|
committer | Ian Jackson <ijackson@chiark.greenend.org.uk> | 2016-10-30 23:56:29 +0000 |
commit | cb809d942c58dea5dfba6ad8b7e3298338ebb24e (patch) | |
tree | d4316c3289f8e8efdd746dfaf3a51ecd0544c5b5 /dgit.1 | |
parent | 14a6daa486a195f465c8049122d20675d6626f07 (diff) | |
parent | 6e7c6b8b8305f162cea9e3da85c24b3f21888a1a (diff) |
Merge branch 'wip.tutorials' into wip
Diffstat (limited to 'dgit.1')
-rw-r--r-- | dgit.1 | 136 |
1 files changed, 32 insertions, 104 deletions
@@ -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] @@ -862,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 @@ -1075,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), |