- In conjunction with support for multiple independent bases, the

specific version directories are now also configurable to include
multiple, user-defined directories.   When multiple directories exist,
the creation of a revision file with no down revision requires
that the starting directory is indicated; the creation of subsequent
revisions along that lineage will then automatically use that
directory for new files.
fixes #124

2 files changed, 209 insertions, 100 deletions

diff --git a/docs/build/changelog.rst b/docs/build/changelog.rst
index 36a5e77..95a690d 100644
--- a/docs/build/changelog.rst
+++ b/docs/build/changelog.rst
@@ -27,6 +27,22 @@ Changelog
           :ref:`branches`
 
     .. change::
+      :tags: feature, versioning
+      :tickets: 124
+
+      In conjunction with support for multiple independent bases, the
+      specific version directories are now also configurable to include
+      multiple, user-defined directories.   When multiple directories exist,
+      the creation of a revision file with no down revision requires
+      that the starting directory is indicated; the creation of subsequent
+      revisions along that lineage will then automatically use that
+      directory for new files.
+
+      .. seealso::
+
+          :ref:`multiple_version_directories`
+
+    .. change::
       :tags: feature, operations, sqlite
       :tickets: 21
 
diff --git a/docs/build/tutorial.rst b/docs/build/tutorial.rst
index 423923d..9b4e26f 100644
--- a/docs/build/tutorial.rst
+++ b/docs/build/tutorial.rst
@@ -132,6 +132,11 @@ The file generated with the "generic" configuration looks like::
     # versions/ directory
     # sourceless = false
 
+    # version location specification; this defaults
+    # to alembic/versions.  When using multiple version
+    # directories, initial revisions must be specified with --version-path
+    # version_locations = %(here)s/bar %(here)s/bat alembic/versions
+
     # the output encoding used when revision files
     # are written from script.py.mako
     # output_encoding = utf-8
@@ -228,6 +233,12 @@ This file contains the following features:
 
   .. versionadded:: 0.6.4
 
+* ``version_locations`` - an optional list of revision file locations, to
+  allow revisions to exist in multiple directories simultaneously.
+  See :ref:`multiple_bases` for examples.
+
+  .. versionadded:: 0.7.0
+
 * ``output_encoding`` - the encoding to use when Alembic writes the
   ``script.py.mako`` file into a new migration file.  Defaults to ``'utf-8'``.
 
@@ -456,7 +467,7 @@ and ``branches``) will show us full information about each revision::
     Parent: <base>
     Path: /path/to/yourproject/alembic/versions/1975ea83b712_add_account_table.py
 
-        add account table
+        create account table
 
         Revision ID: 1975ea83b712
         Revises:
@@ -566,7 +577,7 @@ and the database did not.  We'd get output like::
 
     $ alembic revision --autogenerate -m "Added account table"
     INFO [alembic.context] Detected added table 'account'
-    Generating /Users/classic/Desktop/tmp/alembic/versions/27c6a30d7c24.py...done
+    Generating /path/to/foo/alembic/versions/27c6a30d7c24.py...done
 
 We can then view our file ``27c6a30d7c24.py`` and see that a rudimentary migration
 is already present::
@@ -1412,10 +1423,10 @@ Both it, as well as ``ae1027a6acf_add_a_column.py``, reference
 ``1975ea83b712_add_account_table.py`` as the "downgrade" revision.  To illustrate::
 
     # main source tree:
-    1975ea83b712 (add account table) -> ae1027a6acf (add a column)
+    1975ea83b712 (create account table) -> ae1027a6acf (add a column)
 
     # branched source tree
-    1975ea83b712 (add account table) -> 27c6a30d7c24 (add shopping cart table)
+    1975ea83b712 (create account table) -> 27c6a30d7c24 (add shopping cart table)
 
 Above, we can see ``1975ea83b712`` is our **branch point**; two distinct versions
 both refer to it as its parent.  The Alembic command ``branches`` illustrates
@@ -1427,7 +1438,7 @@ this fact::
   Branches into: 27c6a30d7c24, ae1027a6acf
   Path: foo/versions/1975ea83b712_add_account_table.py
 
