comparison mercurial/helptext/internals/dirstate-v2.txt @ 48183:eb8092f9304f

dirstate-v2: Use "byte sequence" in docs

The patch originally sent as https://phab.mercurial-scm.org/D11546
used "byte string" but that was changed during review to avoid suggesting
Unicode or character encodings.

However "byte range" sounds to be like a range of *indices* within a byte
string/sequence elsewhere.

This changes to "byte sequence". Python docs use "sequence" a lot when
discussing the `bytes` type: https://docs.python.org/3/library/stdtypes.html

Differential Revision: https://phab.mercurial-scm.org/D11623

48182:01c3dd208c75

  in inclusion order. This definition is recursive, as included files can
  themselves include more files.

This hash is defined as the SHA-1 of the concatenation (in sorted
order) of the "expanded contents" of each "root" ignore file.
(Note that computing this does not require actually concatenating byte ranges into
contiguous memory.
Instead a SHA-1 hasher object can be created and fed separate byte ranges one by
one.)

The data file format
--------------------

This is implemented in `rust/hg-core/src/dirstate_tree/on_disk.rs`
and `mercurial/dirstateutils/v2.py`.

The data file contains two types of data: paths and nodes.

Paths and nodes can be organized in any order in the file, except that sibling
nodes must be next to each other and sorted by their path. Contiguity lets
the parent refer to them all by their count with a single pseudo-pointer,
instead of storing one pseudo-pointer per child node. Sorting allows using
binary seach to find a child node with a given name in `O(log(n))` byte ranges
comparisons.

The current implemention writes paths and child node before a given node
for ease of figuring out the value of pseudo-pointers by the time the are to be
written, but this is not an obligation and readers must not rely on it.

48183:eb8092f9304f

  in inclusion order. This definition is recursive, as included files can
  themselves include more files.

This hash is defined as the SHA-1 of the concatenation (in sorted
order) of the "expanded contents" of each "root" ignore file.
(Note that computing this does not require actually concatenating
into a single contiguous byte sequence.
Instead a SHA-1 hasher object can be created
and fed separate chunks one by one.)

The data file format
--------------------

This is implemented in `rust/hg-core/src/dirstate_tree/on_disk.rs`
and `mercurial/dirstateutils/v2.py`.

The data file contains two types of data: paths and nodes.

Paths and nodes can be organized in any order in the file, except that sibling
nodes must be next to each other and sorted by their path.
Contiguity lets the parent refer to them all
by their count and a single pseudo-pointer,
instead of storing one pseudo-pointer per child node.
Sorting allows using binary seach to find a child node with a given name
in `O(log(n))` byte sequence comparisons.

The current implemention writes paths and child node before a given node
for ease of figuring out the value of pseudo-pointers by the time the are to be
written, but this is not an obligation and readers must not rely on it.