comparison tests/test-topic-tutorial.t @ 6914:8da51e02b5d3 mercurial-5.6

test-compat: merge mercurial-5.7 into mercurial-5.6

6809:9903ee44e658

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

  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

  $ 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

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
  (see 'hg help topics' for more information)

  $ 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

  > 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
  

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
  |

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

  $ hg update food
  switching to topic food
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

  $ hg rebase
  rebasing 1:13900241408b "adding condiments" (food)
  merging shopping
  switching to topic food
  rebasing 2:287de11b401f "adding fruits" (food)
  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
  |

#endif

There exists a template keyword named "topic" which can be used

  $ hg log -GT "{rev}:{node|short} {topic}\n {desc}"
  @  5:2d50db8b5b4c food
  |   adding fruits
  o  4:4011b46eeb33 food
  |   adding condiments
  o  3:6104862e8b84
  |   Adding clothes
  o  0:38da43f0a2ea
      Shopping list

  ### target: default (branch)
  (stack is empty)
  s0^ adding fruits (base current)

  $ 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

Keep working within topics
==========================

Making sure all your new local commit are made within a topic will help you
organize your work. It is possible to ensure this through the Mercurial
configuration.

For this tutorial, we'll add the config at the repository level:

  $ cat << EOF >> .hg/hgrc
  > [experimental]
  > topic-mode = enforce
  > EOF

You can also use `hg config --edit` to update your mercurial configuration.


Once enforcement is turned on. New local commit will be denied if no topic is active.

  $ echo sickle >> shopping
  $ hg commit -m 'Adding sickle'
  abort: no active topic
  (see 'hg help -e topic.topic-mode' for details)

  $ hg commit -m 'Adding saw'

  $ echo drill >> shopping
  $ hg commit -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
default branch and start a new topic:

  $ hg update default
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

  $ hg rebase
  nothing to rebase
  [1]

We simulate independant contributions to the repo with this
activity:

  $ cd ../server
  $ hg update
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

  $ cat foo >> shopping
  $ rm foo
  $ hg commit -m 'add a pair of shoes'
  $ cd ../client

Let's discover what other people did contribute:

  $ 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)
  new changesets f2d6cacc6115:fbff9bc37a43
  (run 'hg heads' to see heads)

There are new changes! We can simply use ``hg rebase`` to update our
changeset on top of the latest:

  $ hg log -G
  o  changeset:   12:fbff9bc37a43
  |  tag:         tip
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     add a pair of shoes
  |
  o  changeset:   11:f2d6cacc6115
  |  parent:      5:2d50db8b5b4c
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     add a coat
  |
  | o  changeset:   10:70dfa201ed73
  | |  topic:       drinks
  | |  user:        test
  | |  date:        Thu Jan 01 00:00:00 1970 +0000
  | |  summary:     Adding orange juice
  | |
  | o  changeset:   9:8dfa45bd5e0c
  |/   topic:       drinks
  |    parent:      5:2d50db8b5b4c
  |    user:        test
  |    date:        Thu Jan 01 00:00:00 1970 +0000
  |    summary:     Adding apple juice
  |
  | @  changeset:   8:34255b455dac
  | |  topic:       tools
  | |  user:        test
  | |  date:        Thu Jan 01 00:00:00 1970 +0000
  | |  summary:     Adding drill
  | |
  | o  changeset:   7:cffff85af537
  | |  topic:       tools
  | |  user:        test
  | |  date:        Thu Jan 01 00:00:00 1970 +0000
  | |  summary:     Adding saw
  | |
  | o  changeset:   6:183984ef46d1
  |/   topic:       tools
  |    user:        test
  |    date:        Thu Jan 01 00:00:00 1970 +0000
  |    summary:     Adding hammer
  |
  o  changeset:   5:2d50db8b5b4c
  |  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

      		penwidth=2.0];
      }
#endif

  $ hg rebase
  rebasing 6:183984ef46d1 "Adding hammer" (tools)
  merging shopping
  switching to topic tools
  rebasing 7:cffff85af537 "Adding saw" (tools)
  merging shopping
  rebasing 8:34255b455dac "Adding drill" (tools)
  merging shopping