-      add account table
+      create account table
 
       Revision ID: 1975ea83b712
       Revises:
@@ -1442,7 +1453,7 @@ as a ``branchpoint``::
     $ alembic history
     1975ea83b712 -> 27c6a30d7c24 (head), add shopping cart table
     1975ea83b712 -> ae1027a6acf (head), add a column
-    <base> -> 1975ea83b712 (branchpoint), add account table
+    <base> -> 1975ea83b712 (branchpoint), create account table
 
 We can get a view of just the current heads using ``alembic heads``::
 
@@ -1501,7 +1512,7 @@ pass to it an argument such as ``heads``, meaning we'd like to merge all
 heads.  Or, we can pass it individual revision numbers sequentally::
 
     $ alembic merge -m "merge ae1 and 27c" ae1027 27c6a
-      Generating /path/to/foo/versions/53fffde5ad5_merge_ae1_and_27c.py ... done
+      Generating /path/to/foo/alembic/versions/53fffde5ad5_merge_ae1_and_27c.py ... done
 
 Looking inside the new file, we see it as a regular migration file, with
 the only new twist is that ``down_revision`` points to both revisions::
@@ -1556,14 +1567,14 @@ History shows a similar result, as the mergepoint becomes our head::
     ae1027a6acf, 27c6a30d7c24 -> 53fffde5ad5 (head) (mergepoint), merge ae1 and 27c
     1975ea83b712 -> ae1027a6acf, add a column
     1975ea83b712 -> 27c6a30d7c24, add shopping cart table
-    <base> -> 1975ea83b712 (branchpoint), add account table
+    <base> -> 1975ea83b712 (branchpoint), create account table
 
 With a single ``head`` target, a generic ``upgrade`` can proceed::
 
     $ alembic upgrade head
     INFO  [alembic.migration] Context impl PostgresqlImpl.
     INFO  [alembic.migration] Will assume transactional DDL.
-    INFO  [alembic.migration] Running upgrade  -> 1975ea83b712, add account table
+    INFO  [alembic.migration] Running upgrade  -> 1975ea83b712, create account table
     INFO  [alembic.migration] Running upgrade 1975ea83b712 -> 27c6a30d7c24, add shopping cart table
     INFO  [alembic.migration] Running upgrade 1975ea83b712 -> ae1027a6acf, add a column
     INFO  [alembic.migration] Running upgrade ae1027a6acf, 27c6a30d7c24 -> 53fffde5ad5, merge ae1 and 27c
@@ -1584,7 +1595,7 @@ With a single ``head`` target, a generic ``upgrade`` can proceed::
 
     .. sourcecode:: sql
 
-      -- Running upgrade  -> 1975ea83b712, add account table
+      -- Running upgrade  -> 1975ea83b712, create account table
       INSERT INTO alembic_version (version_num) VALUES ('1975ea83b712')
 
       -- Running upgrade 1975ea83b712 -> 27c6a30d7c24, add shopping cart table
@@ -1667,7 +1678,7 @@ from a fresh database and ran ``upgrade heads`` we'd see::
     $ alembic upgrade heads
     INFO  [alembic.migration] Context impl PostgresqlImpl.
     INFO  [alembic.migration] Will assume transactional DDL.
-    INFO  [alembic.migration] Running upgrade  -> 1975ea83b712, add account table
+    INFO  [alembic.migration] Running upgrade  -> 1975ea83b712, create account table
     INFO  [alembic.migration] Running upgrade 1975ea83b712 -> ae1027a6acf, add a column
     INFO  [alembic.migration] Running upgrade 1975ea83b712 -> 27c6a30d7c24, add shopping cart table
 
@@ -1697,7 +1708,7 @@ continue updating the single value down to the previous versions::
     1975ea83b712 (branchpoint)
 
     $ alembic downgrade -1
-    INFO  [alembic.migration] Running downgrade 1975ea83b712 -> , add account table
+    INFO  [alembic.migration] Running downgrade 1975ea83b712 -> , create account table
 
     $ alembic current
 
@@ -1711,7 +1722,7 @@ it guarantees that ``1975ea83b712`` will have been applied, but not that
 any "sibling" versions are applied::
 
     $ alembic upgrade 27c6a
