changeset 2014:cd6d32a0155c

tutorial: add a second part about having multiple topic

--- a/tests/test-topic-tutorial.t	Thu Sep 29 16:48:13 2016 +0200
+++ b/tests/test-topic-tutorial.t	Fri Sep 30 18:21:50 2016 +0200
@@ -309,3 +309,160 @@
   
   $ hg up default
   0 files updated, 0 files merged, 0 files removed, 0 files unresolved
+
+Working with Multiple Topics
+============================
+
+In the above example, topic are not bring much benefit since you only have one
+line of developement. Topic start to be more useful when you have to work on
+multiple features are the same time.
+
+We might go shopping in a hardware store in the same go, so let's add some
+tools to the shopping list withing a new topic::
+
+  $ hg topic tools
+  $ echo hammer >> shopping
+  $ hg ci -m 'Adding hammer'
+  $ echo saw >> shopping
+  $ hg ci -m 'Adding saw'
+  $ echo drill >> shopping
+  $ hg ci -m 'Adding drill'
+
+But are not sure to actually go in the hardward store, so in the meantime, we
+want to extend the list with drinks. We go back to the official default branch
+and start a new topic::
+
+  $ hg up default
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+  $ hg topic drinks
+  $ echo 'apple juice' >> shopping
+  $ hg ci -m 'Adding apple juice'
+  $ echo 'orange juice' >> shopping
+  $ hg ci -m 'Adding orange juice'
+
+We now have two topics::
+
+  $ hg topic
+   * drinks
+     tools
+
+The information ``hg stack`` command adapt to the active topic::
+
+  $ hg stack
+  ### topic: drinks
+  ### branch: default
+  t2@ Adding orange juice (current)
+  t1: Adding apple juice
+    ^ adding fruits
+  $ hg up tools
+  switching to topic tools
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+  $ hg stack
+  ### topic: tools
+  ### branch: default
+  t3@ Adding drill (current)
+  t2: Adding saw
+  t1: Adding hammer
+    ^ adding fruits
+
+They are seen as independant branch by Mercurial. No rebase or merge betwen them will be attempted by default::
+
+  $ hg rebase
+  nothing to rebase
+  [1]
+
+.. server activity::
+
+  $ cd ../server
+  $ hg up
+  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
+  $ mv shopping foo
+  $ echo 'Coat' > shopping
+  $ cat foo >> shopping
+  $ hg ci -m 'add a coat'
+  $ echo 'Coat' > shopping
+  $ echo 'Shoes' >> shopping
+  $ cat foo >> shopping
+  $ hg rm foo
+  not removing foo: file is untracked
+  [1]
+  $ hg ci -m 'add a pair of shoes'
+  $ cd ../client
+
+Lets see what other people did in the mean time::
+
+  $ hg pull
+  pulling from $TESTTMP/server
+  searching for changes
+  adding changesets
+  adding manifests
+  adding file changes
+  added 2 changesets with 2 changes to 1 files (+1 heads)
+  (run 'hg heads' to see heads)
+
+There is new changes! We can simply use ``hg rebase`` to update our changeset on top of the latest::
+
+  $ hg rebase
+  rebasing 6:183984ef46d1 "Adding hammer"
+  merging shopping
+  rebasing 7:cffff85af537 "Adding saw"
+  merging shopping
+  rebasing 8:34255b455dac "Adding drill"
+  merging shopping
+
+But what about the other topic? You can use 'hg topic --verbose' to see information about them::
+
+  $ hg topic --verbose
+     drinks (on branch: default, 2 changesets, 2 behind)
+     tools  (on branch: default, 3 changesets)
+
+The "2 behind" is telling you that there is 2 new changesets on the named branch of the topic. You need to merge or rebase to incorporate them.
+
+Pushing that topic would create a new heads will be prevented::
+
+  $ hg push --rev drinks
+  pushing to $TESTTMP/server
+  searching for changes
+  abort: push creates new remote head 70dfa201ed73!
+  (merge or see 'hg help push' for details about pushing new heads)
+  [255]
+
+
+Even after a rebase Pushing all active topics at the same time will complains about the multiple heads it would create on that branch::
+
+  $ hg rebase -b drinks
+  rebasing 9:8dfa45bd5e0c "Adding apple juice"
+  merging shopping
+  rebasing 10:70dfa201ed73 "Adding orange juice"
+  merging shopping
+  switching to topic tools
+  $ hg push
+  pushing to $TESTTMP/server
+  searching for changes
+  abort: push creates new remote head 4cd7c1591a67!
+  (merge or see 'hg help push' for details about pushing new heads)
+  [255]
+
+Publishing only one of them is allowed (as long as it does not create a new branch head has we just saw in the previous case)::
+
+  $ hg push -r drinks
+  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
+
+The publishing topic has now vanished, and the one still draft is now marked as "behind"::
+
+  $ hg topic --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
+    ^ add a pair of shoes
+