| hg-reviewers |
In preparation for formalizing revlog version 2.
| Automatic diff as part of commit; lint not applicable. |
| Automatic diff as part of commit; unit tests not applicable. |
| Revision logs - or *revlogs* - are an append only data structure for | Revision logs - or *revlogs* - are an append only data structure for | ||||
| storing discrete entries, or *revisions*. They are the primary storage | storing discrete entries, or *revisions*. They are the primary storage | ||||
| mechanism of repository data. | mechanism of repository data. | ||||
| Revlogs effectively model a directed acyclic graph (DAG). Each node | Revlogs effectively model a directed acyclic graph (DAG). Each node | ||||
| has edges to 1 or 2 *parent* nodes. Each node contains metadata and | has edges to 1 or 2 *parent* nodes. Each node contains metadata and | ||||
| the raw value for that node. | the raw value for that node. | ||||
| Revlogs consist of entries which have metadata and revision data. | Revlogs consist of entries which have metadata and revision data. | ||||
| Metadata includes the hash of the revision's content, sizes, and | Metadata includes the hash of the revision's content, sizes, and | ||||
| links to its *parent* entries. The collective metadata is referred | links to its *parent* entries. The collective metadata is referred | ||||
| to as the *index* and the revision data is the *data*. | to as the *index* and the revision data is the *data*. | ||||
| Revision data is stored as a series of compressed deltas against previous | Revision data is stored as a series of compressed deltas against | ||||
| revisions. | ancestor revisions. | ||||
| Revlogs are written in an append-only fashion. We never need to rewrite | Revlogs are written in an append-only fashion. We never need to rewrite | ||||
| a file to insert nor do we need to remove data. Rolling back in-progress | a file to insert nor do we need to remove data. Rolling back in-progress | ||||
| writes can be performed by truncating files. Read locks can be avoided | writes can be performed by truncating files. Read locks can be avoided | ||||
| using simple techniques. This means that references to other data in | using simple techniques. This means that references to other data in | ||||
| the same revlog *always* refer to a previous entry. | the same revlog *always* refer to a previous entry. | ||||
| Revlogs can be modeled as 0-indexed arrays. The first revision is | Revlogs can be modeled as 0-indexed arrays. The first revision is | ||||
| revision #0 and the second is revision #1. The revision -1 is typically | revision #0 and the second is revision #1. The revision -1 is typically | ||||
| used to mean *does not exist* or *not defined*. | used to mean *does not exist* or *not defined*. | ||||
| File Format | File Format | ||||
| =========== | =========== | ||||
| A revlog begins with a 32-bit big endian integer holding version info | A revlog begins with a 32-bit big endian integer holding version info | ||||
| and feature flags. This integer is shared with the first revision | and feature flags. This integer is shared with the first revision | ||||
| entry. | entry. | ||||
| This integer is logically divided into 2 16-bit shorts. The least | This integer is logically divided into 2 16-bit shorts. The least | ||||
| significant half of the integer is the format/version short. The other | significant half of the integer is the format/version short. The other | ||||
| short holds feature flags that dictate behavior of the revlog. | short holds feature flags that dictate behavior of the revlog. | ||||
| Only 1 bit of the format/version short is currently used. Remaining | |||||
| bits are reserved for future use. | |||||
| The following values for the format/version short are defined: | The following values for the format/version short are defined: | ||||
| 0 | 0 | ||||
| The original revlog version. | The original revlog version. | ||||
| 1 | 1 | ||||
| RevlogNG (*next generation*). It replaced version 0 when it was | RevlogNG (*next generation*). It replaced version 0 when it was | ||||
| implemented in 2006. | implemented in 2006. | ||||
| 2 | 2 | ||||
| In-development version incorporating accumulated knowledge and | In-development version incorporating accumulated knowledge and | ||||
| missing features from 10+ years of revlog version 1. | missing features from 10+ years of revlog version 1. | ||||
| 57005 (0xdead) | 57005 (0xdead) | ||||
| Reserved for internal testing of new versions. No defined format | Reserved for internal testing of new versions. No defined format | ||||
| beyond 32-bit header. | beyond 32-bit header. | ||||
| The feature flags short consists of bit flags. Where 0 is the least | The feature flags short consists of bit flags. Where 0 is the least | ||||
| significant bit, the following bit offsets define flags: | significant bit. The bit flags vary by revlog version. | ||||
| Version 0 revlogs have no defined flags and the presence of a flag | |||||
| is considered an error. | |||||
| Version 1 revlogs have the following flags at the specified bit offsets: | |||||
| 0 | 0 | ||||
| Store revision data inline. | Store revision data inline. | ||||
| 1 | 1 | ||||
| Generaldelta encoding. | Generaldelta encoding. | ||||
| 2-15 | Version 2 revlogs have the following flags at the specified bit offsets: | ||||
| Reserved for future use. | |||||
| 0 | |||||
| Store revision data inline. | |||||
| 1 | |||||
| Generaldelta encoding. | |||||
| The following header values are common: | The following header values are common: | ||||
| 00 00 00 01 | 00 00 00 01 | ||||
| v1 | v1 | ||||
| 00 01 00 01 | 00 01 00 01 | ||||
| v1 + inline | v1 + inline | ||||
| 00 02 00 01 | 00 02 00 01 | ||||