-    INFO  [alembic.migration] Running upgrade  -> 1975ea83b712, add account table
+    INFO  [alembic.migration] Running upgrade  -> 1975ea83b712, create account table
     INFO  [alembic.migration] Running upgrade 1975ea83b712 -> 27c6a30d7c24, add shopping cart table
 
 With ``1975ea83b712`` and ``27c6a30d7c24`` applied, ``ae1027a6acf`` is just
@@ -1751,7 +1762,7 @@ label applied to this revision::
     $ alembic history
     1975ea83b712 -> 27c6a30d7c24 (shoppingcart) (head), add shopping cart table
     1975ea83b712 -> ae1027a6acf (head), add a column
-    <base> -> 1975ea83b712 (branchpoint), add account table
+    <base> -> 1975ea83b712 (branchpoint), create account table
 
 With the label applied, the name ``shoppingcart`` now serves as an alias
 for the ``27c6a30d7c24`` revision specifically.  We can illustrate this
@@ -1795,7 +1806,7 @@ we use the ``--head`` argument, either with the specific revision identifier
 ``27c6a30d7c24``, or more generically using our branchname ``shoppingcart@head``::
 
     $ alembic revision -m "add a shopping cart column"  --head shoppingcart@head
-      Generating /path/to/foo/versions/d747a8a8879_add_a_shopping_cart_column.py ... done
+      Generating /path/to/foo/alembic/versions/d747a8a8879_add_a_shopping_cart_column.py ... done
 
 ``alembic history`` shows both files now part of the ``shoppingcart`` branch::
 
@@ -1803,7 +1814,7 @@ we use the ``--head`` argument, either with the specific revision identifier
     1975ea83b712 -> ae1027a6acf (head), add a column
     27c6a30d7c24 -> d747a8a8879 (shoppingcart) (head), add a shopping cart column
     1975ea83b712 -> 27c6a30d7c24 (shoppingcart), add shopping cart table
-    <base> -> 1975ea83b712 (branchpoint), add account table
+    <base> -> 1975ea83b712 (branchpoint), create account table
 
 We can limit our history operation just to this branch as well::
 
@@ -1817,7 +1828,7 @@ base, we can do that as follows::
     $ alembic history -r :shoppingcart@head
     27c6a30d7c24 -> d747a8a8879 (shoppingcart) (head), add a shopping cart column
     1975ea83b712 -> 27c6a30d7c24 (shoppingcart), add shopping cart table
-    <base> -> 1975ea83b712 (branchpoint), add account table
+    <base> -> 1975ea83b712 (branchpoint), create account table
 
 We can run this operation from the "base" side as well, but we get a different
 result::
@@ -1826,7 +1837,7 @@ result::
     1975ea83b712 -> ae1027a6acf (head), add a column
     27c6a30d7c24 -> d747a8a8879 (shoppingcart) (head), add a shopping cart column
     1975ea83b712 -> 27c6a30d7c24 (shoppingcart), add shopping cart table
-    <base> -> 1975ea83b712 (branchpoint), add account table
+    <base> -> 1975ea83b712 (branchpoint), create account table
 
 When we list from ``shoppingcart@base`` without an endpoint, it's really shorthand
 for ``-r shoppingcart@base:heads``, e.g. all heads, and since ``shoppingcart@base``
@@ -1842,7 +1853,7 @@ if this weren't a head already, we could ask for the "head of the branch
 that includes ``ae1027a6acf``" as follows::
 
     $ alembic revision -m "add another account column" --head ae10@head
-      Generating /Users/classic/dev/alembic/foo/versions/55af2cb1c267_add_another_account_column.py ... done
+      Generating /path/to/foo/alembic/versions/55af2cb1c267_add_another_account_column.py ... done
 
 More Label Syntaxes
 ^^^^^^^^^^^^^^^^^^^
@@ -1863,6 +1874,8 @@ This kind of thing works from history as well::
     $ alembic history -r current:shoppingcart@+2
 
 
+.. _multiple_bases:
+
 Working with Multiple Bases
 ---------------------------
 
