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

UI Guidelines

How to make build a consistent user experience.

/!\ This is a early draft to be filled and reviewed more widely.

1. adding UI element

The general philosophy is that adding is easier than removing. So we tend to start small and add things when it is clear it make senses to make it more widely available. Here are the possible methods to introduce new user interface point. Sorted by increasing "cost":

  1. new config option in the "experimental" section (virtually free, no backward compat needed.)
  2. new config option
  3. new config section
  4. new flag to an existing command
  5. new command

Keep also in mind that we have multiple tier of support

  1. third party extensions (good for experimenting)
  2. extensions bundled with core (that have backward compatibility constraint, but can be deprecated as a whole)
  3. core mercurial

2. commands

2.1. adding new commands

2.2. naming commands

We have two styles of naming currently in fashion

- noun: command can be named after the concept they refer to. eg: hg bookmarks, hg phases hg heads

- verbs: command can also be named after the action they perform, eg: hg rebase, hg graft, hg merge, hg resolve

3. argument

3.1. naming arguments

3.2. common arguments

Here is a list of argument use in multiple commands, avoid to pick colliding short version as it will likely confuse people



used for

-r REV

--rev REV

specifying revisions



forcing as operation



act recursively on subrepositories


--bookmark BOOK

do something with/related to bookmark BOOK



display changesets//output using TEMPLATE


--tool TOOL

merge tool to be used for merging


--include PATTERN

include names matching the given patterns


--exclude PATTERN

exclude names matching the given patterns

Some pattern are specific to command that create/alter changesets



used for

-m MSG


message to be used for the changeset/action



edit the message


--logfile FILE

get message from FILE

Some commands like hg status unfortunately breaks this pattern, this get very confusing for users

4. config

4.1. adding new sections

Try to avoid adding a new section for a single entry. Do add a new section when you are introducing a new concept and already know that multiple option will fit in.

(note: we should get a way to list all config option and section)

4.2. adding new options

4.3. naming config options

Use hyphens between words for every new option.

For boolean option, avoid negative name as they lead to double negative.

5. output

5.1. general output

5.2. error message

abort: uncommitted changes
("use 'hg status' to list changes")

abort: push creates new remote head 02793c56c8d3!
(merge or see "hg help push" for details about pushing new heads)

5.3. color

5.4. progress

6. help text

UIGuideline (last edited 2017-08-11 08:52:28 by DavidDemelier)