diff tests/test-topic-tutorial.t @ 2013:2e8e4619a240

tutorial: add a first version of the tutorial with the basics

This is probably not wonderful but at least we have a base.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/tests/test-topic-tutorial.t	Thu Sep 29 16:48:13 2016 +0200
@@ -0,0 +1,311 @@
+==============
+Topic Tutorial
+==============
+
+.. This test file is also supposed to be able to compile as a rest file.
+
+
+.. Some Setup::
+
+  $ . "$TESTDIR/testlib"
+  $ hg init server
+  $ cd server
+  $ cat >> .hg/hgrc << EOF
+  > [ui]
+  > user= Shopping Master
+  > EOF
+  $ cat >> shopping << EOF
+  > Spam
+  > Whizzo butter
+  > Albatross
+  > Rat (rather a lot)
+  > Jugged fish
+  > Blancmange
+  > Salmon mousse
+  > EOF
+  $ hg commit -A -m "Shopping list"
+  adding shopping
+  $ cd ..
+  $ hg clone server client
+  updating to branch default
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+  $ cd client
+  $ cat >> .hg/hgrc << EOF
+  > [ui]
+  > user= Tutorial User
+  > EOF
+
+Topic branches are lightweight branches which disappear when changes are
+finalized (move to the public phase). They can help users to organise and share
+their unfinished work.
+
+Topic Basics
+============
+
+Let's says we use Mercurial to manage our shopping list::
+
+  $ hg log --graph
+  @  changeset:   0:38da43f0a2ea
+     tag:         tip
+     user:        test
+     date:        Thu Jan 01 00:00:00 1970 +0000
+     summary:     Shopping list
+  
+
+We are about to do some edition to this list and would like to do them within
+a topic. Creating a new topic is done using the ``topic`` command::
+
+  $ hg topic food
+
+As for named branch, our topic is active but it does not contains any changesets yet::
+
+  $ hg topic
+   * food
+  $ hg summary
+  parent: 0:38da43f0a2ea tip
+   Shopping list
+  branch: default
+  commit: (clean)
+  update: (current)
+  topic:  food
+  $ hg log --graph
+  @  changeset:   0:38da43f0a2ea
+     tag:         tip
+     user:        test
+     date:        Thu Jan 01 00:00:00 1970 +0000
+     summary:     Shopping list
+  
+
+Our next commit will be part of the active topic::
+
+  $ cat >> shopping << EOF
+  > Egg
+  > Suggar
+  > Vinegar
+  > Oil
+  > EOF
+  $ hg commit -m "adding condiments"
+  $ hg log --graph --rev 'topic("food")'
+  @  changeset:   1:13900241408b
+  |  tag:         tip
+  ~  topic:       food
+     user:        test
+     date:        Thu Jan 01 00:00:00 1970 +0000
+     summary:     adding condiments
+  
+
+And future commit will be part of that topic too::
+
+  $ cat >> shopping << EOF
+  > Bananas
+  > Pear
+  > Apple
+  > EOF
+  $ hg commit -m "adding fruits"
+  $ hg log --graph --rev 'topic("food")'
+  @  changeset:   2:287de11b401f
+  |  tag:         tip
+  |  topic:       food
+  |  user:        test
+  |  date:        Thu Jan 01 00:00:00 1970 +0000
+  |  summary:     adding fruits
+  |
+  o  changeset:   1:13900241408b
+  |  topic:       food
+  ~  user:        test
+     date:        Thu Jan 01 00:00:00 1970 +0000
+     summary:     adding condiments
+  
+
+We can get a compact view of the content of our topic using the ``stack`` command::
+
+  $ hg stack
+  ### topic: food
+  ### branch: default
+  t2@ adding fruits (current)
+  t1: adding condiments
+    ^ Shopping list
+
+The topic desactivate when we update away from it::
+
+  $ hg up default
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+  $ hg topic
+     food
+
+Note that ``default`` (name of the branch) now refers to the tipmost changeset of default without a topic::
+
+  $ hg log --graph
+  o  changeset:   2:287de11b401f
+  |  tag:         tip
+  |  topic:       food
+  |  user:        test
+  |  date:        Thu Jan 01 00:00:00 1970 +0000
+  |  summary:     adding fruits
+  |
+  o  changeset:   1:13900241408b
+  |  topic:       food
+  |  user:        test
+  |  date:        Thu Jan 01 00:00:00 1970 +0000
+  |  summary:     adding condiments
+  |
+  @  changeset:   0:38da43f0a2ea
+     user:        test
+     date:        Thu Jan 01 00:00:00 1970 +0000
+     summary:     Shopping list
+  
+
+And updating back to the topic reactivate it::
+
+  $ hg up food
+  switching to topic food
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+  $ hg topic
+   * food
+
+The name used for updating does not affect the activation of the topic, updating to a revision part of a topic will activate it in all cases::
+
+  $ hg up default
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+  $ hg up --rev 'desc("condiments")'
+  switching to topic food
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+  $ hg topic
+   * food
+
+.. server side activity::
+
+  $ cd ../server/
+  $ cat > shopping << EOF
+  > T-Shirt
+  > Trousers
+  > Spam
+  > Whizzo butter
+  > Albatross
+  > Rat (rather a lot)
+  > Jugged fish
+  > Blancmange
+  > Salmon mousse
+  > EOF
+  $ hg commit -A -m "Adding clothes"
+  $ cd ../client
+
+Topic will also affect rebase and merge destination. Let's pull the latest update from the main server::
+
+  $ hg pull
+  pulling from $TESTTMP/server
+  searching for changes
+  adding changesets
+  adding manifests
+  adding file changes
+  added 1 changesets with 1 changes to 1 files (+1 heads)
+  (run 'hg heads' to see heads)
+  $ hg log -G
+  o  changeset:   3:6104862e8b84
+  |  tag:         tip
+  |  parent:      0:38da43f0a2ea
+  |  user:        test
+  |  date:        Thu Jan 01 00:00:00 1970 +0000
+  |  summary:     Adding clothes
+  |
+  | o  changeset:   2:287de11b401f
+  | |  topic:       food
+  | |  user:        test
+  | |  date:        Thu Jan 01 00:00:00 1970 +0000
+  | |  summary:     adding fruits
+  | |
+  | @  changeset:   1:13900241408b
+  |/   topic:       food
+  |    user:        test
+  |    date:        Thu Jan 01 00:00:00 1970 +0000
+  |    summary:     adding condiments
+  |
+  o  changeset:   0:38da43f0a2ea
+     user:        test
+     date:        Thu Jan 01 00:00:00 1970 +0000
+     summary:     Shopping list
+  
+
+The topic head will not be considered when merge from the new head of the branch::
+
+  $ hg up default
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+  $ hg merge
+  abort: branch 'default' has one head - please merge with an explicit rev
+  (run 'hg heads' to see all heads)
+  [255]
+
+But the topic will see that branch head as a valid destination::
+
+  $ hg up food
+  switching to topic food
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+  $ hg rebase
+  rebasing 1:13900241408b "adding condiments"
+  merging shopping
+  rebasing 2:287de11b401f "adding fruits"
+  merging shopping
+  $ hg log --graph
+  @  changeset:   5:2d50db8b5b4c
+  |  tag:         tip
+  |  topic:       food
+  |  user:        test
+  |  date:        Thu Jan 01 00:00:00 1970 +0000
+  |  summary:     adding fruits
+  |
+  o  changeset:   4:4011b46eeb33
+  |  topic:       food
+  |  user:        test
+  |  date:        Thu Jan 01 00:00:00 1970 +0000
+  |  summary:     adding condiments
+  |
+  o  changeset:   3:6104862e8b84
+  |  parent:      0:38da43f0a2ea
+  |  user:        test
+  |  date:        Thu Jan 01 00:00:00 1970 +0000
+  |  summary:     Adding clothes
+  |
+  o  changeset:   0:38da43f0a2ea
+     user:        test
+     date:        Thu Jan 01 00:00:00 1970 +0000
+     summary:     Shopping list
+  
+
+The topic information will fade out when we publish the changesets::
+
+  $ hg topic
+     food
+  $ hg push
+  pushing to $TESTTMP/server
+  searching for changes
+  adding changesets
+  adding manifests
+  adding file changes
+  added 2 changesets with 2 changes to 1 files
+  2 new obsolescence markers
+  $ hg topic
+  $ hg log --graph
+  @  changeset:   5:2d50db8b5b4c
+  |  tag:         tip
+  |  user:        test
+  |  date:        Thu Jan 01 00:00:00 1970 +0000
+  |  summary:     adding fruits
+  |
+  o  changeset:   4:4011b46eeb33
+  |  user:        test
+  |  date:        Thu Jan 01 00:00:00 1970 +0000
+  |  summary:     adding condiments
+  |
+  o  changeset:   3:6104862e8b84
+  |  parent:      0:38da43f0a2ea
+  |  user:        test
+  |  date:        Thu Jan 01 00:00:00 1970 +0000
+  |  summary:     Adding clothes
+  |
+  o  changeset:   0:38da43f0a2ea
+     user:        test
+     date:        Thu Jan 01 00:00:00 1970 +0000
+     summary:     Shopping list
+  
+  $ hg up default
+  0 files updated, 0 files merged, 0 files removed, 0 files unresolved