/!\ This page is primarily intended for Mercurial's developers.

A plan for light weight branching/categorization what would work with other Mercurial principle and actual DVCS idea.

Still a very early prototype stage.


Mercurial have been struggling for year to define a nice way to handle 'topic' branch (also called 'feature' branch) especially when it come to exchange them with other people (eg: for pull request).

1. Constraint

The main challenges to get such feature right are:

- Life cycle:

- Distributed system:

- Tracking/Target:

- Clearly defined set of changes:

- Anonymous branching:

- name conflict handling:

2. Current shortcomings of bookmarks

This section (and page) is not meant as "bookmarks are doomed, lets do something else." The idea here is "we have long standing issues with bookmark, lets think again from scratch a see what emerge." We'll see what to do with the other idea later. It's entirely possible that bookmarks can grow bits of new functionality and become topics.

There is currently an experimentation around the idea of "remote bookmarks" and wider work flow changes, it will be "evaluated" independently. (its a wiki Feel free to update content of this section)




Life cycle








defined set



partial exch









Life cycle of bookmark are problematic because we still have not figured out a good way to handle deletion and renaming. So once they are in the wild, it is very hard to get rid of a feature related bookmark. [augie and marmoute are not sure if remote-bookmarks improve that.]

Behavior in distributed is okay-ish for the in-core bookmark. The current behavior on pull work in a distributed ways as it will exchange any bookmark alongside their changeset. However behavior on push is more problematic as local bookmark may not be pushed, and Mercurial may warn about it or not depending unrelated condition. The 'remote-boomarks' change is more problematic in this aspect as remote name are not propagated so changesets can get exchanged without there topic information.

tracking is not covered at all by current core version. It is introduced with 'remote-bookmark' but only cover rebase, the UI to setup and observe tracking is unclear to [marmoute] yet.

A bookmark can implicitly define a set of revisions since everything 'only' under that bookmark it can be considered in the topic. This has issues:

Because they refer to a single changeset at the top of the stack, bookmark are bad at partial exchange. It is often practical to push or to pull only a part of the topic because the rest is not ready yet. Because the bookmark have no "start" the changesets are pulled anonymously in this case.

For the same reason (refer to a single things) bookmark are does not allow for experimental branch and small popping heads in the same topics.

Beside the current state of their implementation, divergent bookmarks provide a solution for conflict. however it does not handle recessing a bookmark or deletion/recreation cycle, but this is more related to live cycle.

Open idea

This is a list of idea that emerged while brain storming.

  • Topic could be a property attached to each changesets (grouping them by similar topic)
  • Topic could fade away when changesets become public (either archived or plain dropped)
    • A benefit of archiving them is that users can query for topics, eg you could say hg log -r topic(issue123) which would help

  • Tracking could be achieved through the naming scheme. eg:
    • 'default//feature-foo' would be a topic 'feature-foo' tracking the 'default' branch.
    • 'stable//issue4700' would be a topic 'issue4700' tracking branch stable.
    • '@//feature-bar' would be a topic 'feature-bar' tracking bookmark '@' ?
    • 'stable//issue4689//issue4700' would be a topic 'issue4700' tracking the topic 'stable//issue4689'. When topic 'issue4686' face away (because published), the tracking fallback to 'stable'.
  • Topic could be non contiguous (mpm idea) feature-foo -> fix-bar -> feature-foo. Allowing a stream lined work that is automatically split apart after that.

  • Topic could be hierarchical 'issue4700.test' 'issue4700.preparation', activation//reference could be done at any level 'issue4700' or 'issue4700' (this could help handle branching/different approach)
  • pushing a new head on a new topic to a non-publishing server would be allowed.

    • that is, it'd be legal to have one head per topic on a non-publishing server.
  • A changeset could maybe have multiple topic.
    • Augie doesn't feel great about this option just because of UI complexity.
  • Users can name patches (in a sense) without mq
    • One of the major complaints about evolve from veteran mq users is that their patches no longer have explicit names. Topics provide a potential way to name patches again.

principle of very primitive extension

Assign topics to non-public changesets. A topic is like a named branch, in that it is a label on a changeset (the initial prototype even stores the topic in the extra area in the changeset), but that topics just disappear when the change moves to public phase.

Problem solved

1. What Topic solves

Bookmarks are a clone of git's refs, which seems to work more poorly in Mercurial than they do in Git, in part because the synchronization parts of bookmarks aren't really done. Adding the remaining functionality to bookmarks has been challenging, and seems to be adding a lot of conceptual complexity around configuration of the synchronization mechanism that AugieFackler finds frustrating. (<- This should be dispatched in the section related to bookmark).

The current implementation also makes it possible to say "what patches did I do while working on topic issue1234", which might be nice.

2. What Topic may solve

(Use case that exists but it is not clear if Topic should try to solve them)

3. What Topic do not solve

  • Topic seems orthogonal to tracking content of remote repository.
  • Topic is not fitted for long term branch, we have named branch for that (and bookmark?)

(Use case we know belong to other feature)

Open Question

  • Right now we use changeset extra for storing the topic. That might lead to bonus divergence problems.
  • Should changesets be allowed multiple topics?
  • How permissive should we be on topic names?

CategoryDeveloper and CategoryNewFeatures