X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.1;h=c9705c7dc2d98c3cab55ab49e357d55785ccdf8a;hp=9a9f32e2730633b64eca7949df7aa4ccbc72917e;hb=42a4e12f8b0511c915d1f3e174ce724642605c81;hpb=2c790fefb4b5d606005a9161faaf740d0377756b diff --git a/dgit.1 b/dgit.1 index 9a9f32e2..c9705c7d 100644 --- a/dgit.1 +++ b/dgit.1 @@ -52,8 +52,73 @@ Tagging and signing should be left to dgit push. does an `upload', pushing the current HEAD to the archive (as a source package) and to dgit-repos (as git commits). This also involves making a signed git tag, and signing the files to be uploaded to the -archive. -.SH MODEL AND WORKFLOW +archive. (For a format `3.0 (quilt)' source package, dgit push +may also have to make a commit on your current branch to contain +quilt metadata. It will do this automatically.) + +.B dgit quilt-fixup +looks to see if there is quilt patch metadata left over by dpkg-source +-b, and if so makes a git commit of it. This is normally done +automatically by dgit push. dgit quilt-fixup takes no additional +arguments. Note that it will only process a patch generated by +dpkg-source for the most recent version (according to the +debia/changelog). +.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 commit to push; the only requirement is that it is a +descendant of the state of the archive, as provided by dgit in the +remote tracking branch +.BR remotes/dgit/ \fIsuite\fR. + +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 the same. 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) obtain a git history representation of what's in the +archive and record it in the +.BI remotes/dgit/ suite +tracking branch. Then construct somehow, using your other git history +plus appropriate diffs and cherry picks from the dgit remote tracking +branch, a git commit whose tree corresponds to the tree to use for the +next upload. If that commit-to-be-uploaded is not a descendant of the +dig remote tracking branch, check it out and say +.BR "git merge -s ours remotes/dgit/" \fIsuite\fR; +that tells git that we are deliberately throwing away any differences +between what's in the archive and what you intend to upload. +Then run +.BR "dgit push" +to actually upload the result. +.SH MODEL You may use any suitable git workflow with dgit, provided you satisfy dgit's requirements: @@ -93,6 +158,38 @@ dgit expects repos that it works with to have a remote. This refers to the well-known dgit-repos location (currently, the dgit-repos project on Alioth). dgit fetch updates the remote tracking branch for dgit/suite. + +dgit does not (currently) represent the orig tarball(s) in git; nor +does it represent the patch statck of a `3.0 (quilt)' package. The +orig tarballs are downloaded and kept in the parent directory, as with +a traditional (non-gitish) dpkg-source workflow. + +To a user looking at the archive, changes pushed using dgit look like +changes made in an NMU: in a `3.0 (quilt)' package the delta from the +previous upload is recorded in a new patch constructed by dpkg-source. +.SH PACKAGE SOURCE FORMATS +If you are not the maintainer, you do not need to worry about the +source format of the package. You can just make changes as you like +in git. If the package is a `3.0 (quilt)' package, the patch stack +will usually not be represented in the git history. + +If you are the maintainer of a non-native package, you currently have +two sensible options: + +Firstly, you can regard your git history as primary, and the archive +as an export format. For example, you could maintain topic branches +in git and a fast-forwarding release branch; or you could do your work +directly in a merging way on the +.BI dgit/ suite +branches. If you do this you should probably use a `1.0' format +source package. In the archive, the delta between upstream will be +represented in the single Debian patch. + +Secondly, you can regard your quiltish patch stack in the archive as +primary. You will have to use other tools besides dgit to import and +export this patch stack. For `3.0 (quilt)' packages, dgit has to do +more work to work around quilt braindamage. See also the BUGS +section. We recommend against the use of `3.0 (quilt)'. .SH OPTIONS .TP .BR --dry-run | -n @@ -147,9 +244,6 @@ there is no way to ask the archive to do this without knowing the name of an existing package. Without --new we can just use the package we are trying to push. But with --new that will not work, so we guess that -.B dpkg -exists in the target suite. If it doesn't, you can use this option to -specify a package which does. If the suite is empty, bad luck. .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 @@ -233,6 +327,15 @@ 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. +`3.0 (quilt)' packages have an additional difficulty: if these are +edited in the most normal way, and then fed to dpkg-buildpackage, +dpkg-source will add extra quilt patch metadata to the source tree +during the source package build. This extra metadata is then of +course not included in the git history. So dgit push needs to commit +it for you, to make sure that the git history and archive contents are +identical. That this is necessary is a bug in the `3.0 (quilt)' +format. + The error messages are often unhelpfully terse and tend to refer to line numbers in dgit.