But what about the other topic? You can use 'hg topics --verbose' to see
information about all the topics:

  $ hg topics --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 over the base of the topic.

Pushing that topic would create a new head, and therefore 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 would publish
them to the default branch, and then mercurial would complain about the
multiple *public* heads it would create on that branch:

  $ hg rebase -b drinks
  rebasing 9:8dfa45bd5e0c "Adding apple juice" (drinks)
  merging shopping
  switching to topic drinks
  rebasing 10:70dfa201ed73 "Adding orange juice" (drinks)
  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 as we just saw in the previous case):

  adding manifests
  adding file changes
  added 2 changesets with 2 changes to 1 files
  2 new obsolescence markers

The published topic has now faded out, and the other is now marked as
"behind":

  $ hg topics --verbose
   * tools (on branch: default, 3 changesets, 2 behind)

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

Navigating within your stack
----------------------------

As we saw before `stack` displays changesets on your current topic in a clean way:

  $ hg topics --verbose
   * tools (on branch: default, 3 changesets, 2 behind)

  $ hg stack

  s3@ Adding drill (current)
  s2: Adding saw
  s1: Adding hammer
  s0^ add a pair of shoes (base)

You can navigate in your current stack with `previous` and `next`.

`previous` will bring you back to the parent of the topic head.

  $ hg previous
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
  [s2] Adding saw

  s3: Adding drill
  s2@ Adding saw (current)
  s1: Adding hammer
  s0^ add a pair of shoes (base)

`next` will move you forward to the topic head.

  $ hg next
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
  [s3] Adding drill

  s3@ Adding drill (current)
  s2: Adding saw
  s1: Adding hammer
  s0^ add a pair of shoes (base)

You can also directly jump to a changeset within your stack with the revset `t#`.

  $ hg update s1
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

  $ hg stack

Understanding the current situation with hg log is not so easy, because
it shows too many things:

  $ hg log -G -r "s0::"
  @  changeset:   18:b7509bd417f8
  |  tag:         tip
  |  topic:       tools
  |  parent:      12:fbff9bc37a43
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     Adding hammer to the shopping list
  |
  | o  changeset:   17:4cd7c1591a67
  | |  user:        test
  | |  date:        Thu Jan 01 00:00:00 1970 +0000
  | |  summary:     Adding orange juice
  | |
  | o  changeset:   16:20759cb47ff8
  |/   parent:      12:fbff9bc37a43
  |    user:        test
  |    date:        Thu Jan 01 00:00:00 1970 +0000
  |    summary:     Adding apple juice
  |
  | *  changeset:   15:bb1e6254f532
  | |  topic:       tools
  | |  user:        test
  | |  date:        Thu Jan 01 00:00:00 1970 +0000
  | |  instability: orphan
  | |  summary:     Adding drill
  | |
  | *  changeset:   14:d4f97f32f8a1
  | |  topic:       tools
  | |  user:        test
  | |  date:        Thu Jan 01 00:00:00 1970 +0000
  | |  instability: orphan
  | |  summary:     Adding saw
  | |
  | x  changeset:   13:a8ab3599d53d
  |/   topic:       tools
  |    user:        test
  |    date:        Thu Jan 01 00:00:00 1970 +0000
  |    obsolete:    reworded using amend as 18:b7509bd417f8
  |    summary:     Adding hammer
  |
  o  changeset:   12:fbff9bc37a43
  |  user:        test
  ~  date:        Thu Jan 01 00:00:00 1970 +0000
     summary:     add a pair of shoes
  

  s3$ Adding drill (orphan)
  s2$ Adding saw (orphan)
  s1@ Adding hammer to the shopping list (current)
  s0^ add a pair of shoes (base)

It's easy to stabilize the situation, `next` has an `--evolve` option.  It will
do the necessary relocation of `s2` and `s3` over the new `s1` without having
to do that rebase by hand.:

  $ hg next --evolve
  move:[s2] Adding saw
  atop:[s1] Adding hammer to the shopping list
  working directory is now at d5c51ee5762a

  $ hg stack
  ### topic: tools
  ### target: default (branch), 2 behind
  s3$ Adding drill (orphan)

