--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/tests/test-topic-tutorial.t Tue Mar 14 14:47:20 2017 -0700
@@ -0,0 +1,468 @@
+==============
+Topic Tutorial
+==============
+
+.. This test file is also supposed to be able to compile as a rest file.
+
+
+.. Some Setup::
+
+ $ . "$TESTDIR/testlib/topic_setup.sh"
+ $ 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
+
+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
+