@@ -1872,13 +1885,39 @@ if we have multiple heads, ``alembic revision`` allows us to tell it which
 allow us to assign names to branches that we can use in subsequent commands.
 Let's put all these together and refer to a new "base", that is, a whole
 new tree of revision files that will be semi-independent of the account/shopping
-cart revisions we've been working with.
+cart revisions we've been working with.  This new tree will deal with
+database tables involving "networking".
+
+Setting up Multiple Version Directories
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+While optional, it is often the case that when working with multiple bases,
+we'd like different sets of version files to exist within their own directories;
+typically, if an application is organized into several sub-modules, each
+one would have a version directory containing migrations pertinent to
+that module.  So to start out, we can edit ``alembic.ini`` to refer
+to multiple directories;  we'll also state the current ``versions``
+directory as one of them::
+
+  # version location specification; this defaults
+  # to foo/versions.  When using multiple version
+  # directories, initial revisions must be specified with --version-path
+  version_locations = %(here)s/model/networking %(here)s/alembic/versions
+
+The new folder ``%(here)s/model/networking`` is in terms of where
+the ``alembic.ini`` file is as we are using the symbol ``%(here)s`` which
+resolves to this.   When we create our first new revision, the directory
+``model/networking`` will be created automatically if it does not
+exist yet.  Once we've created a revision here, the path is used automatically
+when generating subsequent revision files that refer to this revision tree.
 
 Creating a Labeled Base Revision
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-We want to create a new, labeled branch in one step.  To ensure the branch can
-accommodate this label, we need to ensure our ``script.py.mako`` file, used
+We also want our new branch to have its own name, and for that we want to
+apply a branch label to the base.  In order to achieve this using the
+``alembic revision`` command without editing, we need to ensure our
+``script.py.mako`` file, used
 for generating new revision files, has the appropriate substitutions present.
 If Alembic version 0.7.0 or greater was used to generate the original
 migration environment, this is already done.  However when working with an older
@@ -1894,16 +1933,19 @@ underneath the ``down_revision`` directive::
 
 With this in place, we can create a new revision file, starting up a branch
 that will deal with database tables involving networking; we specify the
-"head" version of ``base`` as well as a ``branch_label``::
+``--head`` version of ``base``, a ``--branch-label`` of ``networking``,
+and the directory we want this first revision file to be
+placed in with ``--version-path``::
 
-    $ alembic revision -m "create networking branch" --head=base --branch-label=networking
-      Generating /Users/classic/dev/alembic/foo/versions/3782d9986ced_create_networking_branch.py ... done
+    $ alembic revision -m "create networking branch" --head=base --branch-label=networking --version-path=model/networking
+      Creating directory /path/to/foo/model/networking ... done
+      Generating /path/to/foo/model/networking/3cac04ae8714_create_networking_branch.py ... done
 
 If we ran the above command and we didn't have the newer ``script.py.mako``
 directive, we'd get this error::
 
   FAILED: Version 3cac04ae8714 specified branch_labels networking, however
-  the migration file foo/versions/3cac04ae8714_create_networking_branch.py
+  the migration file foo/model/networking/3cac04ae8714_create_networking_branch.py
   does not have them; have you upgraded your script.py.mako to include the 'branch_labels'
   section?
 
@@ -1919,23 +1961,24 @@ Once we have a new, permanent (for as long as we desire it to be)
 base in our system, we'll always have multiple heads present::
 
     $ alembic heads
-    3782d9986ced (networking)
-    ae1027a6acf
-    d747a8a8879 (shoppingcart)
+    3cac04ae8714 (networking) (head)
+    27c6a30d7c24 (shoppingcart) (head)
+    ae1027a6acf (head)
 
 When we want to add a new revision file to ``networking``, we specify
-``networking@head`` as the ``--head``::
+``networking@head`` as the ``--head``.  The appropriate version directory
+is now selected automatically based on the head we choose::
 
     $ alembic revision -m "add ip number table" --head=networking@head