One more to go:

  $ hg next --evolve
  move:[s3] Adding drill
  atop:[s2] Adding saw
  working directory is now at bae3758e46bf

  $ hg stack
  ### topic: tools
  ### target: default (branch), 2 behind
  s3@ Adding drill (current)
  s2: Adding saw
  s1: Adding hammer to the shopping list
  s0^ add a pair of shoes (base)

Let's take a look at `hg log` once again:

  $ hg log -G -r "s0::"
  @  changeset:   20:bae3758e46bf
  |  tag:         tip
  |  topic:       tools
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     Adding drill
  |
  o  changeset:   19:d5c51ee5762a
  |  topic:       tools
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     Adding saw
  |
  o  changeset:   18:b7509bd417f8
  |  topic:       tools
  |  parent:      12:fbff9bc37a43
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     Adding hammer to the shopping list
  |
  | o  changeset:   17:4cd7c1591a67
  | |  user:        test
  | |  date:        Thu Jan 01 00:00:00 1970 +0000
  | |  summary:     Adding orange juice
  | |
  | o  changeset:   16:20759cb47ff8
  |/   parent:      12:fbff9bc37a43
  |    user:        test
  |    date:        Thu Jan 01 00:00:00 1970 +0000
  |    summary:     Adding apple juice
  |
  o  changeset:   12:fbff9bc37a43
  |  user:        test
  ~  date:        Thu Jan 01 00:00:00 1970 +0000
     summary:     add a pair of shoes
  

Merge within a multi-headed stack will use the other topic head as
destination if the topic has two heads. But rebasing will yield a
completely linear history so it's what we will do.

  $ hg log -G
  @  changeset:   21:f936c6da9d61
  |  tag:         tip
  |  topic:       tools
  |  parent:      18:b7509bd417f8
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     Adding nails
  |
  | o  changeset:   20:bae3758e46bf
  | |  topic:       tools
  | |  user:        test
  | |  date:        Thu Jan 01 00:00:00 1970 +0000
  | |  summary:     Adding drill
  | |
  | o  changeset:   19:d5c51ee5762a
  |/   topic:       tools
  |    user:        test
  |    date:        Thu Jan 01 00:00:00 1970 +0000
  |    summary:     Adding saw
  |
  o  changeset:   18:b7509bd417f8
  |  topic:       tools
  |  parent:      12:fbff9bc37a43
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     Adding hammer to the shopping list
  |
  | o  changeset:   17:4cd7c1591a67
  | |  user:        test
  | |  date:        Thu Jan 01 00:00:00 1970 +0000
  | |  summary:     Adding orange juice
  | |
  | o  changeset:   16:20759cb47ff8
  |/   parent:      12:fbff9bc37a43
  |    user:        test
  |    date:        Thu Jan 01 00:00:00 1970 +0000
  |    summary:     Adding apple juice
  |
  o  changeset:   12:fbff9bc37a43
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     add a pair of shoes
  |
  o  changeset:   11:f2d6cacc6115
  |  parent:      5:2d50db8b5b4c
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     add a coat
  |
  o  changeset:   5:2d50db8b5b4c
  |  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

  $ hg up s4
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

  $ hg rebase
  rebasing 19:d5c51ee5762a "Adding saw" (tools)
  merging shopping
  rebasing 20:bae3758e46bf "Adding drill" (tools)
  merging shopping

  $ hg stack
  ### topic: tools
  ### target: default (branch), 2 behind

  adding file changes
  added 4 changesets with 4 changes to 1 files (+1 heads)
  8 new obsolescence markers

Pushing the new topic branch to a non-publishing server did not require
--force. As long as new heads are on their own topic, Mercurial will not
complain about them.

From another client, we will get them with their topic:

  $ cd ../other-client

  adding changesets
  adding manifests
  adding file changes
  added 4 changesets with 4 changes to 1 files (+1 heads)
  8 new obsolescence markers
  new changesets b7509bd417f8:2d084ac00115 (4 drafts)
  (run 'hg heads' to see heads)

  $ hg topics --verbose
     tools (on branch: default, 4 changesets, 2 behind)

  searching for changes
  adding changesets
  adding manifests
  adding file changes
  added 1 changesets with 1 changes to 1 files
  new changesets 0d409663a1fd (1 drafts)
  (run 'hg update' to get a working copy)

  $ hg update
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

