diff tests/test-topic-tutorial.t @ 2829:1c529afd3fef stable

doc: add stack part in topic tutorial

--- 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)