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

Topic Plan

A (speculative) plan for topic branching that would work more seamlessly with common Mercurial workflows. Still very early prototype stage. Everything is subject to change.

1. Problem Statement

The Mercurial community has been struggling for years to define a nice way to handle 'topic' branches (sometimes also called 'feature' branches), especially when it comes to sharing them with other people (mainly for code review or other collaboration.)

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 bits of git's refs to Mercurial has been controversial, and may represent enough of a behavior change that it's infeasible.

Named branches are visible forever in the revision history, which makes them unsuitable for feature branch work as the feature branch names rapidly pollute the output of things like hg branches.

2. Current Target

This describe the target semantic and behavior for topics.

2.1. General semantics

TL;DR; topic are an extra "light-branch" data relevant to draft changesets.

2.2. General effect on named branch

Changeset with topic are only aspiring to be part of the named branch, but not fully in that branch yet. when you have branch foo name foo is resolved to the heads of foo with no topic.

Three is a couple of examples:

Multiple heads are not longer ambiguous,


Partial data does not have radical change on the definition,


Usual traversal rules apply:

2.3. Behavior for update

This implies change in hg update behavior (but are not super relevant)

2.4. Behavior for merge

This assume hg rebase and hg merge to be identical

2.5. Behavior for push to publishing (default repo)

2.6. Behavior for push to non-publisehd repo

2.7. Stacked diffs workflow

2.8. User Transition

3. Pro and Cons

4. Other questions

5. Open ideas

This is a list of idea that emerged while brainstorming. This served as base for the current things.

6. Current Implementation

Assign topics to non-public changesets. A topic is like a named branch, in that it is a label stored in a changeset's extra, but that topics just disappear when the change moves to public phase (the data still exists, it's just not shown.)

Code is available at http://hg.durin42.com/hg-topic-experiment/.

6.0.1. Non-Goals

6.1. Open Questions

7. See also


CategoryDeveloper and CategoryNewFeatures