6914:8da51e02b5d3

This Mercurial configuration example is used for testing.

.. Various setup

  $ . "$TESTDIR/testlib/common.sh" #rest-ignore
  $ cat >> $HGRCPATH << EOF
  > [extensions]
  > evolve =
  > rebase =
  > topic =
  > EOF

  $ hg init server

  $ cd server

  $ cat >> .hg/hgrc << EOF
  > [ui]
  > user = Shopping Master
  > EOF

  $ cat >> shopping << EOF
  > Spam
  > Whizzo butter

  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

  $ hg topics food
  marked working directory as topic: food

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

  $ hg topics
   * food (0 changesets)

  $ hg summary

Our next commit will be part of the active topic:

  $ cat >> shopping << EOF
  > Egg
  > Sugar
  > Vinegar
  > Oil
  > EOF

  $ hg commit -m "adding condiments"
  active topic 'food' grew its first changeset
  (see 'hg help topics' for more information)

  $ hg log --graph --rev 'topic("food")'
  @  changeset:   1:9e90e00c084b
  |  tag:         tip
  ~  topic:       food
     user:        test
     date:        Thu Jan 01 00:00:00 1970 +0000
     summary:     adding condiments

  > EOF

  $ hg commit -m "adding fruits"

  $ hg log --graph --rev 'topic("food")'
  @  changeset:   2:a25aaa6b9385
  |  tag:         tip
  |  topic:       food
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     adding fruits
  |
  o  changeset:   1:9e90e00c084b
  |  topic:       food
  ~  user:        test
     date:        Thu Jan 01 00:00:00 1970 +0000
     summary:     adding condiments
  

Note that ``default`` (name of the branch) now refers to the tipmost
changeset of default without a topic:

  $ hg log --graph
  o  changeset:   2:a25aaa6b9385
  |  tag:         tip
  |  topic:       food
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     adding fruits
  |
  o  changeset:   1:9e90e00c084b
  |  topic:       food
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     adding condiments
  |

  |  parent:      0:38da43f0a2ea
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     Adding clothes
  |
  | o  changeset:   2:a25aaa6b9385
  | |  topic:       food
  | |  user:        test
  | |  date:        Thu Jan 01 00:00:00 1970 +0000
  | |  summary:     adding fruits
  | |
  | @  changeset:   1:9e90e00c084b
  |/   topic:       food
  |    user:        test
  |    date:        Thu Jan 01 00:00:00 1970 +0000
  |    summary:     adding condiments
  |

  $ hg update food
  switching to topic food
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

  $ hg rebase
  rebasing 1:9e90e00c084b "adding condiments" (food)
  merging shopping
  switching to topic food
  rebasing 2:a25aaa6b9385 "adding fruits" (food)
  merging shopping

  $ hg log --graph
  @  changeset:   5:fec062fcfcfa
  |  tag:         tip
  |  topic:       food
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     adding fruits
  |
  o  changeset:   4:d3a1ea2a0337
  |  topic:       food
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     adding condiments
  |

#endif

There exists a template keyword named "topic" which can be used

  $ hg log -GT "{rev}:{node|short} {topic}\n {desc}"
  @  5:fec062fcfcfa food
  |   adding fruits
  o  4:d3a1ea2a0337 food
  |   adding condiments
  o  3:6104862e8b84
  |   Adding clothes
  o  0:38da43f0a2ea
      Shopping list

  ### target: default (branch)
  (stack is empty)
  s0^ adding fruits (base current)

  $ hg log --graph
  @  changeset:   5:fec062fcfcfa
  |  tag:         tip
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     adding fruits
  |
  o  changeset:   4:d3a1ea2a0337
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     adding condiments
  |
  o  changeset:   3:6104862e8b84

Keep working within topics
==========================

Making sure all your new local commits are made within a topic will help you
organize your work. It is possible to ensure this through the Mercurial
configuration.