-      Generating /Users/classic/dev/alembic/foo/versions/109ec7d132bf_add_ip_number_table.py ... done
+      Generating /path/to/foo/model/networking/109ec7d132bf_add_ip_number_table.py ... done
 
 It's important that we refer to the head using ``networking@head``; if we
-only refer to ``networking``, that refers to only ``3782d9986ced`` specifically;
+only refer to ``networking``, that refers to only ``3cac04ae8714`` specifically;
 if we specify this and it's not a head, ``alembic revision`` will make sure
 we didn't mean to specify the head::
 
     $ alembic revision -m "add DNS table" --head=networking
-      FAILED: Revision 3782d9986ced is not a head revision; please
+      FAILED: Revision 3cac04ae8714 is not a head revision; please
       specify --splice to create a new branch from this revision
 
 As mentioned earlier, as this base is independent, we can view its history
@@ -1943,8 +1986,8 @@ from the base using ``history -r networking@base:``::
 
     $ alembic history -r networking@base:
     109ec7d132bf -> 29f859a13ea (networking) (head), add DNS table
-    3782d9986ced -> 109ec7d132bf (networking), add ip number table
-    <base> -> 3782d9986ced (networking), create networking branch
+    3cac04ae8714 -> 109ec7d132bf (networking), add ip number table
+    <base> -> 3cac04ae8714 (networking), create networking branch
 
 Note this is the same output we'd get at this point if we used
 ``-r :networking@head``.
