Mercurial > evolve
changeset 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.
| author | Pierre-Yves David <pierre-yves.david@ens-lyon.org> |
|---|---|
| date | Thu, 29 Sep 2016 16:48:13 +0200 |
| parents | dc34d5317001 |
| children | cd6d32a0155c |
| files | tests/test-topic-tutorial.t |
| diffstat | 1 files changed, 311 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /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