For this tutorial, we'll add the config at the repository level:

  $ cat << EOF >> .hg/hgrc
  > [experimental]
  > topic-mode = enforce
  > EOF

You can also use `hg config --edit` to update your Mercurial configuration.


Once enforcement is turned on, new local commits will be denied if no topic is active.

  $ echo sickle >> shopping
  $ hg commit -m 'Adding sickle'
  abort: no active topic
  (see 'hg help -e topic.topic-mode' for details)

  $ hg commit -m 'Adding saw'

  $ echo drill >> shopping
  $ hg commit -m 'Adding drill'

But we are not sure if 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
default branch and start a new topic:

  $ hg update default
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

  $ hg rebase
  nothing to rebase
  [1]

We simulate independent contributions to the repo with this
activity:

  $ cd ../server
  $ hg update
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

  $ cat foo >> shopping
  $ rm foo
  $ hg commit -m 'add a pair of shoes'
  $ cd ../client

Let's discover what other people have contributed:

  $ 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)
  new changesets bbfb218049cd:033bfcc0ecb0
  (run 'hg heads' to see heads)

There are new changes! We can simply use ``hg rebase`` to update our
changeset on top of the latest:

  $ hg log -G
  o  changeset:   12:033bfcc0ecb0
  |  tag:         tip
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     add a pair of shoes
  |
  o  changeset:   11:bbfb218049cd
  |  parent:      5:fec062fcfcfa
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     add a coat
  |
  | o  changeset:   10:0b8a99ba9213
  | |  topic:       drinks
  | |  user:        test
  | |  date:        Thu Jan 01 00:00:00 1970 +0000
  | |  summary:     Adding orange juice
  | |
  | o  changeset:   9:213e97c6cd8a
  |/   topic:       drinks
  |    parent:      5:fec062fcfcfa
  |    user:        test
  |    date:        Thu Jan 01 00:00:00 1970 +0000
  |    summary:     Adding apple juice
  |
  | @  changeset:   8:9ef4e4f40a79
  | |  topic:       tools
  | |  user:        test
  | |  date:        Thu Jan 01 00:00:00 1970 +0000
  | |  summary:     Adding drill
  | |
  | o  changeset:   7:c1d9846a234f
  | |  topic:       tools
  | |  user:        test
  | |  date:        Thu Jan 01 00:00:00 1970 +0000
  | |  summary:     Adding saw
  | |
  | o  changeset:   6:6d6f38ff45f0
  |/   topic:       tools
  |    user:        test
  |    date:        Thu Jan 01 00:00:00 1970 +0000
  |    summary:     Adding hammer
  |
  o  changeset:   5:fec062fcfcfa
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     adding fruits
  |
  o  changeset:   4:d3a1ea2a0337
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     adding condiments
  |
  o  changeset:   3:6104862e8b84

      		penwidth=2.0];
      }
#endif

  $ hg rebase
  rebasing 6:6d6f38ff45f0 "Adding hammer" (tools)
  merging shopping
  switching to topic tools
  rebasing 7:c1d9846a234f "Adding saw" (tools)
  merging shopping
  rebasing 8:9ef4e4f40a79 "Adding drill" (tools)
  merging shopping

But what about the other topic? You can use ``hg topics --verbose`` to see
information about all the topics:

  $ hg topics --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 top of the base of the topic.

