==============

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 organize and share

their unfinished work.

Topic Basics

============

  $ hg log --graph

  @  changeset:   0:38da43f0a2ea

     tag:         tip

     user:        test

     date:        Thu Jan 01 00:00:00 1970 +0000

     summary:     Shopping list

  $ hg topic food

Much like a named branch, our topic is active but it does not contain any

  $ 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

  $ 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

  $ 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``

  $ hg stack

  ### topic: food

  ### branch: default

  t2@ adding fruits (current)

  t1: adding condiments

  t0^ Shopping list (base)

  $ 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

  $ 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

  $ hg up food

  switching to topic food

  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

  $ hg topic

   * food

Updating to any changeset that is part of a topic activates the topic

  $ 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

  $ 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

The topic will also affect the rebase and the merge destinations. Let's pull

  $ 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 merging from the new head of the

  $ 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]

  $ 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

  switching to topic food

  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

  $ 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

   * food

  $ 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, topics do not bring much benefit since you only have one

line of development. Topics start to be more useful when you have to work on

multiple features at the same time.

We might go shopping in a hardware store in the same go, so let's add some

  $ 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 we are not sure we will actually go to the hardware store, so in the

meantime, we want to extend the list with drinks. We go back to the official

  $ 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'

  $ hg topic

   * drinks

     tools

  $ hg stack

  ### topic: drinks

  ### branch: default

  t2@ Adding orange juice (current)

  t1: Adding apple juice

  t0^ adding fruits (base)

  $ 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

  t0^ adding fruits (base)

They are seen as independent branches by Mercurial. No rebase or merge

  $ hg rebase

  nothing to rebase

  [1]

  $ 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

  $ rm foo

  $ hg ci -m 'add a pair of shoes'

  $ cd ../client

  $ 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 are new changes! We can simply use ``hg rebase`` to update our

  $ hg rebase

  rebasing 6:183984ef46d1 "Adding hammer"

  merging shopping

  switching to topic tools

  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

  $ 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 are 2 new changesets on the named

branch of the topic. You need to merge or rebase to incorporate them.