git branch pristine
-.. todo::
-
- The following text and graph should be put in a more general overview of
- the topology of Wizard git repositories.
-
-From the point of view of the pristine branch pointer, history should be a
-straight-forward progression of versions. Once you have more versions,
-it will look something like:
-
-.. digraph:: pristine_dag
-
- rankdir=LR
- node [shape=square]
- subgraph cluster_pristine {
- a -> b -> c
- a [label="1.0"]
- b [label="1.1"]
- c [label="2.0"]
- label = "pristine"
- color = white
- labeljust = r
- }
-
Scriptsify
----------
able to reconstruct a version of the application that was actually used, the
better off we will be when we try to subsequently upgrade those applications.
-.. todo::
-
- The following text and graph should be put in a more general overview of
- the topology of Wizard git repositories.
-
-To give you an idea of what the Git history graph will look like when we
-are done, here is the graph from before, but augmented with the scripts versions:
-
-.. digraph:: master_dag
-
- rankdir=LR
- node [shape=square]
- subgraph cluster_pristine {
- a -> b -> c
- a [label="1.0"]
- b [label="1.1"]
- c [label="2.0"]
- label = "pristine"
- color = white
- labeljust = r
- }
- subgraph cluster_master {
- as -> bs -> cs
- as [label="1.0-scripts"]
- bs [label="1.1-scripts"]
- cs [label="2.0-scripts"]
- label = "master"
- color = white
- labeljust = r
- }
- a -> as
- b -> bs
- c -> cs
- a []
-
First things first: verify that we are on the master branch::
git checkout master
--- /dev/null
+Anatomy of a repository
+=======================
+
+:Author: Edward Z. Yang <ezyang@mit.edu>
+
+Wizard is all about using Git's excellent directed acyclic graph model of
+history to perform file-system merges as well as keep track of user
+changes on top of ours. If you are not familiar with the way Git internally
+represents commits, I highly recommend reading
+`Git for Computer Scientists <http://eagain.net/articles/git-for-computer-scientists/>`_
+first.
+
+Wizard takes a simplified view of upstream: from the point of view of the
+pristine branch pointer, history should be a straight-forward progression of
+versions. Internal development history is discarded, and there is a one-to-one
+mapping of releases and commits.
+
+.. digraph:: pristine_dag
+
+ node [shape=square]
+ subgraph cluster_pristine {
+ c -> b -> a
+ a [label="1.0"]
+ b [label="1.1"]
+ c [label="2.0"]
+ label = "pristine"
+ color = white
+ }
+
+From here, we build "scriptsified" versions of the application, which
+correspond to the master branch. Every time upstream releases an update,
+we import it into our pristine branch, and then merge the changes into
+master.
+
+.. digraph:: master_dag
+
+ node [shape=square]
+ subgraph cluster_master {
+ cs -> bs -> as
+ as [label="1.0-scripts"]
+ bs [label="1.1-scripts"]
+ cs [label="2.0-scripts"]
+ label = "master"
+ color = white
+ }
+ subgraph cluster_pristine {
+ c -> b -> a
+ a [label="1.0"]
+ b [label="1.1"]
+ c [label="2.0"]
+ label = "pristine"
+ color = white
+ }
+ as -> a
+ bs -> b
+ cs -> c
+
+If there was an error in a deployed scripts version, you might see a structure
+like this:
+
+.. digraph:: scripts2_dag
+
+ node [shape=square]
+ subgraph cluster_master {
+ cs -> bs2 -> bs -> as
+ as [label="1.0-scripts"]
+ bs [label="1.1-scripts",style=dashed]
+ bs2 [label="1.1-scripts2"]
+ cs [label="2.0-scripts"]
+ label = "master"
+ color = white
+ }
+ subgraph cluster_pristine {
+ c -> b -> a
+ a [label="1.0"]
+ b [label="1.1"]
+ c [label="2.0"]
+ label = "pristine"
+ color = white
+ }
+ as -> a
+ bs -> b
+ cs -> c
+
+But such occasions should be rare. In this particular graph, ``1.1-scripts`` was
+defective, and ``1.1-scripts2`` was the fixed version.
+
+There is another layer to this graph, which is not visible from the repository:
+it contains the user's commits and is unique for each user.
+
+.. digraph:: master_dag
+
+ node [shape=square]
+ subgraph cluster_user {
+ node [shape=ellipse]
+ u -> x -> y -> z
+ u [style=filled,fillcolor=red,fontcolor=white,color=red]
+ label = "master"
+ color = white
+ }
+ subgraph cluster_master {
+ bs -> as
+ as [label="1.0-scripts"]
+ bs [label="1.1-scripts"]
+ color = white
+ }
+ subgraph cluster_pristine {
+ b -> a
+ a [label="1.0"]
+ b [label="1.1"]
+ label = "pristine"
+ color = white
+ }
+ as -> a
+ bs -> b
+ x -> bs
+ z -> as
+
+The red node ``u`` represents uncommitted changes that may exist
+in a user's checkout at any given time. The untagged commits
+``x``, ``y`` and ``z`` each have a particular story: ``z`` was
+the commit generated when the install took place and the user's
+specific configuration was versioned. ``y`` was the pre-upgrade
+commit generated so that we could then perform a merge; ``x`` is
+the resulting merge commit.