Page MenuHomePhabricator

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

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

Details

Reviewers
None
Group Reviewers
hg-reviewers
Summary

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

Repository
rHG Mercurial
Branch
default
Lint
No Linters Available
Unit
No Unit Test Coverage

Event Timeline

indygreg created this revision.Sat, Nov 7, 2:42 PM
joerg.sonnenberger added inline comments.
mercurial/helptext/internals/locks.txt
51

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.

mercurial/helptext/internals/repolayout.txt
5

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

18

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

69

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

mercurial/helptext/internals/store-revlog.txt
43

00manifest.i?

44

using inline storage?

131

Byte value of 0 is not possible?

191

See above.

330

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?

339

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.
mercurial/helptext/internals/repolayout.txt
5

.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.