doc/repo.rst

   1 Anatomy of a repository
   2 =======================
   3
   4 :Author: Edward Z. Yang <ezyang@mit.edu>
   5
   6 Wizard is all about using Git's excellent directed acyclic graph model of
   7 history to perform file-system merges as well as keep track of user
   8 changes on top of ours.  If you are not familiar with the way Git internally
   9 represents commits, I highly recommend reading
  10 `Git for Computer Scientists <http://eagain.net/articles/git-for-computer-scientists/>`_
  11 first.
  12
  13 Wizard takes a simplified view of upstream: from the point of view of the
  14 pristine branch pointer, history should be a straight-forward progression of
  15 versions.  Internal development history is discarded, and there is a one-to-one
  16 mapping of releases and commits.
  17
  18 .. digraph:: pristine_dag
  19
  20     node [shape=square]
  21     subgraph cluster_pristine {
  22         c -> b -> a
  23         a [label="1.0"]
  24         b [label="1.1"]
  25         c [label="2.0"]
  26         label = "pristine"
  27         color = white
  28     }
  29
  30 From here, we build "scriptsified" versions of the application, which
  31 correspond to the master branch.  Every time upstream releases an update,
  32 we import it into our pristine branch, and then merge the changes into
  33 master.
  34
  35 .. digraph:: master_dag
  36
  37     node [shape=square]
  38     subgraph cluster_master {
  39         cs -> bs -> as
  40         as [label="1.0-scripts"]
  41         bs [label="1.1-scripts"]
  42         cs [label="2.0-scripts"]
  43         label = "master"
  44         color = white
  45     }
  46     subgraph cluster_pristine {
  47         c -> b -> a
  48         a [label="1.0"]
  49         b [label="1.1"]
  50         c [label="2.0"]
  51         label = "pristine"
  52         color = white
  53     }
  54     as -> a
  55     bs -> b
  56     cs -> c
  57
  58 If there was an error in a deployed scripts version, you might see a structure
  59 like this:
  60
  61 .. digraph:: scripts2_dag
  62
  63     node [shape=square]
  64     subgraph cluster_master {
  65         cs -> bs2 -> bs -> as
  66         as [label="1.0-scripts"]
  67         bs [label="1.1-scripts",style=dashed]
  68         bs2 [label="1.1-scripts2"]
  69         cs [label="2.0-scripts"]
  70         label = "master"
  71         color = white
  72     }
  73     subgraph cluster_pristine {
  74         c -> b -> a
  75         a [label="1.0"]
  76         b [label="1.1"]
  77         c [label="2.0"]
  78         label = "pristine"
  79         color = white
  80     }
  81     as -> a
  82     bs -> b
  83     cs -> c
  84
  85 But such occasions should be rare.  In this particular graph, ``1.1-scripts`` was
  86 defective, and ``1.1-scripts2`` was the fixed version.
  87
  88 There is another layer to this graph, which is not visible from the repository:
  89 it contains the user's commits and is unique for each user.
  90
  91 .. digraph:: master_dag
  92
  93     node [shape=square]
  94     subgraph cluster_user {
  95         node [shape=ellipse]
  96         u -> x -> y -> z
  97         u [style=filled,fillcolor=red,fontcolor=white,color=red]
  98         label = "master"
  99         color = white
 100     }
 101     subgraph cluster_master {
 102         bs -> as
 103         as [label="1.0-scripts"]
 104         bs [label="1.1-scripts"]
 105         color = white
 106     }
 107     subgraph cluster_pristine {
 108         b -> a
 109         a [label="1.0"]
 110         b [label="1.1"]
 111         label = "pristine"
 112         color = white
 113     }
 114     as -> a
 115     bs -> b
 116     x -> bs
 117     z -> as
 118
 119 The red node ``u`` represents uncommitted changes that may exist
 120 in a user's checkout at any given time.  The untagged commits
 121 ``x``, ``y`` and ``z`` each have a particular story: ``z`` was
 122 the commit generated when the install took place and the user's
 123 specific configuration was versioned.  ``y`` was the pre-upgrade
 124 commit generated so that we could then perform a merge; ``x`` is
 125 the resulting merge commit.
 126
 127 All user repositories are initialized with ``--shared``, which means
 128 they take no space footprint at the very beginning.  However, this also
 129 makes it vitally important that the canonical repository in the scripts
 130 locker not lose revisions.