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

Topic Tutorial

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

This Mercurial configuration example is used for testing.

.. Various setup

  $ . "$TESTDIR/testlib/topic_setup.sh"

  $ cat >> $HGRCPATH << EOF

  > [experimental]

  > evolution=all

  > [extensions]

  > evolve=

  > EOF

  $ 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

#if docgraph-ext

  $ . "$TESTDIR/testlib/docgraph_setup.sh" #rest-ignore

#endif

Topic branches are lightweight branches which disappear when changes are

finalized (moved to the public phase). They can help users to organize and share

their unfinished work.

In this tutorial, we explain how to use topics for local development. In the

first part, there is a central *publishing* server. Anything pushed to the

central server will become public and immutable. This means no unfinished work

should escape the local repository.

Topic Basics

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

Let's say 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

#if docgraph-ext

  $ hg docgraph -r "all()" --sphinx-directive --rankdir LR #rest-ignore

  .. graphviz::

      strict digraph "Mercurial graph" {

      	graph [rankdir=LR,

      		splines=polyline

      	];

      	node [label="\N"];

      	0	 [fillcolor="#7F7FFF",

      		fixedsize=true,

      		group=default,

      		height=1,

      		label=0,

      		pin=true,

      		pos="1,0!",

      		shape=circle,

      		style=filled,

      		width=1];

      }

#endif

We are about to make some additions to this list and would like to do them

within a topic. Creating a new topic is done using the ``topic`` command:

  $ hg topics food

  marked working directory as topic: food

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

changeset yet:

  $ hg topics

   * food (0 changesets)

  $ 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

#if docgraph-ext

  $ hg docgraph -r "all()" --sphinx-directive --rankdir LR #rest-ignore

  .. graphviz::

      strict digraph "Mercurial graph" {

      	graph [rankdir=LR,

      		splines=polyline

      	];

      	node [label="\N"];

      	0	 [fillcolor="#7F7FFF",

      		fixedsize=true,

      		group=default,

      		height=1,

      		label=0,

      		pin=true,

      		pos="1,0!",

      		shape=circle,

      		style=filled,

      		width=1];

      }

#endif

Our next commit will be part of the active topic:

  $ cat >> shopping << EOF

  > Egg

  > Suggar

  > Vinegar

  > Oil

  > EOF

  $ hg commit -m "adding condiments"

  active topic 'food' grew its first changeset

  $ 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

#if docgraph-ext

  $ hg docgraph -r "topic("food")" --sphinx-directive --rankdir LR #rest-ignore

  .. graphviz::

      strict digraph "Mercurial graph" {

      	graph [rankdir=LR,

      		splines=polyline

      	];

      	node [label="\N"];

      	1	 [fillcolor="#7F7FFF",

      		fixedsize=true,

      		group=default,

      		height=1,

      		label=1,

      		pin=true,

      		pos="1,1!",

      		shape=pentagon,

      		style=filled,

      		width=1];

      }

#endif

And future commits 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

#if docgraph-ext

  $ hg docgraph -r "topic("food")" --sphinx-directive --rankdir LR #rest-ignore

  .. graphviz::

      strict digraph "Mercurial graph" {

      	graph [rankdir=LR,

      		splines=polyline

      	];

      	node [label="\N"];

      	1	 [fillcolor="#7F7FFF",

      		fixedsize=true,

      		group=default,

      		height=1,

      		label=1,

      		pin=true,

      		pos="1,1!",

      		shape=pentagon,

      		style=filled,

      		width=1];

      	2	 [fillcolor="#7F7FFF",

      		fixedsize=true,

      		group=default,

      		height=1,

      		label=2,

      		pin=true,

      		pos="1,2!",

      		shape=pentagon,

      		style=filled,

      		width=1];

      	1 -> 2	 [arrowhead=none,

      		penwidth=2.0];

      }

#endif

We can get a compact view of the content of our topic using the ``stack``

command:

  $ hg stack

  ### topic: food

  ### target: default (branch)

  t2@ adding fruits (current)

  t1: adding condiments

  t0^ Shopping list (base)

The topic deactivates when we update away from it:

  $ hg update default

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

  $ hg topics

     food (2 changesets)

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

#if docgraph-ext

  $ hg docgraph -r "all()" --sphinx-directive --rankdir LR #rest-ignore

  .. graphviz::

      strict digraph "Mercurial graph" {

      	graph [rankdir=LR,

      		splines=polyline

      	];

      	node [label="\N"];

      	0	 [fillcolor="#7F7FFF",

      		fixedsize=true,

      		group=default,

      		height=1,

      		label=0,

      		pin=true,

      		pos="1,0!",

      		shape=circle,

      		style=filled,

      		width=1];

      	1	 [fillcolor="#7F7FFF",

      		fixedsize=true,

      		group=default,

      		height=1,

      		label=1,

      		pin=true,

      		pos="1,1!",

      		shape=pentagon,

      		style=filled,

      		width=1];

      	0 -> 1	 [arrowhead=none,

      		penwidth=2.0];

      	2	 [fillcolor="#7F7FFF",

      		fixedsize=true,

      		group=default,

      		height=1,

      		label=2,

      		pin=true,

      		pos="1,2!",

      		shape=pentagon,

      		style=filled,

      		width=1];

      	1 -> 2	 [arrowhead=none,

      		penwidth=2.0];

      }

#endif

And updating back to the topic reactivates it:

  $ hg update food

  switching to topic food

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

  $ hg topics

   * food (2 changesets)

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

regardless of how the revision was specified:

  $ hg update default

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

  $ hg update --rev 'desc("condiments")'

  switching to topic food

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

  $ hg topics

   * food (2 changesets)

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

The topic will also affect the rebase and the merge destinations. 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