--- a/tests/test-topic-tutorial.t Wed Aug 09 12:52:06 2017 +0200
+++ b/tests/test-topic-tutorial.t Fri Sep 30 18:22:30 2016 +0200
@@ -7,6 +7,13 @@
.. Various setup
$ . "$TESTDIR/testlib/topic_setup.sh"
+ $ cat >> $HGRCPATH << EOF
+ > [experimental]
+ > evolution=all
+ > [extensions]
+ > evolve=
+ > EOF
+
$ hg init server
$ cd server
@@ -576,3 +583,229 @@
t1: Adding hammer
t0^ add a pair of shoes (base)
+Working Within Your Stack
+===========================
+
+Navigating within your stack
+----------------------------
+
+As we saw before `stack` display changesets on your current topic in a clean way:
+
+ $ hg topics --verbose
+ * tools (on branch: default, 3 changesets, 2 behind)
+
+ $ hg stack
+ ### topic: tools
+ ### branch: default, 2 behind
+ t3@ Adding drill (current)
+ t2: Adding saw
+ t1: Adding hammer
+ t0^ add a pair of shoes (base)
+
+You can navigate in your current stack with `previous` and `next`.
+
+`previous` will takes you to the parent of your working directory parent on the same topic.
+
+ $ hg previous
+ 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+ [14] Adding saw
+
+ $ hg stack
+ ### topic: tools
+ ### branch: default, 2 behind
+ t3: Adding drill
+ t2@ Adding saw (current)
+ t1: Adding hammer
+ t0^ add a pair of shoes (base)
+
+`next` will moves take you to the children of your working directory parent on the same topic.
+
+ $ hg next
+ 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+ [15] Adding drill
+
+ $ hg stack
+ ### topic: tools
+ ### branch: default, 2 behind
+ t3@ Adding drill (current)
+ t2: Adding saw
+ t1: Adding hammer
+ t0^ add a pair of shoes (base)
+
+You can also directly access changesets within your stack with the revset `t#`.
+
+ $ hg update t1
+ 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+
+ $ hg stack
+ ### topic: tools
+ ### branch: default, 2 behind
+ t3: Adding drill
+ t2: Adding saw
+ t1@ Adding hammer (current)
+ t0^ add a pair of shoes (base)
+
+Editing your work mid-stack
+---------------------------
+
+It's easy to edit your work inside your stack:
+
+ $ hg stack
+ ### topic: tools
+ ### branch: default, 2 behind
+ t3: Adding drill
+ t2: Adding saw
+ t1@ Adding hammer (current)
+ t0^ add a pair of shoes (base)
+
+ $ hg amend -m "Adding hammer to the shopping list"
+ 2 new unstable changesets
+
+Understanding the current situation with hg log is not so easy:
+
+ $ hg log -G -r "t0::"
+ @ changeset: 18:b7509bd417f8
+ | tag: tip
+ | topic: tools
+ | parent: 12:fbff9bc37a43
+ | user: test
+ | date: Thu Jan 01 00:00:00 1970 +0000
+ | summary: Adding hammer to the shopping list
+ |
+ | o changeset: 17:4cd7c1591a67
+ | | user: test
+ | | date: Thu Jan 01 00:00:00 1970 +0000
+ | | summary: Adding orange juice
+ | |
+ | o changeset: 16:20759cb47ff8
+ |/ parent: 12:fbff9bc37a43
+ | user: test
+ | date: Thu Jan 01 00:00:00 1970 +0000
+ | summary: Adding apple juice
+ |
+ | o changeset: 15:bb1e6254f532
+ | | topic: tools
+ | | user: test
+ | | date: Thu Jan 01 00:00:00 1970 +0000
+ | | trouble: unstable
+ | | summary: Adding drill
+ | |
+ | o changeset: 14:d4f97f32f8a1
+ | | topic: tools
+ | | user: test
+ | | date: Thu Jan 01 00:00:00 1970 +0000
+ | | trouble: unstable
+ | | summary: Adding saw
+ | |
+ | x changeset: 13:a8ab3599d53d
+ |/ topic: tools
+ | user: test
+ | date: Thu Jan 01 00:00:00 1970 +0000
+ | obsolete: rewritten as b7509bd417f8
+ | summary: Adding hammer
+ |
+ o changeset: 12:fbff9bc37a43
+ | user: test
+ ~ date: Thu Jan 01 00:00:00 1970 +0000
+ summary: add a pair of shoes
+
+Fortunately stack show you a better visualization:
+
+ $ hg stack
+ ### topic: tools
+ ### branch: default, 2 behind
+ t3$ Adding drill (unstable)
+ t2$ Adding saw (unstable)
+ t1@ Adding hammer to the shopping list (current)
+ t0^ add a pair of shoes (base)
+
+It's easy to stabilize the situation, `next` has an `--evolve` option:
+
+ $ hg next --evolve
+ move:[14] Adding saw
+ atop:[18] Adding hammer to the shopping list
+ working directory now at d5c51ee5762a
+
+ $ hg stack
+ ### topic: tools
+ ### branch: default, 2 behind
+ t3$ Adding drill (unstable)
+ t2@ Adding saw (current)
+ t1: Adding hammer to the shopping list
+ t0^ add a pair of shoes (base)
+
+One more to go:
+
+ $ hg next --evolve
+ move:[15] Adding drill
+ atop:[19] Adding saw
+ working directory now at bae3758e46bf
+
+ $ hg stack
+ ### topic: tools
+ ### branch: default, 2 behind
+ t3@ Adding drill (current)
+ t2: Adding saw
+ t1: Adding hammer to the shopping list
+ t0^ add a pair of shoes (base)
+
+Let's take a look at `hg log` once again:
+
+ $ hg log -G -r "t0::"
+ @ changeset: 20:bae3758e46bf
+ | tag: tip
+ | topic: tools
+ | user: test
+ | date: Thu Jan 01 00:00:00 1970 +0000
+ | summary: Adding drill
+ |
+ o changeset: 19:d5c51ee5762a
+ | topic: tools
+ | user: test
+ | date: Thu Jan 01 00:00:00 1970 +0000
+ | summary: Adding saw
+ |
+ o changeset: 18:b7509bd417f8
+ | topic: tools
+ | parent: 12:fbff9bc37a43
+ | user: test
+ | date: Thu Jan 01 00:00:00 1970 +0000
+ | summary: Adding hammer to the shopping list
+ |
+ | o changeset: 17:4cd7c1591a67
+ | | user: test
+ | | date: Thu Jan 01 00:00:00 1970 +0000
+ | | summary: Adding orange juice
+ | |
+ | o changeset: 16:20759cb47ff8
+ |/ parent: 12:fbff9bc37a43
+ | user: test
+ | date: Thu Jan 01 00:00:00 1970 +0000
+ | summary: Adding apple juice
+ |
+ o changeset: 12:fbff9bc37a43
+ | user: test
+ ~ date: Thu Jan 01 00:00:00 1970 +0000
+ summary: add a pair of shoes
+
+Multi-headed stack
+------------------
+
+Stack is also very helpful when you have a multi-headed stack:
+
+ $ hg up t1
+ 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+
+ $ echo nails >> shopping
+
+ $ hg commit -m 'Adding nails'
+
+ $ hg stack
+ ### topic: tools (2 heads)
+ ### branch: default, 2 behind
+ t4: Adding drill
+ t3: Adding saw
+ t1^ Adding hammer to the shopping list (base)
+ t2@ Adding nails (current)
+ t1: Adding hammer to the shopping list
+ t0^ add a pair of shoes (base)