Mercurial File Formats

This page is a starting point for understanding Mercurial file internals. Text files are marked as "local" if they are in the local charset, otherwise "utf-8" or "ascii". Files intended to be user-editable are marked "editable".

TableOfContents

1. Files in the working directory

1.1. .hgignore (local editable)

This lists ignore patterns. May or may not be managed. See [http://www.selenic.com/mercurial/hgignore.5.html hgignore manpage].

Source: mercurial/ignore.py

1.2. .hgtags (utf-8 editable)

This is a managed file containing tags. Effective tags are determined by combining information from this file on all project heads (not from the working directory).

One line per tag in the format '<full hex changeset id> <tag>'.

Source: mercurial/localrepo.py:readtags()

1.3. .hgsigs (ascii) [gpg]

This file contains changeset signatures from the gpg extension, one per line. Format:

<full hex changeset id> <signature version> <base64-encoded signature>

Source: hgext/gpg.py

1.4. .hg/

This directory in the repository root contains all the revision history and non-versioned configuration data.

2. Files in the repository directory (.hg)

2.1. 00changelog.i

In repositories with the 'store' requirement, this is a placeholder to warn older Mercurial about version mismatch.

2.2. requires (ascii)

If this file exists, it contains one line per feature that a local Mercurial must support to read the repository. See RequiresFile.

2.3. branch (utf-8)

This file contains a single line with the branch name for the branch in the working directory. If it doesn't exist, the branch is \'\' (aka 'default').

Source: mercurial/dirstate.py:_branch

2.4. branch.cache (utf-8)

First line is:

<full hex id of tip> <revision number of tip>

This line is used to determine if the cache is current.

Remaining lines are:

<full hex id of branch tip> <branch name>

2.5. dirstate

This file contains information on the current state of the working directory in binary format. It begins with two 40-byte hashes, for first and second parent, followed by an entry for each file. Each file entry is of the following form:

<1-byte state><4-byte mode><4-byte size><4-byte mtime><4-byte name length><n-byte name>

If the name contains a null character, it is split into two strings, with the second being the copy source for move and copy operations.

Source: mercurial/parsers.py:parse_dirstate()

2.6. hgrc (local editable)

This is the repository-local configuration file. See [".hgrc"] for more info.

2.7. inotify.sock [inotify]

This is a socket created by the inotify extension to communicate with its daemon.

2.8. localtags (local editable)

File containing local tags. Same format as .hgtags.

2.9. patches/ [mq]

This directory contains mq's patch management data

2.10. wlock

The lock file for the working directory state

Source: mercurial/lock.py, mercurial/localrepo.py:wlock()

2.11. journal.*

These files are backups of files before the beginning of a transaction used to restore earlier state on failure:

• journal.dirstate - copy of dirstate
• journal.branch - copy of branch

2.12. undo.*

Files from last transaction to allow rollback

• undo.dirstate - copy of dirstate
• undo.branch - copy of branch

3. Files in the repository store (.hg or .hg/store)

The following files are stored under .hg/store in repos with the store requirement, otherwise in .hg

3.1. lock

The lock file for the repository store

Source: mercurial/lock.py, mercurial/localrepo.py:lock()

3.2. journal

The journal file is a text file containing one entry per line of the form:

<filename> <pre-modified length>

This file allows mercurial to undo changes to revlogs. If this file exists, a transaction is in progress or has been interrupted.

Source: mercurial/transaction.py

3.3. undo

Renamed journal to allow rollback after transaction is complete.

Source: mercurial/localrepo.py:rollback()

3.4. 00changelog.[id]

The project changelog, stored in ["Revlog"] format.

Source: mercurial/changelog.py

3.5. 00manifest.[id]

The project manifest, stored in ["Revlog"] format. Each manifest revision contains a list of the file revisions in each changeset, in the form:

<filename>\0<hex file revision id>[<flags>]\n

Source: mercurial/parsers.c:parse_manifest()

3.6. data/

[:Revlog:Revlogs] for each file in the project history. Names are escaped in various increasingly-complex ways:

• old (see mercurial/filelog.py:encodedir()):
  • directory names ending in .i or .d have .hg appended
• store (see mercurial/store.py:encodedstore):

  • uppercase is escaped: 'FOO' -> '_f_o_o'

  • character codes outside of 32-126 are converted to '~XX' hex format
• fncache (see mercurial/store.py:hybridencode):
  • windows reserved filename prefixes are ~XX-encoded
  • very long filenames and stored by hash