From cfd5e47a4a0d485c2cbb93cccad40e8086de52ea Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Wed, 1 Jul 2015 18:12:54 +0100 Subject: Manpages: Break out dgit(7) from dgit(1). --- dgit.7 | 153 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 dgit.7 (limited to 'dgit.7') diff --git a/dgit.7 b/dgit.7 new file mode 100644 index 0000000..a3ea84c --- /dev/null +++ b/dgit.7 @@ -0,0 +1,153 @@ +.TH dgit 7 "" "Debian Project" "dgit" +.SH NAME +dgit \- principles of operation +.SH SUMMARY +.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 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 (currently, on Alioth). +.SH MODEL +You may use any suitable git workflow with dgit, provided you +satisfy dgit's requirements: + +dgit maintains a pseudo-remote called +.BR dgit , +with one branch per suite. This remote cannot be used with +plain git. + +The +.B dgit-repos +repository for each package contains one ref per suite named +\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). + +However, it is perfectly fine to have other branches in dgit-repos; +normally the dgit-repos repo for the package will be accessible via +the remote name `origin'. + +dgit push will also (by default) make signed tags called +.BI debian/ version +and push them to dgit-repos, but nothing depends on these tags +existing. + +dgit push can operate on any commit which is a descendant of the +current dgit/suite tip in dgit-repos. + +Uploads made by dgit contain an additional field +.B Dgit +in the source package .dsc. (This is added by dgit push.) +This specifies a commit (an ancestor of the dgit/suite +branch) whose tree is identical to the unpacked source upload. + +Uploads not made by dgit are represented in git by commits which are +synthesised by dgit. The tree of each such commit corresponds to the +unpacked source; there is an origin commit with the contents, and a +psuedo-merge from last known upload - that is, from the contents of +the dgit/suite branch. + +dgit expects repos that it works with to have a +.B dgit +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. The +orig tarballs are downloaded (by dgit clone) into the parent +directory, as with a traditional (non-gitish) dpkg-source workflow. +You need to retain these tarballs in the parent directory for dgit +build and dgit push. + +dgit repositories could be cloned with standard (git) methods. The +only exception is that for sourcefull builds / uploads the orig +tarball(s) need to be present in the parent directory. + +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 READ-ONLY DISTROS +Distros which do not maintain a set of dgit history git repositories +can still be used in a read-only mode with dgit. Currently Ubuntu +is configured this way. +.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. +.SH FORMAT 3.0 (QUILT) +For a format `3.0 (quilt)' source package, dgit may have to make a +commit on your current branch to contain metadata used by quilt and +dpkg-source. + +This is because `3.0 (quilt)' source format represents the patch stack +as files in debian/patches/ actually inside the source tree. This +means that, taking the whole tree (as seen by git or ls) (i) +dpkg-source cannot represent certain trees, and (ii) packing up a tree +in `3.0 (quilt)' and then unpacking it does not always yield the same +tree. + +dgit will automatically work around this for you when building and +pushing. The only thing you need to know is that dgit build, sbuild, +etc., may make new commits on your HEAD. If you're not a quilt user +this commit won't contain any changes to files you care about. + +You can explicitly request that dgit do just this fixup, by running +dgit quilt-fixup. + +If you are a quilt user you need to know that dgit's git trees are +`patches applied packaging branches' and do not contain the .pc +directory (which is used by quilt to record which patches are +applied). If you want to manipulate the patch stack you probably want +to be looking at tools like git-dpm. +.SH FILES IN THE SOURCE PACKAGE BUT NOT IN GIT +This section is mainly of interest to maintainers who want to use dgit +with their existing git history for the Debian package. + +Some developers like to have an extra-clean git tree which lacks files +which are normally found in source tarballs and therefore in Debian +source packages. For example, it is conventional to ship ./configure +in the source tarball, but some people prefer not to have it present +in the git view of their project. + +dgit requires that the source package unpacks to exactly the same +files as are in the git commit on which dgit push operates. So if you +just try to dgit push directly from one of these extra-clean git +branches, it will fail. + +As the maintainer you therefore have the following options: +.TP +\(bu +Persuade upstream that the source code in their git history and the +source they ship as tarballs should be identical. Of course simply +removing the files from the tarball may make the tarball hard for +people to use. +.IP +One answer is to commit the (maybe autogenerated) +files, perhaps with some simple automation to deal with conflicts and +spurious changes. This has the advantage that someone who clones +the git repository finds the program just as easy to build as someone +who uses the tarball. +.TP +\(bu +Have separate git branches which do contain the extra files, and after +regenerating the extra files (whenever you would have to anyway), +commit the result onto those branches. +.TP +\(bu +Provide source packages which lack the files you don't want +in git, and arrange for your package build to create them as needed. +This may mean not using upstream source tarballs and makes the Debian +source package less useful for people without Debian build +infrastructure. +.LP +Of course it may also be that the differences are due to build system +bugs, which cause unintended files to end up in the source package. +dgit will notice this and complain. You may have to fix these bugs +before you can unify your existing git history with dgit's. +.SH SEE ALSO +\fBdgit\fP(1). -- cgit v1.2.3