Pushing that topic would create a new head, and therefore will be prevented:

  $ hg push --rev drinks
  pushing to $TESTTMP/server (glob)
  searching for changes
  abort: push creates new remote head 0b8a99ba9213!
  (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 would publish
them to the default branch, and then Mercurial would complain about the
multiple *public* heads it would create on that branch:

  $ hg rebase -b drinks
  rebasing 9:213e97c6cd8a "Adding apple juice" (drinks)
  merging shopping
  switching to topic drinks
  rebasing 10:0b8a99ba9213 "Adding orange juice" (drinks)
  merging shopping
  switching to topic tools

  $ hg push
  pushing to $TESTTMP/server (glob)
  searching for changes
  abort: push creates new remote head 56656c6d1153!
  (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 as we just saw in the previous case):

  adding manifests
  adding file changes
  added 2 changesets with 2 changes to 1 files
  2 new obsolescence markers

The published topic has now faded out, and the other is now marked as being
"behind":

  $ hg topics --verbose
   * tools (on branch: default, 3 changesets, 2 behind)

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

Navigating within your stack
----------------------------

As we saw before ``stack`` displays changesets on your current topic in a clean way:

  $ hg topics --verbose
   * tools (on branch: default, 3 changesets, 2 behind)

  $ hg stack

  s3@ Adding drill (current)
  s2: Adding saw
  s1: Adding hammer
  s0^ add a pair of shoes (base)

You can navigate in your current stack with ``previous`` and ``next``.

``previous`` will bring you back to the parent of the topic head.

  $ hg previous
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
  [s2] Adding saw

  s3: Adding drill
  s2@ Adding saw (current)
  s1: Adding hammer
  s0^ add a pair of shoes (base)

``next`` will move you forward to the topic head.

  $ hg next
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
  [s3] Adding drill

  s3@ Adding drill (current)
  s2: Adding saw
  s1: Adding hammer
  s0^ add a pair of shoes (base)

You can also directly jump to a changeset within your stack with the revset ``s<number>``.

  $ hg update s1
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

  $ hg stack

Understanding the current situation with hg log is not so easy, because
it shows too many things:

  $ hg log -G -r "s0::"
  @  changeset:   18:2c1a47a5c075
  |  tag:         tip
  |  topic:       tools
  |  parent:      12:033bfcc0ecb0
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     Adding hammer to the shopping list
  |
  | o  changeset:   17:9dc8cec494f3
  | |  user:        test
  | |  date:        Thu Jan 01 00:00:00 1970 +0000
  | |  summary:     Adding orange juice
  | |
  | o  changeset:   16:9dfd6068e8e7
  |/   parent:      12:033bfcc0ecb0
  |    user:        test
  |    date:        Thu Jan 01 00:00:00 1970 +0000
  |    summary:     Adding apple juice
  |
  | *  changeset:   15:56656c6d1153
  | |  topic:       tools
  | |  user:        test
  | |  date:        Thu Jan 01 00:00:00 1970 +0000
  | |  instability: orphan
  | |  summary:     Adding drill
  | |
  | *  changeset:   14:a0ec1a6dcdce
  | |  topic:       tools
  | |  user:        test
  | |  date:        Thu Jan 01 00:00:00 1970 +0000
  | |  instability: orphan
  | |  summary:     Adding saw
  | |
  | x  changeset:   13:dcb888ba1623
  |/   topic:       tools
  |    user:        test
  |    date:        Thu Jan 01 00:00:00 1970 +0000
  |    obsolete:    reworded using amend as 18:2c1a47a5c075
  |    summary:     Adding hammer
  |
  o  changeset:   12:033bfcc0ecb0
  |  user:        test
  ~  date:        Thu Jan 01 00:00:00 1970 +0000
     summary:     add a pair of shoes
  

  s3$ Adding drill (orphan)
  s2$ Adding saw (orphan)
  s1@ Adding hammer to the shopping list (current)
  s0^ add a pair of shoes (base)

It's easy to stabilize the situation, ``next`` has an ``--evolve`` option
(turned on by default nowadays). It will do the necessary relocation of `s2`
and `s3` over the new `s1` without having to do that rebase by hand:

  $ hg next --evolve
  move:[s2] Adding saw
  atop:[s1] Adding hammer to the shopping list
  working directory is now at 7537e3a3cbca

  $ hg stack
  ### topic: tools
  ### target: default (branch), 2 behind
  s3$ Adding drill (orphan)

One more to go:

  $ hg next --evolve
  move:[s3] Adding drill
  atop:[s2] Adding saw
  working directory is now at 9d65331e0dc1

  $ hg stack
  ### topic: tools
  ### target: default (branch), 2 behind
  s3@ Adding drill (current)
  s2: Adding saw
  s1: Adding hammer to the shopping list
  s0^ add a pair of shoes (base)

Let's take a look at ``hg log`` once again:

  $ hg log -G -r "s0::"
  @  changeset:   20:9d65331e0dc1
  |  tag:         tip
  |  topic:       tools
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     Adding drill
  |
  o  changeset:   19:7537e3a3cbca
  |  topic:       tools
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     Adding saw
  |
  o  changeset:   18:2c1a47a5c075
  |  topic:       tools
  |  parent:      12:033bfcc0ecb0
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     Adding hammer to the shopping list
  |
  | o  changeset:   17:9dc8cec494f3
  | |  user:        test
  | |  date:        Thu Jan 01 00:00:00 1970 +0000
  | |  summary:     Adding orange juice
  | |
  | o  changeset:   16:9dfd6068e8e7
  |/   parent:      12:033bfcc0ecb0
  |    user:        test
  |    date:        Thu Jan 01 00:00:00 1970 +0000
  |    summary:     Adding apple juice
  |
  o  changeset:   12:033bfcc0ecb0
  |  user:        test
  ~  date:        Thu Jan 01 00:00:00 1970 +0000
     summary:     add a pair of shoes
  

Merge within a multi-headed stack will use the other topic head as
destination if the topic has two heads. But rebasing will yield a
completely linear history so it's what we will do.

  $ hg log -G
  @  changeset:   21:69ad92f8ff49
  |  tag:         tip
  |  topic:       tools
  |  parent:      18:2c1a47a5c075
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     Adding nails
  |
  | o  changeset:   20:9d65331e0dc1
  | |  topic:       tools
  | |  user:        test
  | |  date:        Thu Jan 01 00:00:00 1970 +0000
  | |  summary:     Adding drill
  | |
  | o  changeset:   19:7537e3a3cbca
  |/   topic:       tools
  |    user:        test
  |    date:        Thu Jan 01 00:00:00 1970 +0000
  |    summary:     Adding saw
  |
  o  changeset:   18:2c1a47a5c075
  |  topic:       tools
  |  parent:      12:033bfcc0ecb0
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     Adding hammer to the shopping list
  |
  | o  changeset:   17:9dc8cec494f3
  | |  user:        test
  | |  date:        Thu Jan 01 00:00:00 1970 +0000
  | |  summary:     Adding orange juice
  | |
  | o  changeset:   16:9dfd6068e8e7
  |/   parent:      12:033bfcc0ecb0
  |    user:        test
  |    date:        Thu Jan 01 00:00:00 1970 +0000
  |    summary:     Adding apple juice
  |
  o  changeset:   12:033bfcc0ecb0
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     add a pair of shoes
  |
  o  changeset:   11:bbfb218049cd
  |  parent:      5:fec062fcfcfa
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     add a coat
  |
  o  changeset:   5:fec062fcfcfa
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     adding fruits
  |
  o  changeset:   4:d3a1ea2a0337
  |  user:        test
  |  date:        Thu Jan 01 00:00:00 1970 +0000
  |  summary:     adding condiments
  |
  o  changeset:   3:6104862e8b84

  $ hg up s4
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

  $ hg rebase
  rebasing 19:7537e3a3cbca "Adding saw" (tools)
  merging shopping
  rebasing 20:9d65331e0dc1 "Adding drill" (tools)
  merging shopping

  $ hg stack
  ### topic: tools
  ### target: default (branch), 2 behind

  adding file changes
  added 4 changesets with 4 changes to 1 files (+1 heads)
  8 new obsolescence markers

Pushing the new topic branch to a non-publishing server did not require
``--force``. As long as new heads are on their own topic, Mercurial will not
complain about them.

From another client, we will get them with their topic:

  $ cd ../other-client

  adding changesets
  adding manifests
  adding file changes
  added 4 changesets with 4 changes to 1 files (+1 heads)
  8 new obsolescence markers
  new changesets 2c1a47a5c075:bbb9e269a01a (4 drafts)
  (run 'hg heads' to see heads)

  $ hg topics --verbose
     tools (on branch: default, 4 changesets, 2 behind)

  searching for changes
  adding changesets
  adding manifests
  adding file changes
  added 1 changesets with 1 changes to 1 files
  new changesets 71d37f5c73ed (1 drafts)
  (run 'hg update' to get a working copy)

  $ hg update
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved