2 files changed, 119 insertions, 16 deletions
diff --git a/debian/changelog b/debian/changelog
index 4a977b5..8d91bb3 100644
@@ -2,6 +2,7 @@ dgit (2.9~) unstable; urgency=low
* dgit-*(7). Many new tutorial manpages, several written and many
improved by Sean Whitton.
+ * dgit(7): Substantial updates, including documenting split view.
@@ -11,6 +11,22 @@ using dgit. This git history is stored in a canonical location known
which lives on a dedicated git server.
+git branches suitable for use with dgit
+can be edited directly in git,
+and used directly for building binary packages.
+They can be shared using all conventional means for sharing git
+It is not necessary to use dgit to work with dgitish git branches.
+However, dgit is (usually) needed in order to convert to or from
+Debian-format source packages.
+.SH SEE ALSO
+Reference manual and documentation catalogue.
+Tutorials and workflow guides. See dgit(1) for a list.
You may use any suitable git workflow with dgit, provided you
satisfy dgit's requirements:
@@ -37,9 +53,6 @@ dgit push will also make signed tags called
and push them to dgit-repos. These are used at the
server to authenticate pushes.
-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
in the source package .dsc. (This is added by dgit push.)
@@ -48,29 +61,87 @@ 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
+unpacked source; there is a
+commit with the contents,
pseudo-merge from last known upload - that is, from the contents of
the dgit/suite branch.
+Depending on the source package format,
+the contents commit may have a more complex structure,
+but ultimately it will be a convergence of stubby branches
+from origin commits representing the components of the source package.
-dgit expects repos that it works with to have a
+dgit expects trees that it works with to have a
-remote. This refers to the well-known dgit-repos location (on a
-dedicated Debian VM). dgit fetch updates the remote tracking branch
+(pseudo) remote. This refers to the dgit-created git view of
+the corresponding archive.
+The dgit archive tracking view is synthesised locally,
+by each copy of dgit.
+The tracking view is always a descendant of the
+dgit-repos suite branch (if one exists),
+but may be ahead of it if uploads have been done without dgit.
+The archive tracking view is always fast forwarding within
-dgit does not (currently) represent the orig tarball(s) in git. The
+dgit push can operate on any commit which is a descendant of
+the suite tracking branch.
+dgit does not make a systematic record of
+its imports of orig tarball(s).
+So it does not work by finding git tags or branches
+referring to orig tarball(s).
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.
+(They are not needed for purely-git-based workflows.)
-dgit repositories could be cloned with standard (git) methods. The
-only exception is that for sourceful builds / uploads the orig
-tarball(s) need to be present in the parent directory.
+dgit repositories could be cloned with standard (git) methods.
+the dgit repositories do not contain uploads not made with dgit.
+for sourceful builds / uploads the orig
+tarball(s) will need to be present in the parent directory.
-To a user looking at the archive, changes pushed using dgit look like
+To a user looking at the archive, changes pushed
+in a simple NMU
+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.
+previous upload is recorded in new patch(es) constructed by dpkg-source.
+Because the synthesis
+of the suite tracking branches
+is done locally based only on the current archive state,
+it will not necessarily see every upload
+not done with dgit.
+Also, different versions of dgit
+(or the software it calls)
+might import the same .dscs differently
+(although we try to minimise this).
+As a consequence, the dgit tracking views of the same
+suite, made by different instances of dgit, may vary.
+They will have the same contents, but may have different history.
+There is no uniform linkage between the tracking branches for
+The Debian infrastructure
+does not do any automatic import of uploads made without dgit.
+It would be possible for a distro's infrastructure to do this;
+in that case,
+different dgit client instances
+would see exactly the same history.
+There has been no bulk import of historical uploads into
+Debian's dgit infrastructure.
+To do this it would be necessary to decide whether to
+import existing vcs history
+(which might not be faithful to dgit's invariants)
+or previous non-Dgit uploads
+(which would not provide a very rich history).
.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
@@ -105,6 +176,39 @@ If you are a quilt user you need to know that dgit's git trees are
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 SPLIT VIEW QUILT MODE
+When working with git branches intended
+for use with the `3.0 (quilt)' source format
+dgit can automatically convert a suitable
+maintainer-provided git branch
+(in one of a variety of formats)
+into a dgit branch.
+When a split view mode is engaged
+dgit build commands and
+will, on each invocation,
+convert the user's HEAD into the dgit view,
+so that it can be built and/or uploaded.
+dgit push in split view mode will push the dgit view to the dgit
+The dgit view is always a descendant of the maintainer view.
+dgit push will also make a maintainer view tag
+according to DEP-14
+and push that to the dgit git server.
+Split view mode must be enabled explicitly
+(by the use of the applicable command line options,
+subcommands, or configuration).
+This is because it is not possible to reliably tell
+whether a git tree for a dpkg-source `3.0 (quilt)' package
+is a patches-applied or patches-unapplied tree.
+Split view conversions are cached in the ref
+This should not be manipulated directly.
.SH FILES IN THE SOURCE PACKAGE BUT NOT IN GIT - AUTOTOOLS ETC.
This section is mainly of interest to maintainers who want to use dgit
with their existing git history for the Debian package.
@@ -228,5 +332,3 @@ This is 100% reliable, but has the downside
that if you forget to git add or to commit, and then use
.BR "dgit -wg" " or " "git reset --hard" ,
your changes may be lost.
-.SH SEE ALSO