==============
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