This is an archive of the discontinued Mercurial Phabricator instance.

internals: start to document how .hg/ works
Needs RevisionPublic

Authored by indygreg on Nov 7 2020, 2:42 PM.


Group Reviewers

This commit adds internals documentation that starts to document the
files and semantics of the .hg/ directory.

A lot of this functionality is currently only documented via code
(that doesn't count as documentation!). And the semantics are often wonky
enough that it warrants documentation.

I set out attempting to document the file layout for .hg/. Along the
way, I realized I also needed to document the semantics of lock files,
the path encoding of the revlog store, and how transactions work.

The documentation is missing critical information, such as a thorough
accounting of all the random files in .hg/ and .hg/store and their
formats. But perfect is the enemy of good. And some documentation
seems strictly better than no documentation.

The transaction documentation could definitely be better. However, the
transaction code and transaction semantics are a hot mess and it is
incredibly difficult to read and reason about. I think the only reasonable
way we document and validate the documentation of transactions is by
refactoring the code to actually be readable and document what we learn
along the way.

I started writing these docs several months ago, before the shared hgrc
work started. So the documentation is missing details about this feature
as well. But that's an experimental feature. Hopefully we can add details
of this feature to these docs before that feature stabilizes.

Diff Detail

rHG Mercurial
No Linters Available
No Unit Test Coverage

Event Timeline

indygreg created this revision.Nov 7 2020, 2:42 PM
joerg.sonnenberger added inline comments.

We try to read the content of the symlink? Not sure if documenting the reason for a symlink (atomic creation including content) makes sense here.


.hg/hgrc is an exception here. Any others?


Maybe "unknown properties of the repository encoding" instead of UB?


Mention cache and wcache as placeholders at least? Any other important items?




using inline storage?


Byte value of 0 is not possible?


See above.


As discussed earlier on IRC, I think the "cache" file property is currently hard-wired to 0 with no interface to set it to 1?


The inline -> external storage for revlog files should be documented as a special case here. I'm not even sure if the current logic is fully correct for that...

mharbison72 added inline comments.

.hg/hgrc is an exception here. Any others?

I can't think of any writable examples, but the strip backups are maybe a read-only exception.

(That patch is a bit daunting to review, maybe having each section in their own patch would help to process them in smaller piece)

baymax requested changes to this revision.May 25 2021, 5:32 AM

There seems to have been no activities on this Diff for the past 3 Months.

By policy, we are automatically moving it out of the need-review state.

Please, move it back to need-review without hesitation if this diff should still be discussed.


This revision now requires changes to proceed.May 25 2021, 5:32 AM