Here we describe the update algorithm.  This is responsible for
refreshing patches against updated versions of their dependencies,
for merging different versions of the various braches created by
distributed development, and for implementing decisions to add and
remove dependencies from patches.

Broadly speaking the update proceeds as follows: during the Ranking
phase we construct the intended graph of dependencies between patches
(and incidentally select a merge order for the base branch of each
patch).  Then during the Traversal phase we walk that graph from the
bottom up, constructing for each patch by a series of merges and other
operations first a new base branch head commit and then a new tip
branch head commit.  These new head commits are maximums - that is,
each has as ancestors all of its branches' sources and indeed all
relevant commits in that branch.

We have two possible strategies for constructing new base branch
heads: we can either Merge (works incrementally even if there the
patch has multiple dependencies, but may sometimes not be possible) or
we can Regenerate (trivial if there is a single dependency, and is
always possible, but may involve the user re-resolving conflicts if
there are multiple dependencies).

\section{Notation}

\begin{basedescript}{
\desclabelwidth{5em}
\desclabelstyle{\nextlinelabel}
}
\item[ $\depsreqof{K}$ ]
The set of direct dependencies (in the form $\py$)
requested in the commit $K$ ($K \in \pn$) for the patch $\p$.

\item[ $\pc \hasdirdep \p$ ]
The patch $\pc$ has as a direct dependency the
patch $\p$.  This is an acyclic relation.

\item[ $\p \hasdep \pq$ ]
The patch $\p$ has as direct or indirect dependency the
patch $\pq$.
Acyclic; the completion of $\hasdirdep$ into a
partial order.

\item[ $\pendsof{\set J}{\p}$ ]
Convenience notation for
the $\le$-maximal elements of $\bigcup_{J \in \set J} \pendsof{J}{\p}$
(where $\set J$ is some set of commits).

\item[ $\pendsof{\set X}{\p} \le T$ ]
Convenience notation for
$\bigforall_{E \in \pendsof{\set X}{\p}} E \le T$

\item[ $\allsrcs$ ]
$\bigcup_{\p \in \allpatches} \set H^{\pn} \cup \set H^{\py}$.
All the input commits to the update algorithm.  (See below.)

\item[ $\set H^{\pc^{_=/-}}$ ]

The existing head commit(s) $\set H$ of the branch $\pc^{+/-}$.
These are the heads which will be merged and used in this update.
This will include the current local and remote git refs, as desired.
Obtained from the function $h$ (see below).

%\item[ $\set E_{\pc}$ ]
%$ \bigcup_i \pendsof{S_{\pc,i}}{\pc} $.
%All the ends of $\pc$ in the sources.

%\item[ $ \tipzc, \tipcc, \tipuc, \tipfc $ ]
%The git ref for the Topbloke commit set $\pc$: respectively,
%the original, current, updated, and final values.

\end{basedescript}

\stdsection{Inputs to the update algorithm}

\begin{basedescript}{
\desclabelwidth{5em}
\desclabelstyle{\nextlinelabel}
}
\item[ $\pc_0$ ]
The topmost patch which we are trying to update.  This and
all of its dependencies will be updated.

\item[ $h : \pc^{+/-} \mapsto \set H^{\pc^{+/-}}$ ]
Function for getting the existing heads $\set H$ of the branch $\pc^{+/-}$.

\item[ $w : \pc^{+/-} \mapsto \set W_0^{\pc^{+/-}}$ ]

Function for getting the existing local head of the branch
$\pc^{+/-}$.  I.e., the current value of the branch ref for $\pc^{+/-}$.
$W_0^{\pc^{+/-}} \in \set H$.

\item[ $g : \pc, \Gamma \mapsto \Gamma'$ ]
Function to allow explicit adjustment of the direct dependencies
of $\pc$.  It is provided with a putative set of direct dependencies
$\Gamma$ computed as an appropriate merge of the dependencies requested by the
sources and should return the complete actual set $\Gamma'$ of direct
dependencies to use.  This allows the specification of any desired
(acyclic) relations $\hasdirdep$ and $\hasdep$.

\end{basedescript}

\stdsection{Important variables and values in the update algorithm}

\begin{basedescript}{
\desclabelwidth{5em}
\desclabelstyle{\nextlinelabel}
}
\item[ $\Gamma_{\pc}$ ]
The desired direct dependencies of $\pc$, a set of patches.

\item[ $\allpatches$ ]
The set of all the patches we are dealing with (constructed
during the update algorithm).

\item[ $\tipcn, \tipcy$ ]
The new tips of the git branches $\pcn$ and $\pcy$, containing
all the appropriate commits (and the appropriate other patches),
as generated by the Traversal phase of the update algorithm.

\item[ $\allreach$ ]
The set of all reachable commits.

A reachable commit is one we might refer to explicitly in any of these
algorithms, and any ancestor of such a commit.  We explicitly
enumerate all of the input commits ($\allsrcs$), so the reachable
commits are originally the input commits and their ancestors.

$\allreach$ varies over time as we generate more commits.  Each
commit we generate will have only reachable commits as ancestors, so
generating a new commit (only) adds that new commit to $\allreach$.

\item[ $\allreachof{\py}$ ]
The set of reachable commits at the point where we have just generated
$\tippy$, i.e. just after $\alg{Merge-Tip}(\p)$.

\end{basedescript}
