942 --config format.use-dirstate-v2=False \ |
942 --config format.use-dirstate-v2=False \ |
943 --config storage.dirstate-v2.slow-path=allow |
943 --config storage.dirstate-v2.slow-path=allow |
944 |
944 |
945 For a more comprehensive guide, see :hg:`help internals.dirstate-v2`. |
945 For a more comprehensive guide, see :hg:`help internals.dirstate-v2`. |
946 |
946 |
947 ``use-dirstate-tracked-key`` |
947 ``use-dirstate-tracked-hint`` |
948 Enable or disable the writing of "tracked key" file alongside the dirstate. |
948 Enable or disable the writing of "tracked key" file alongside the dirstate. |
949 (default to disabled) |
949 (default to disabled) |
950 |
950 |
951 That "tracked-key" can help external automations to detect changes to the |
951 That "tracked-hint" can help external automations to detect changes to the |
952 set of tracked files. |
952 set of tracked files. (i.e the result of `hg files` or `hg status -macd`) |
953 |
953 |
954 The tracked-key is written in a new `.hg/dirstate-tracked-key`. That file |
954 The tracked-hint is written in a new `.hg/dirstate-tracked-hint`. That file |
955 contains two lines: |
955 contains two lines: |
956 - the first line is the file version (currently: 1), |
956 - the first line is the file version (currently: 1), |
957 - the second line contains the "tracked-key". |
957 - the second line contains the "tracked-hint". |
958 |
958 That file is written right after the dirstate is written. |
959 The tracked-key changes whenever the set of file tracked in the dirstate |
959 |
960 changes. The general guarantees are: |
960 The tracked-hint changes whenever the set of file tracked in the dirstate |
961 - if the tracked key is identical, the set of tracked file MUST not have changed, |
961 changes. The general idea is: |
962 - if the tracked key is different, the set of tracked file MIGHT differ. |
962 - if the hint is identical, the set of tracked file SHOULD be identical, |
|
963 - if the hint is different, the set of tracked file MIGHT be different. |
|
964 |
|
965 The "hint is identical" case uses `SHOULD` as the dirstate and the hint file |
|
966 are two distinct files and therefore that cannot be read or written to in an |
|
967 atomic way. If the key is identical, nothing garantees that the dirstate is |
|
968 not updated right after the hint file. This is considered a negligible |
|
969 limitation for the intended usecase. It is actually possible to prevent this |
|
970 race by taking the repository lock during read operations. |
963 |
971 |
964 They are two "ways" to use this feature: |
972 They are two "ways" to use this feature: |
965 |
973 |
966 1) monitoring changes to the `.hg/dirstate-tracked-key`, if the file changes |
974 1) monitoring changes to the `.hg/dirstate-tracked-hint`, if the file |
967 the tracked set might have changed. |
975 changes, the tracked set might have changed. |
968 |
976 |
969 2) storing the value and comparing it to a later value. Beware that it is |
977 2) storing the value and comparing it to a later value. |
970 impossible to achieve atomic writing or reading of the two files involved |
|
971 files (`.hg/dirstate` and `.hg/dirstate-tracked-key`). So it is needed to |
|
972 read the `tracked-key` files twice: before and after reading the tracked |
|
973 set. The `tracked-key` is only usable as a cache key if it had the same |
|
974 value in both cases and must be discarded otherwise. |
|
975 |
|
976 To enforce that the `tracked-key` value can be used race-free (with double |
|
977 reading as explained in (2)), the `.hg/dirstate-tracked-key` is written |
|
978 twice: before and after we change the associated `.hg/dirstate` file. |
|
979 |
978 |
980 ``use-persistent-nodemap`` |
979 ``use-persistent-nodemap`` |
981 Enable or disable the "persistent-nodemap" feature which improves |
980 Enable or disable the "persistent-nodemap" feature which improves |
982 performance if the Rust extensions are available. |
981 performance if the Rust extensions are available. |
983 |
982 |