README.dsc-import

   1 We would like to: represent the input tarballs as a commit each (which
   2 all get merged together as if by git merge -s subtree), and for quilt
   3 packages, each patch as a commit.  But w want to avoid (as much as
   4 possible) reimplementing the package extraction algorithm in
   5 dpkg-source.
   6
   7 dpkg-source does not currently provide interfaces that look like they
   8 are intended for what dgit wants to do.  And dgit wants to work with
   9 old versions of dpkg, so I have implemented the following algorithm
  10 rather than wait for such interfaces added (even supposing that a sane
  11 interface could be designed, which is doubtful):
  12
  13 * dgit will untar each input tarball.
  14
  15   This will be done by scanning the .dsc for things whose names look
  16   like (compressed) tarballs, and using the interfaces provided by
  17   Dpkg::Compression to get at the tarball.
  18
  19   Each input tarball unpack will be done separately, and will be
  20   followed by git add and git write-tree, to obtain a git tree object
  21   corresponding to the tarball contents.
  22
  23   That tree object will be made into a commit object with no parents.
  24   (The package changelog will be searched for the earliest version
  25   with the right upstream version component, and the information found
  26   there used for the commit object's metadata.)
  27
  28 * For `3.0 (quilt), dgit will run
  29     dpkg-source -x --skip-patches
  30
  31   git plumbing will be used to make the result into a tree and a
  32   commit.  The commit will have as parents all the tarballs previously
  33   mentioned.  The main orig tarball will be the leftmost parent and
  34   the debian tarball the rightmost parent.  The metadata will come
  35   from the .dsc and/or the final changelog entry.
  36
  37   dgit will then dpkg-source --before-build and record the resulting
  38   tree, too.
  39
  40   Then, dgit will switch back to the patches-unapplied version and use
  41   `gbp pq import' (in the private working area) to turn the
  42   patches-unapplied tree into a patches-applied one.
  43
  44   Finally dgit will check that the gbp pq generated patches-applied
  45   version has the same git tree object as the one generated by
  46   dpkg-source --before-build.
  47
  48 * For source formats other than `3.0 (quilt)', dgit will do simply
  49     dpkg-source -x.
  50
  51   Again, it will make that into a tree and a commit.
  52
  53 * For source formats with only single file entry in the .dsc, the
  54   (one) tarball is not imported separately (since its tree object
  55   would be the same as the extracted object), and the commit of the
  56   dpkg-source -x output has no parents.
  57
  58 * As currently, there will be a final no-change-to-the-tree
  59   pseudomerge commit which stitches the package into the relevant dgit
  60   suite branch.  (By `pseudomerge' we mean something that looks as if
  61   it was made with git merge -s ours.)
  62
  63 * As currently, dgit will take steps so that none of the git trees
  64   discussed above contain a .pc directory.
  65
  66
  67 This has the following properties:
  68
  69 * Each input tarball is represented by a different commit; in usual
  70   cases these commits will be the same for every upload of the same
  71   upstream version.
  72
  73 * For `3.0 (quilt)' each patch's changes to the upstream files appears
  74   as a single git commit (as is the effect of the debian tarball);
  75   also, there is a commit object whose tree is just the debian/
  76   directory, which might well be the same as certain debian-only git
  77   workflow trees.
  78
  79 * For `1.0' non-native, the effect of the diff is represented as a
  80   commit.  So eg `git blame' will show synthetic commits corresponding
  81   to the correct parts of the input source package.
  82
  83 * It is possible to `git cherry-pick' etc. commits representing `3.0
  84   (quilt)' patches.  It is even possible fish out the patch stack as
  85   git branch and rebase it elsewhere etc., since the patch stack is
  86   represented as a contiguous series of commits which make only the
  87   relevant upstream changes.
  88
  89 * Every orig tarball in the source package is decompressed twice, but
  90   disk space for only one extra copy of its unpacked contents is
  91   needed.  (The converse would be possible in principle but would be
  92   very hard to arrange with the current interfaces provided by the
  93   various tools.)
  94
  95 * No back doors into the innards of dpkg-source (nor changes to
  96   dpkg-dev) are required.
  97
  98 * dgit does grow a dependency on git-buildpackage.
  99
 100 * Knowledge of the source format embedded in dgit is is restricted to
 101   some relatively straightforward processing of filenames found in
 102   .dsc files.
 103
 104 * dgit now depends on dpkg-source -x --skip-patches followed by
 105   dpkg-source --before-build being the same as dpkg-source -x
 106   (for `3.0 (quilt)').