chiark / gitweb /
dgit(7): Substantial updates
authorIan Jackson <ijackson@chiark.greenend.org.uk>
Sun, 30 Oct 2016 22:47:43 +0000 (22:47 +0000)
committerIan Jackson <ijackson@chiark.greenend.org.uk>
Sun, 30 Oct 2016 22:47:46 +0000 (22:47 +0000)
Including documenting split view.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
debian/changelog
dgit.7

index 4a977b5..8d91bb3 100644 (file)
@@ -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.
 
  --
 
diff --git a/dgit.7 b/dgit.7
index cbf91b9..6f5844b 100644 (file)
--- a/dgit.7
+++ b/dgit.7
@@ -11,6 +11,22 @@ using dgit.  This git history is stored in a canonical location known
 as
 .B dgit-repos
 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
+branches.
+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
+.TP
+\fBdgit\fP(1)
+Reference manual and documentation catalogue.
+.TP
+\fBdgit-*\fB(7)
+Tutorials and workflow guides.  See dgit(1) for a list.
 .SH MODEL
 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
 .B Dgit
 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,
+and a
 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
 .B dgit
-remote.  This refers to the well-known dgit-repos location (on a
-dedicated Debian VM).  dgit fetch updates the remote tracking branch
-for dgit/suite.
+(pseudo) remote.  This refers to the dgit-created git view of
+the corresponding archive.
+
+The dgit archive tracking view is synthesised locally,
+on demand,
+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
+each suite.
 
-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).
+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.
+(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.
+However,
+the dgit repositories do not contain uploads not made with dgit.
+And
+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
+reasonable
 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.
+.SH LIMITATIONS
+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
+different suites.
+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
+dgit push
+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
+git server.
+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
+(for example)
+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
+dgit-intern/quilt-cache.
+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
-\fBdgit\fP(1).