diff -r 765b2561fa90 -r fd24f1c7accd tests/test-topic-tutorial.t --- a/tests/test-topic-tutorial.t Thu May 18 23:35:16 2017 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,468 +0,0 @@ -============== -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 (glob) - 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 (glob) - 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 (glob) - 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 (glob) - 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 (glob) - 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 (glob) - 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 -