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

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