This page is primarily intended for developers of Mercurial.

Coding Style

How to make your code pretty the Mercurial way.

1. Introduction

This page is intended to save new developers a few round-trips when contributing changes. It doesn't cover everything, but it does cover some of the most common mistakes people make.

2. Some code doesn't agree with the coding style!

Yes, because some code predates the coding style and has not yet been rewritten to conform. Please follow the coding style for all new code.

3. Naming conventions

The new (since the end of 2019) naming conventions mostly follow PEP8 for new code. For private methods and helper functions, the convention is to use a single leading underbar. Use a trailing underbar to avoid shadowing built-ins and imported modules.

Throughout the code, the following variables usually refer to the same thing:



p1, p2

first and second parents


a context.changectx instance (or derivative)


a context.filectx instance

fn, fname



a python file(like) object


a localrepo or review object


an unfiltered local repo instance

4. Whitespace and syntax

We use black for most style formatting. Use it! An example configuration for the fix extension which automates cleaning up style issues after commit.

5. Language features and compatibility

6. Classes

7. Unicode and character encoding

Character encoding is a complex topic (see Encoding Strategy for an overview) but Mercurial generally follows these rules:

8. Status and error messages

Short messages should look like this:

adding foo.txt

Note the following:

Some existing strings don't follow this style and are kept like that for backwards compatibility reasons. But please write all new strings in this style.

The above message should look like this in your code:

ui.status(_('adding %s\n') % filename)

Please note:

9. User options

10. Miscellaneous

11. Automated checking

A lot of the rules in this document and a bunch of others can be automatically checked with our 'check-code' script:

$ python contrib/ --blame `hg manifest`
mercurial/ (working directory):
 >     u = u'\n\n'.join([p and t.ugettext(unicode(p, 'ascii')) or '' for p in paragraphs])
 line too long

We recommend you run this script before every submission. In addition to catching style and portability issues in Python code, it will also inspect our C code and test suite.

12. See also


CodingStyle (last edited 2022-02-21 17:44:01 by RaphaelGomes)