Mercurial > hg
annotate mercurial/helptext/internals/dirstate-v2.txt @ 48180:f78d8b8c46d7
setup: stop packaging python3.dll and python3X.dll in the wheel distribution
Now that exewrapper is smart enough to find the DLLs it needs without help from
the build script, backout ed286d150aa8 and 2960b7fac966. Note that this will
require deleting the build/lib.win-amd64-3.X directory to actually remove it
from the final wheel.
Differential Revision: https://phab.mercurial-scm.org/D11455
author | Matt Harbison <matt_harbison@yahoo.com> |
---|---|
date | Sun, 19 Sep 2021 01:36:37 -0400 |
parents | e8a576de703f |
children | eb8092f9304f |
rev | line source |
---|---|
48166
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
1 The *dirstate* is what Mercurial uses internally to track |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
2 the state of files in the working directory, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
3 such as set by commands like `hg add` and `hg rm`. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
4 It also contains some cached data that help make `hg status` faster. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
5 The name refers both to `.hg/dirstate` on the filesystem |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
6 and the corresponding data structure in memory while a Mercurial process |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
7 is running. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
8 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
9 The original file format, retroactively dubbed `dirstate-v1`, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
10 is described at https://www.mercurial-scm.org/wiki/DirState. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
11 It is made of a flat sequence of unordered variable-size entries, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
12 so accessing any information in it requires parsing all of it. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
13 Similarly, saving changes requires rewriting the entire file. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
14 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
15 The newer `dirsate-v2` file format is designed to fix these limitations |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
16 and make `hg status` faster. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
17 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
18 User guide |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
19 ========== |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
20 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
21 Compatibility |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
22 ------------- |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
23 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
24 The file format is experimental and may still change. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
25 Different versions of Mercurial may not be compatible with each other |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
26 when working on a local repository that uses this format. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
27 When using an incompatible version with the experimental format, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
28 anything can happen including data corruption. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
29 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
30 Since the dirstate is entirely local and not relevant to the wire protocol, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
31 `dirstate-v2` does not affect compatibility with remote Mercurial versions. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
32 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
33 When `share-safe` is enabled, different repositories sharing the same store |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
34 can use different dirstate formats. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
35 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
36 Enabling `dirsate-v2` for new local repositories |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
37 ------------------------------------------------ |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
38 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
39 When creating a new local repository such as with `hg init` or `hg clone`, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
40 the `exp-dirstate-v2` boolean in the `format` configuration section |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
41 controls whether to use this file format. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
42 This is disabled by default as of this writing. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
43 To enable it for a single repository, run for example:: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
44 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
45 $ hg init my-project --config format.exp-dirstate-v2=1 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
46 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
47 Checking the format of an existing local repsitory |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
48 -------------------------------------------------- |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
49 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
50 The `debugformat` commands prints information about |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
51 which of multiple optional formats are used in the current repository, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
52 including `dirstate-v2`:: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
53 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
54 $ hg debugformat |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
55 format-variant repo |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
56 fncache: yes |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
57 dirstate-v2: yes |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
58 […] |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
59 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
60 Upgrading or downgrading an existing local repository |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
61 ----------------------------------------------------- |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
62 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
63 The `debugupgrade` command does various upgrades or downgrades |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
64 on a local repository |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
65 based on the current Mercurial version and on configuration. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
66 The same `format.exp-dirstate-v2` configuration is used again. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
67 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
68 Example to upgrade:: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
69 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
70 $ hg debugupgrade --config format.exp-dirstate-v2=1 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
71 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
72 Example to downgrade to `dirstate-v1`:: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
73 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
74 $ hg debugupgrade --config format.exp-dirstate-v2=0 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
75 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
76 Both of this commands do nothing but print a list of proposed changes, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
77 which may include changes unrelated to the dirstate. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
78 Those other changes are controlled by their own configuration keys. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
79 Add `--run` to a command to actually apply the proposed changes. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
80 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
81 Backups of `.hg/requires` and `.hg/dirstate` are created |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
82 in a `.hg/upgradebackup.*` directory. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
83 If something goes wrong, restoring those files should undo the change. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
84 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
85 Note that upgrading affects compatibility with older versions of Mercurial |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
86 as noted above. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
87 This can be relevant when a repository’s files are on a USB drive |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
88 or some other removable media, or shared over the network, etc. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
89 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
90 Internal filesystem representation |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
91 ================================== |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
92 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
93 Requirements file |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
94 ----------------- |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
95 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
96 The `.hg/requires` file indicates which of various optional file formats |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
97 are used by a given repository. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
98 Mercurial aborts when seeing a requirement it does not know about, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
99 which avoids older version accidentally messing up a respository |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
100 that uses a format that was introduced later. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
101 For versions that do support a format, the presence or absence of |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
102 the corresponding requirement indicates whether to use that format. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
103 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
104 When the file contains a `exp-dirstate-v2` line, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
105 the `dirstate-v2` format is used. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
106 With no such line `dirstate-v1` is used. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
107 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
108 High level description |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
109 ---------------------- |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
110 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
111 Whereas `dirstate-v1` uses a single `.hg/disrtate` file, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
112 in `dirstate-v2` that file is a "docket" file |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
113 that only contains some metadata |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
114 and points to separate data file named `.hg/dirstate.{ID}`, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
115 where `{ID}` is a random identifier. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
116 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
117 This separation allows making data files append-only |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
118 and therefore safer to memory-map. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
119 Creating a new data file (occasionally to clean up unused data) |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
120 can be done with a different ID |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
121 without disrupting another Mercurial process |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
122 that could still be using the previous data file. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
123 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
124 Both files have a format designed to reduce the need for parsing, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
125 by using fixed-size binary components as much as possible. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
126 For data that is not fixed-size, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
127 references to other parts of a file can be made by storing "pseudo-pointers": |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
128 integers counted in bytes from the start of a file. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
129 For read-only access no data structure is needed, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
130 only a bytes buffer (possibly memory-mapped directly from the filesystem) |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
131 with specific parts read on demand. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
132 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
133 The data file contains "nodes" organized in a tree. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
134 Each node represents a file or directory inside the working directory |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
135 or its parent changeset. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
136 This tree has the same structure as the filesystem, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
137 so a node representing a directory has child nodes representing |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
138 the files and subdirectories contained directly in that directory. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
139 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
140 The docket file format |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
141 ---------------------- |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
142 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
143 This is implemented in `rust/hg-core/src/dirstate_tree/on_disk.rs` |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
144 and `mercurial/dirstateutils/docket.py`. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
145 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
146 Components of the docket file are found at fixed offsets, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
147 counted in bytes from the start of the file: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
148 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
149 * Offset 0: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
150 The 12-bytes marker string "dirstate-v2\n" ending with a newline character. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
151 This makes it easier to tell a dirstate-v2 file from a dirstate-v1 file, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
152 although it is not strictly necessary |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
153 since `.hg/requires` determines which format to use. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
154 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
155 * Offset 12: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
156 The changeset node ID on the first parent of the working directory, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
157 as up to 32 binary bytes. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
158 If a node ID is shorter (20 bytes for SHA-1), |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
159 it is start-aligned and the rest of the bytes are set to zero. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
160 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
161 * Offset 44: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
162 The changeset node ID on the second parent of the working directory, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
163 or all zeros if there isn’t one. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
164 Also 32 binary bytes. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
165 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
166 * Offset 76: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
167 Tree metadata on 44 bytes, described below. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
168 Its separation in this documentation from the rest of the docket |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
169 reflects a detail of the current implementation. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
170 Since tree metadata is also made of fields at fixed offsets, those could |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
171 be inlined here by adding 76 bytes to each offset. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
172 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
173 * Offset 120: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
174 The used size of the data file, as a 32-bit big-endian integer. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
175 The actual size of the data file may be larger |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
176 (if another Mercurial processis in appending to it |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
177 but has not updated the docket yet). |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
178 That extra data must be ignored. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
179 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
180 * Offset 124: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
181 The length of the data file identifier, as a 8-bit integer. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
182 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
183 * Offset 125: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
184 The data file identifier. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
185 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
186 * Any additional data is current ignored, and dropped when updating the file. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
187 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
188 Tree metadata in the docket file |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
189 -------------------------------- |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
190 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
191 Tree metadata is similarly made of components at fixed offsets. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
192 These offsets are counted in bytes from the start of tree metadata, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
193 which is 76 bytes after the start of the docket file. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
194 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
195 This metadata can be thought of as the singular root of the tree |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
196 formed by nodes in the data file. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
197 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
198 * Offset 0: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
199 Pseudo-pointer to the start of root nodes, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
200 counted in bytes from the start of the data file, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
201 as a 32-bit big-endian integer. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
202 These nodes describe files and directories found directly |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
203 at the root of the working directory. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
204 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
205 * Offset 4: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
206 Number of root nodes, as a 32-bit big-endian integer. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
207 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
208 * Offset 8: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
209 Total number of nodes in the entire tree that "have a dirstate entry", |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
210 as a 32-bit big-endian integer. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
211 Those nodes represent files that would be present at all in `dirstate-v1`. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
212 This is typically less than the total number of nodes. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
213 This counter is used to implement `len(dirstatemap)`. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
214 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
215 * Offset 12: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
216 Number of nodes in the entire tree that have a copy source, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
217 as a 32-bit big-endian integer. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
218 At the next commit, these files are recorded |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
219 as having been copied or moved/renamed from that source. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
220 (A move is recorded as a copy and separate removal of the source.) |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
221 This counter is used to implement `len(dirstatemap.copymap)`. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
222 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
223 * Offset 16: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
224 An estimation of how many bytes of the data file |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
225 (within its used size) are unused, as a 32-bit big-endian integer. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
226 When appending to an existing data file, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
227 some existing nodes or paths can be unreachable from the new root |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
228 but they still take up space. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
229 This counter is used to decide when to write a new data file from scratch |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
230 instead of appending to an existing one, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
231 in order to get rid of that unreachable data |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
232 and avoid unbounded file size growth. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
233 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
234 * Offset 20: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
235 These four bytes are currently ignored |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
236 and reset to zero when updating a docket file. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
237 This is an attempt at forward compatibility: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
238 future Mercurial versions could use this as a bit field |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
239 to indicate that a dirstate has additional data or constraints. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
240 Finding a dirstate file with the relevant bit unset indicates that |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
241 it was written by a then-older version |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
242 which is not aware of that future change. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
243 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
244 * Offset 24: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
245 Either 20 zero bytes, or a SHA-1 hash as 20 binary bytes. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
246 When present, the hash is of ignore patterns |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
247 that were used for some previous run of the `status` algorithm. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
248 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
249 * (Offset 44: end of tree metadata) |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
250 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
251 Optional hash of ignore patterns |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
252 -------------------------------- |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
253 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
254 The implementation of `status` at `rust/hg-core/src/dirstate_tree/status.rs` |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
255 has been optimized such that its run time is dominated by calls |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
256 to `stat` for reading the filesystem metadata of a file or directory, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
257 and to `readdir` for listing the contents of a directory. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
258 In some cases the algorithm can skip calls to `readdir` |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
259 (saving significant time) |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
260 because the dirstate already contains enough of the relevant information |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
261 to build the correct `status` results. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
262 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
263 The default configuration of `hg status` is to list unknown files |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
264 but not ignored files. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
265 In this case, it matters for the `readdir`-skipping optimization |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
266 if a given file used to be ignored but became unknown |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
267 because `.hgignore` changed. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
268 To detect the possibility of such a change, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
269 the tree metadata contains an optional hash of all ignore patterns. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
270 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
271 We define: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
272 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
273 * "Root" ignore files as: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
274 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
275 - `.hgignore` at the root of the repository if it exists |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
276 - And all files from `ui.ignore.*` config. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
277 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
278 This set of files is sorted by the string representation of their path. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
279 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
280 * The "expanded contents" of an ignore files is the byte string made |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
281 by the concatenation of its contents followed by the "expanded contents" |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
282 of other files included with `include:` or `subinclude:` directives, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
283 in inclusion order. This definition is recursive, as included files can |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
284 themselves include more files. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
285 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
286 This hash is defined as the SHA-1 of the concatenation (in sorted |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
287 order) of the "expanded contents" of each "root" ignore file. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
288 (Note that computing this does not require actually concatenating byte ranges into |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
289 contiguous memory. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
290 Instead a SHA-1 hasher object can be created and fed separate byte ranges one by |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
291 one.) |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
292 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
293 The data file format |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
294 -------------------- |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
295 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
296 This is implemented in `rust/hg-core/src/dirstate_tree/on_disk.rs` |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
297 and `mercurial/dirstateutils/v2.py`. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
298 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
299 The data file contains two types of data: paths and nodes. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
300 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
301 Paths and nodes can be organized in any order in the file, except that sibling |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
302 nodes must be next to each other and sorted by their path. Contiguity lets |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
303 the parent refer to them all by their count with a single pseudo-pointer, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
304 instead of storing one pseudo-pointer per child node. Sorting allows using |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
305 binary seach to find a child node with a given name in `O(log(n))` byte ranges |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
306 comparisons. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
307 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
308 The current implemention writes paths and child node before a given node |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
309 for ease of figuring out the value of pseudo-pointers by the time the are to be |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
310 written, but this is not an obligation and readers must not rely on it. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
311 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
312 A path is stored as a byte string anywhere in the file, without delimiter. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
313 It is refered to by one or more node by a pseudo-pointer to its start, and its |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
314 length in bytes. Since there is no delimiter, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
315 when a path is a substring of another the same bytes could be reused, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
316 although the implementation does not exploit this as of this writing. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
317 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
318 A node is stored on 43 bytes with components at fixed offsets. Paths and |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
319 child nodes relevant to a node are stored externally and referenced though |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
320 pseudo-pointers. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
321 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
322 All integers are stored in big-endian. All pseudo-pointers are 32-bit integers |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
323 counting bytes from the start of the data file. Path lengths and positions |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
324 are 16-bit integers, also counted in bytes. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
325 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
326 Node components are: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
327 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
328 * Offset 0: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
329 Pseudo-pointer to the full path of this node, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
330 from the working directory root. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
331 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
332 * Offset 4: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
333 Length of the full path. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
334 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
335 * Offset 6: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
336 Position of the last `/` path separator within the full path, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
337 in bytes from the start of the full path, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
338 or zero if there isn’t one. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
339 The part of the full path after this position is the "base name". |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
340 Since sibling nodes have the same parent, only their base name vary |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
341 and needs to be considered when doing binary search to find a given path. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
342 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
343 * Offset 8: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
344 Pseudo-pointer to the "copy source" path for this node, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
345 or zero if there is no copy source. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
346 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
347 * Offset 12: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
348 Length of the copy source path, or zero if there isn’t one. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
349 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
350 * Offset 14: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
351 Pseudo-pointer to the start of child nodes. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
352 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
353 * Offset 18: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
354 Number of child nodes, as a 32-bit integer. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
355 They occupy 43 times this number of bytes |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
356 (not counting space for paths, and further descendants). |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
357 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
358 * Offset 22: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
359 Number as a 32-bit integer of descendant nodes in this subtree, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
360 not including this node itself, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
361 that "have a dirstate entry". |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
362 Those nodes represent files that would be present at all in `dirstate-v1`. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
363 This is typically less than the total number of descendants. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
364 This counter is used to implement `has_dir`. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
365 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
366 * Offset 26: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
367 Number as a 32-bit integer of descendant nodes in this subtree, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
368 not including this node itself, |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
369 that represent files tracked in the working directory. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
370 (For example, `hg rm` makes a file untracked.) |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
371 This counter is used to implement `has_tracked_dir`. |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
372 |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
373 * Offset 30 and more: |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
374 **TODO:** docs not written yet |
e8a576de703f
dirstate-v2: Add internal documentation
Simon Sapin <simon.sapin@octobus.net>
parents:
diff
changeset
|
375 as this part of the format might be changing soon. |