@@ -1953,97 +1996,147 @@ We may now run upgrades or downgrades freely, among individual branches
 (let's assume a clean database again)::
 
     $ alembic upgrade networking@head
-    INFO  [alembic.migration] Running upgrade  -> 3782d9986ced, create networking branch
-    INFO  [alembic.migration] Running upgrade 3782d9986ced -> 109ec7d132bf, add ip number table
+    INFO  [alembic.migration] Running upgrade  -> 3cac04ae8714, create networking branch
+    INFO  [alembic.migration] Running upgrade 3cac04ae8714 -> 109ec7d132bf, add ip number table
     INFO  [alembic.migration] Running upgrade 109ec7d132bf -> 29f859a13ea, add DNS table
 
 or against the whole thing using ``heads``::
 
     $ alembic upgrade heads
-    INFO  [alembic.migration] Running upgrade  -> 1975ea83b712, add account table
+    INFO  [alembic.migration] Running upgrade  -> 1975ea83b712, create account table
     INFO  [alembic.migration] Running upgrade 1975ea83b712 -> 27c6a30d7c24, add shopping cart table
     INFO  [alembic.migration] Running upgrade 27c6a30d7c24 -> d747a8a8879, add a shopping cart column
     INFO  [alembic.migration] Running upgrade 1975ea83b712 -> ae1027a6acf, add a column
     INFO  [alembic.migration] Running upgrade ae1027a6acf -> 55af2cb1c267, add another account column
 
-Branch and Merge Nuttiness
---------------------------
+Branch Dependencies
+-------------------
+
+When working with multiple roots, it is expected that these different
+revision streams will need to refer to one another.   For example, a new
+revision in ``networking`` which needs to refer to the ``account``
+table will want to establish ``55af2cb1c267, add another account column``,
+the last revision that
+works with the account table, as a dependency.   From a graph perspective,
+this means nothing more that the new file will feature both
+``55af2cb1c267`` and ``29f859a13ea , add DNS table`` as "down" revisions,
+and looks just as though we had merged these two branches together.  However,
+we don't want to consider these as "merged"; we want the two revision
+streams to *remain independent*, even though a version in ``networking``
+is going to reach over into the other stream.  To support this use case,
+Alembic provides a directive known as ``depends_on``, which allows
+a revision file to refer to another as a "dependency", very similar to
+an entry in ``down_revision`` but not quite.
+
+First we will build out our new revision on the ``networking`` branch
+in the usual way::
+
+    $ alembic revision -m "add ip account table" --head=networking@head
+      Generating /path/to/foo/model/networking/2a95102259be_add_ip_account_table.py ... done
+
+Next, we'll add an explicit dependency inside the file, by placing the
+directive ``depends_on='55af2cb1c267'`` underneath the other directives::
 
-We have quite a lot of versioning going on, history overall now shows::
+    # revision identifiers, used by Alembic.
+    revision = '2a95102259be'
+    down_revision = '29f859a13ea'
+    branch_labels = None
+    depends_on='55af2cb1c267'
 
-    $ alembic history
-    109ec7d132bf -> 29f859a13ea (networking) (head), add DNS table
-    3782d9986ced -> 109ec7d132bf (networking), add ip number table
-    <base> -> 3782d9986ced (networking), create networking branch
-    ae1027a6acf -> 55af2cb1c267 (head), add another account column
-    1975ea83b712 -> ae1027a6acf, add a column
-    27c6a30d7c24 -> d747a8a8879 (shoppingcart) (head), add a shopping cart column
-    1975ea83b712 -> 27c6a30d7c24 (shoppingcart), add shopping cart table
-    <base> -> 1975ea83b712 (branchpoint), add account table
+Currently, ``depends_on`` needs to be a real revision number, not a partial
+number or branch name.
 
+We now can see the effect this directive has, when we view the history
+of the ``networking`` branch in terms of "heads", e.g., all the revisions that
+are descendants::
 
-If you actually wanted, all three branches can be merged::
+    $ alembic history -r :networking@head
+    29f859a13ea (55af2cb1c267) -> 2a95102259be (networking) (head), add ip account table
+    109ec7d132bf -> 29f859a13ea (networking), add DNS table
+    3cac04ae8714 -> 109ec7d132bf (networking), add ip number table
+    <base> -> 3cac04ae8714 (networking), create networking branch
+    ae1027a6acf -> 55af2cb1c267 (effective head), add another account column
+    1975ea83b712 -> ae1027a6acf, Add a column
+    <base> -> 1975ea83b712 (branchpoint), create account table
+
+What we see is that the full history of the ``networking`` branch, in terms
+of an "upgrade" to the "head", will include that the tree building
+up ``55af2cb1c267 (effective head), add another account column``
+will be pulled in first.   Interstingly, we don't see this displayed
+when we display history in the other direction, e.g. from ``networking@base``::
 
-    $ alembic merge -m "merge all three branches" heads
-      Generating /Users/classic/dev/alembic/foo/versions/3180f4d6e81d_merge_all_three_branches.py ... done
+    $ alembic history -r networking@base:
+    29f859a13ea (55af2cb1c267) -> 2a95102259be (networking) (head), add ip account table
+    109ec7d132bf -> 29f859a13ea (networking), add DNS table
+    3cac04ae8714 -> 109ec7d132bf (networking), add ip number table
+    <base> -> 3cac04ae8714 (networking), create networking branch
 
-    $ alembic upgrade head
-    INFO  [alembic.migration] Running upgrade 29f859a13ea, 55af2cb1c267, d747a8a8879 -> 3180f4d6e81d, merge all three branches
+The reason for the discrepancy is that displaying history from the base
+shows us what would occur if we ran a downgrade operation, instead of an
+upgrade.  If we downgraded all the files in ``networking`` using
+``networking@base``, the dependencies aren't affected, they're left in place.
 
-at which point, we're back to one head, but note!  This head has **two** labels
-now::
+We also see something odd if we view ``heads`` at the moment::
 
     $ alembic heads
-    3180f4d6e81d (shoppingcart, networking)
+    2a95102259be (networking) (head)
+    27c6a30d7c24 (shoppingcart) (head)
+    55af2cb1c267 (effective head)
+
+The head file that we used as a "dependency", ``55af2cb1c267`` is displayed
+as an "effective" head, which we can see also in the history display earlier.
+What this means is that at the moment, if we were to upgrade all versions
+to the top, the ``55af2cb1c267`` revision number would not actually be
+present in the ``alembic_version`` table; this is because it does not have
+a branch of its own subsequent to the ``2a95102259be`` revision which depends
+on it::
 
-    $ alembic current --verbose
-    Current revision(s) for postgresql://scott:XXXXX@localhost/test:
-    Rev: 3180f4d6e81d (head) (mergepoint)
-    Merges: 29f859a13ea, 55af2cb1c267, d747a8a8879
-    Branch names: shoppingcart, networking
-    Path: foo/versions/3180f4d6e81d_merge_all_three_branches.py
+    $ alembic upgrade heads
+    INFO  [alembic.migration] Running upgrade 29f859a13ea, 55af2cb1c267 -> 2a95102259be, add ip account table
 
-        merge all three branches
+    $ alembic current
+    2a95102259be (head)
+    27c6a30d7c24 (head)
 
-        Revision ID: 3180f4d6e81d
-        Revises: 29f859a13ea, 55af2cb1c267, d747a8a8879
-        Create Date: 2014-11-20 16:27:56.395477
+If we add a new revision onto ``55af2cb1c267``, now this branch again becomes
+a "real" branch which would have its own entry in the database::
 
-When labels are combined like this, it means that ``networking@head`` and
-``shoppingcart@head`` are ultimately along the same branch, as is the
-unnamed ``ae1027a6acf`` branch since we've merged everything together.
-``alembic history`` when leading from ``networking@base:``,
-``:shoppingcart@head`` or similar will show the whole tree at this point::
+    $ alembic revision -m "more account changes" --head=55af2cb@head
+      Generating /path/to/foo/versions/34e094ad6ef1_more_account_changes.py ... done
 
-    $ alembic history -r :shoppingcart@head
-    29f859a13ea, 55af2cb1c267, d747a8a8879 -> 3180f4d6e81d (networking, shoppingcart) (head) (mergepoint), merge all three branches
+    $ alembic upgrade heads
+    INFO  [alembic.migration] Running upgrade 55af2cb1c267 -> 34e094ad6ef1, more account changes
+
+    $ alembic current
+    2a95102259be (head)
+    27c6a30d7c24 (head)
+    34e094ad6ef1 (head)
+
+
+For posterity, the revision tree now looks like::
+
+    $ alembic history
+    29f859a13ea (55af2cb1c267) -> 2a95102259be (networking) (head), add ip account table
     109ec7d132bf -> 29f859a13ea (networking), add DNS table
-    3782d9986ced -> 109ec7d132bf (networking), add ip number table
-    <base> -> 3782d9986ced (networking), create networking branch
+    3cac04ae8714 -> 109ec7d132bf (networking), add ip number table
+    <base> -> 3cac04ae8714 (networking), create networking branch
+    1975ea83b712 -> 27c6a30d7c24 (shoppingcart) (head), add shopping cart table
+    55af2cb1c267 -> 34e094ad6ef1 (head), more account changes
     ae1027a6acf -> 55af2cb1c267, add another account column
-    1975ea83b712 -> ae1027a6acf, add a column
-    27c6a30d7c24 -> d747a8a8879 (shoppingcart), add a shopping cart column
-    1975ea83b712 -> 27c6a30d7c24 (shoppingcart), add shopping cart table
-    <base> -> 1975ea83b712 (branchpoint), add account table
-
-It follows then that the "branch labels" feature is useful for branches
-that are **unmerged**.  Once branches are merged into a single stream, labels
-are not particularly useful as they tend to refer to the whole revision
-stream in any case.  They can of course be removed from revision files
-at the point at which they are no longer useful, or moved to other files.
-
-For posterity, here's the graph of the whole thing::
-
-                         --- ae10 --> 55af --->--
-                       /                         \
-    <base> --> 1975 -->                          |
-                       \                         |
-                         --- 27c6 --> d747 -->   |
-                        (shoppingcart)        \  |
-                                              +--+-----> 3180
-                                                 |    (networking,
-                                                /      shoppingcart)
-    <base> --> 3782 -----> 109e ----> 29f8 --->
+    1975ea83b712 -> ae1027a6acf, Add a column
+    <base> -> 1975ea83b712 (branchpoint), create account table
+
+
+                        --- 27c6 --> d747 --> <head>
+                       /   (shoppingcart)
+    <base> --> 1975 -->
+                       \
+                         --- ae10 --> 55af --> <head>
+                                        ^
+                                        +--------+ (dependency)
+                                                 |
+                                                 |
+    <base> --> 3782 -----> 109e ----> 29f8 ---> 2a95 --> <head>
              (networking)