Patchwork D12201: tracked-key: remove the dual write and rename to tracked-hint

login
register
mail settings
Submitter phabricator
Date Feb. 17, 2022, 10:27 a.m.
Message ID <differential-rev-PHID-DREV-gwqaqvophezy3c73ie2s-req@mercurial-scm.org>
Download mbox | patch
Permalink /patch/50538/
State New
Headers show

Comments

phabricator - Feb. 17, 2022, 10:27 a.m.
marmoute created this revision.
Herald added a reviewer: hg-reviewers.
Herald added a subscriber: mercurial-patches.

REVISION SUMMARY
  The dual-write approach was mostly useless. As explained in the previous version
  of the help, the key had to be read twice before we could cache a value.
  
  However this "read twice" limitation actually also apply to any usage of the
  key. If some operation wants to rely of the "same value == same tracked set"
  property it would need to read the value before, and after running that
  operation (or at least, after, in all cases). So it cannot be sure the operation
  it did is "valid" until checking the key after the operation. As a resultat such
  operation can only be read-only or rollbackable.
  
  This reduce the utility of the "same value == same tracked set" a lot.
  
  So it seems simpler to drop the double write and to update the documentation to
  highlight that this file does not garantee race-free operation. As a result the
  "key" is demoted to a "hint".
  
  Documentation is updated accordingly.

REPOSITORY
  rHG Mercurial

BRANCH
  default

REVISION DETAIL
  https://phab.mercurial-scm.org/D12201

AFFECTED FILES
  mercurial/configitems.py
  mercurial/dirstate.py
  mercurial/helptext/config.txt
  mercurial/localrepo.py
  mercurial/requirements.py
  mercurial/upgrade_utils/actions.py
  mercurial/upgrade_utils/engine.py
  tests/test-help.t
  tests/test-persistent-nodemap.t
  tests/test-status-tracked-key.t
  tests/test-upgrade-repo.t

CHANGE DETAILS




To: marmoute, #hg-reviewers
Cc: mercurial-patches, mercurial-devel

Patch

diff --git a/tests/test-upgrade-repo.t b/tests/test-upgrade-repo.t
--- a/tests/test-upgrade-repo.t
+++ b/tests/test-upgrade-repo.t
@@ -214,7 +214,7 @@ 
   format-variant     repo
   fncache:            yes
   dirstate-v2:         no
-  tracked-key:         no
+  tracked-hint:        no
   dotencode:          yes
   generaldelta:       yes
   share-safe:         yes
@@ -231,7 +231,7 @@ 
   format-variant     repo config default
   fncache:            yes    yes     yes
   dirstate-v2:         no     no      no
-  tracked-key:         no     no      no
+  tracked-hint:        no     no      no
   dotencode:          yes    yes     yes
   generaldelta:       yes    yes     yes
   share-safe:         yes    yes     yes
@@ -249,7 +249,7 @@ 
   format-variant     repo config default
   fncache:            yes     no     yes
   dirstate-v2:         no     no      no
-  tracked-key:         no     no      no
+  tracked-hint:        no     no      no
   dotencode:          yes     no     yes
   generaldelta:       yes    yes     yes
   share-safe:         yes    yes     yes
@@ -267,7 +267,7 @@ 
   format-variant     repo config default
   [formatvariant.name.mismatchconfig|fncache:           ][formatvariant.repo.mismatchconfig| yes][formatvariant.config.special|     no][formatvariant.default|     yes]
   [formatvariant.name.uptodate|dirstate-v2:       ][formatvariant.repo.uptodate|  no][formatvariant.config.default|     no][formatvariant.default|      no]
-  [formatvariant.name.uptodate|tracked-key:       ][formatvariant.repo.uptodate|  no][formatvariant.config.default|     no][formatvariant.default|      no]
+  [formatvariant.name.uptodate|tracked-hint:      ][formatvariant.repo.uptodate|  no][formatvariant.config.default|     no][formatvariant.default|      no]
   [formatvariant.name.mismatchconfig|dotencode:         ][formatvariant.repo.mismatchconfig| yes][formatvariant.config.special|     no][formatvariant.default|     yes]
   [formatvariant.name.uptodate|generaldelta:      ][formatvariant.repo.uptodate| yes][formatvariant.config.default|    yes][formatvariant.default|     yes]
   [formatvariant.name.uptodate|share-safe:        ][formatvariant.repo.uptodate| yes][formatvariant.config.default|    yes][formatvariant.default|     yes]
@@ -298,7 +298,7 @@ 
    {
     "config": false,
     "default": false,
-    "name": "tracked-key",
+    "name": "tracked-hint",
     "repo": false
    },
    {
@@ -498,7 +498,7 @@ 
   format-variant     repo
   fncache:             no
   dirstate-v2:         no
-  tracked-key:         no
+  tracked-hint:        no
   dotencode:           no
   generaldelta:        no
   share-safe:          no
@@ -514,7 +514,7 @@ 
   format-variant     repo config default
   fncache:             no    yes     yes
   dirstate-v2:         no     no      no
-  tracked-key:         no     no      no
+  tracked-hint:        no     no      no
   dotencode:           no    yes     yes
   generaldelta:        no    yes     yes
   share-safe:          no    yes     yes
@@ -532,7 +532,7 @@ 
   format-variant     repo config default
   fncache:             no    yes     yes
   dirstate-v2:         no     no      no
-  tracked-key:         no     no      no
+  tracked-hint:        no     no      no
   dotencode:           no    yes     yes
   generaldelta:        no     no     yes
   share-safe:          no    yes     yes
@@ -550,7 +550,7 @@ 
   format-variant     repo config default
   [formatvariant.name.mismatchconfig|fncache:           ][formatvariant.repo.mismatchconfig|  no][formatvariant.config.default|    yes][formatvariant.default|     yes]
   [formatvariant.name.uptodate|dirstate-v2:       ][formatvariant.repo.uptodate|  no][formatvariant.config.default|     no][formatvariant.default|      no]
-  [formatvariant.name.uptodate|tracked-key:       ][formatvariant.repo.uptodate|  no][formatvariant.config.default|     no][formatvariant.default|      no]
+  [formatvariant.name.uptodate|tracked-hint:      ][formatvariant.repo.uptodate|  no][formatvariant.config.default|     no][formatvariant.default|      no]
   [formatvariant.name.mismatchconfig|dotencode:         ][formatvariant.repo.mismatchconfig|  no][formatvariant.config.default|    yes][formatvariant.default|     yes]
   [formatvariant.name.mismatchdefault|generaldelta:      ][formatvariant.repo.mismatchdefault|  no][formatvariant.config.special|     no][formatvariant.default|     yes]
   [formatvariant.name.mismatchconfig|share-safe:        ][formatvariant.repo.mismatchconfig|  no][formatvariant.config.default|    yes][formatvariant.default|     yes]
@@ -1602,7 +1602,7 @@ 
   format-variant     repo config default
   fncache:            yes    yes     yes
   dirstate-v2:         no     no      no
-  tracked-key:         no     no      no
+  tracked-hint:        no     no      no
   dotencode:          yes    yes     yes
   generaldelta:       yes    yes     yes
   share-safe:         yes    yes     yes
@@ -1646,7 +1646,7 @@ 
   format-variant     repo config default
   fncache:            yes    yes     yes
   dirstate-v2:         no     no      no
-  tracked-key:         no     no      no
+  tracked-hint:        no     no      no
   dotencode:          yes    yes     yes
   generaldelta:       yes    yes     yes
   share-safe:         yes    yes     yes
@@ -1693,7 +1693,7 @@ 
   format-variant     repo config default
   fncache:            yes    yes     yes
   dirstate-v2:         no     no      no
-  tracked-key:         no     no      no
+  tracked-hint:        no     no      no
   dotencode:          yes    yes     yes
   generaldelta:       yes    yes     yes
   share-safe:         yes    yes     yes
@@ -1746,7 +1746,7 @@ 
   format-variant     repo config default
   fncache:            yes    yes     yes
   dirstate-v2:         no     no      no
-  tracked-key:         no     no      no
+  tracked-hint:        no     no      no
   dotencode:          yes    yes     yes
   generaldelta:       yes    yes     yes
   share-safe:         yes    yes     yes
@@ -1796,7 +1796,7 @@ 
   format-variant     repo config default
   fncache:            yes    yes     yes
   dirstate-v2:         no     no      no
-  tracked-key:         no     no      no
+  tracked-hint:        no     no      no
   dotencode:          yes    yes     yes
   generaldelta:       yes    yes     yes
   share-safe:         yes    yes     yes
@@ -1847,7 +1847,7 @@ 
   format-variant     repo config default
   fncache:            yes    yes     yes
   dirstate-v2:         no     no      no
-  tracked-key:         no     no      no
+  tracked-hint:        no     no      no
   dotencode:          yes    yes     yes
   generaldelta:       yes    yes     yes
   share-safe:         yes    yes     yes
diff --git a/tests/test-status-tracked-key.t b/tests/test-status-tracked-key.t
--- a/tests/test-status-tracked-key.t
+++ b/tests/test-status-tracked-key.t
@@ -1,19 +1,19 @@ 
-==============================
-Test the "tracked key" feature
-==============================
+===============================
+Test the "tracked hint" feature
+===============================
 
-The tracked key feature provide a file that get updated when the set of tracked
+The tracked hint feature provide a file that get updated when the set of tracked
 files get updated.
 
 basic setup
 
   $ cat << EOF >> $HGRCPATH
   > [format]
-  > use-dirstate-tracked-key=yes
+  > use-dirstate-tracked-hint=yes
   > EOF
 
-  $ hg init tracked-key-test
-  $ cd tracked-key-test
+  $ hg init tracked-hint-test
+  $ cd tracked-hint-test
   $ hg debugbuilddag '.+10' -n
   $ hg log -G -T '{rev} {desc} {files}\n'
   o  10 r10 nf10
@@ -56,61 +56,61 @@ 
 key-file exists
 -----------
 
-The tracked key file should exist
+The tracked hint file should exist
 
   $ ls -1 .hg/dirstate*
   .hg/dirstate
-  .hg/dirstate-tracked-key
+  .hg/dirstate-tracked-hint
 
 key-file stay the same if the tracked set is unchanged
 ------------------------------------------------------
 
 (copy its content for later comparison)
 
-  $ cp .hg/dirstate-tracked-key ../key-bck
+  $ cp .hg/dirstate-tracked-hint ../key-bck
   $ echo foo >> nf0
   $ sleep 1
   $ hg status
   M nf0
-  $ diff --brief .hg/dirstate-tracked-key ../key-bck
+  $ diff --brief .hg/dirstate-tracked-hint ../key-bck
   $ hg revert -C nf0
   $ sleep 1
   $ hg status
-  $ diff --brief .hg/dirstate-tracked-key ../key-bck
+  $ diff --brief .hg/dirstate-tracked-hint ../key-bck
 
 key-file change if the tracked set is changed manually
 ------------------------------------------------------
 
 adding a file to tracking
 
-  $ cp .hg/dirstate-tracked-key ../key-bck
+  $ cp .hg/dirstate-tracked-hint ../key-bck
   $ echo x > x
   $ hg add x
-  $ diff --brief .hg/dirstate-tracked-key ../key-bck
-  Files .hg/dirstate-tracked-key and ../key-bck differ
+  $ diff --brief .hg/dirstate-tracked-hint ../key-bck
+  Files .hg/dirstate-tracked-hint and ../key-bck differ
   [1]
 
 remove a file from tracking
 (forget)
 
-  $ cp .hg/dirstate-tracked-key ../key-bck
+  $ cp .hg/dirstate-tracked-hint ../key-bck
   $ hg forget x
-  $ diff --brief .hg/dirstate-tracked-key ../key-bck
-  Files .hg/dirstate-tracked-key and ../key-bck differ
+  $ diff --brief .hg/dirstate-tracked-hint ../key-bck
+  Files .hg/dirstate-tracked-hint and ../key-bck differ
   [1]
 
 (remove)
 
-  $ cp .hg/dirstate-tracked-key ../key-bck
+  $ cp .hg/dirstate-tracked-hint ../key-bck
   $ hg remove nf1
-  $ diff --brief .hg/dirstate-tracked-key ../key-bck
-  Files .hg/dirstate-tracked-key and ../key-bck differ
+  $ diff --brief .hg/dirstate-tracked-hint ../key-bck
+  Files .hg/dirstate-tracked-hint and ../key-bck differ
   [1]
 
 key-file changes on revert (when applicable)
 --------------------------------------------
 
-  $ cp .hg/dirstate-tracked-key ../key-bck
+  $ cp .hg/dirstate-tracked-hint ../key-bck
   $ hg status
   R nf1
   ? x
@@ -118,8 +118,8 @@ 
   undeleting nf1
   $ hg status
   ? x
-  $ diff --brief .hg/dirstate-tracked-key ../key-bck
-  Files .hg/dirstate-tracked-key and ../key-bck differ
+  $ diff --brief .hg/dirstate-tracked-hint ../key-bck
+  Files .hg/dirstate-tracked-hint and ../key-bck differ
   [1]
 
 
@@ -130,24 +130,24 @@ 
 
 (removing)
 
-  $ cp .hg/dirstate-tracked-key ../key-bck
+  $ cp .hg/dirstate-tracked-hint ../key-bck
   $ hg status --rev . --rev '.#generations[-1]'
   R nf10
   $ hg up '.#generations[-1]'
   0 files updated, 0 files merged, 1 files removed, 0 files unresolved
-  $ diff --brief .hg/dirstate-tracked-key ../key-bck
-  Files .hg/dirstate-tracked-key and ../key-bck differ
+  $ diff --brief .hg/dirstate-tracked-hint ../key-bck
+  Files .hg/dirstate-tracked-hint and ../key-bck differ
   [1]
 
 (adding)
 
-  $ cp .hg/dirstate-tracked-key ../key-bck
+  $ cp .hg/dirstate-tracked-hint ../key-bck
   $ hg status --rev . --rev '.#generations[1]'
   A nf10
   $ hg up '.#generations[1]'
   1 files updated, 0 files merged, 0 files removed, 0 files unresolved
-  $ diff --brief .hg/dirstate-tracked-key ../key-bck
-  Files .hg/dirstate-tracked-key and ../key-bck differ
+  $ diff --brief .hg/dirstate-tracked-hint ../key-bck
+  Files .hg/dirstate-tracked-hint and ../key-bck differ
   [1]
 
 update not affecting the tracked set
@@ -155,24 +155,24 @@ 
   $ echo foo >> nf0
   $ hg commit -m foo
 
-  $ cp .hg/dirstate-tracked-key ../key-bck
+  $ cp .hg/dirstate-tracked-hint ../key-bck
   $ hg status --rev . --rev '.#generations[-1]'
   M nf0
   $ hg up '.#generations[-1]'
   1 files updated, 0 files merged, 0 files removed, 0 files unresolved
-  $ diff --brief .hg/dirstate-tracked-key ../key-bck
+  $ diff --brief .hg/dirstate-tracked-hint ../key-bck
 
 Test upgrade and downgrade
 ==========================
 
-  $ ls .hg/dirstate-tracked-key
-  .hg/dirstate-tracked-key
+  $ ls .hg/dirstate-tracked-hint
+  .hg/dirstate-tracked-hint
   $ hg debugrequires | grep 'tracked'
   dirstate-tracked-key-v1
 
 downgrade
 
-  $ hg debugupgraderepo --config format.use-dirstate-tracked-key=no --run --quiet
+  $ hg debugupgraderepo --config format.use-dirstate-tracked-hint=no --run --quiet
   upgrade will perform the following actions:
   
   requirements
@@ -181,15 +181,15 @@ 
   
   no revlogs to process
   
-  $ ls -1 .hg/dirstate-tracked-key
-  ls: cannot access '.hg/dirstate-tracked-key': $ENOENT$
+  $ ls -1 .hg/dirstate-tracked-hint
+  ls: cannot access '.hg/dirstate-tracked-hint': $ENOENT$
   [2]
   $ hg debugrequires | grep 'tracked'
   [1]
 
 upgrade
 
-  $ hg debugupgraderepo --config format.use-dirstate-tracked-key=yes --run --quiet
+  $ hg debugupgraderepo --config format.use-dirstate-tracked-hint=yes --run --quiet
   upgrade will perform the following actions:
   
   requirements
@@ -198,7 +198,7 @@ 
   
   no revlogs to process
   
-  $ ls -1 .hg/dirstate-tracked-key
-  .hg/dirstate-tracked-key
+  $ ls -1 .hg/dirstate-tracked-hint
+  .hg/dirstate-tracked-hint
   $ hg debugrequires | grep 'tracked'
   dirstate-tracked-key-v1
diff --git a/tests/test-persistent-nodemap.t b/tests/test-persistent-nodemap.t
--- a/tests/test-persistent-nodemap.t
+++ b/tests/test-persistent-nodemap.t
@@ -65,7 +65,7 @@ 
   format-variant     repo
   fncache:            yes
   dirstate-v2:         no
-  tracked-key:         no
+  tracked-hint:        no
   dotencode:          yes
   generaldelta:       yes
   share-safe:         yes
@@ -783,7 +783,7 @@ 
   format-variant     repo config default
   fncache:            yes    yes     yes
   dirstate-v2:         no     no      no
-  tracked-key:         no     no      no
+  tracked-hint:        no     no      no
   dotencode:          yes    yes     yes
   generaldelta:       yes    yes     yes
   share-safe:         yes    yes     yes
@@ -826,7 +826,7 @@ 
   format-variant     repo config default
   fncache:            yes    yes     yes
   dirstate-v2:         no     no      no
-  tracked-key:         no     no      no
+  tracked-hint:        no     no      no
   dotencode:          yes    yes     yes
   generaldelta:       yes    yes     yes
   share-safe:         yes    yes     yes
diff --git a/tests/test-help.t b/tests/test-help.t
--- a/tests/test-help.t
+++ b/tests/test-help.t
@@ -1599,7 +1599,7 @@ 
   
       "use-dirstate-v2"
   
-      "use-dirstate-tracked-key"
+      "use-dirstate-tracked-hint"
   
       "use-persistent-nodemap"
   
diff --git a/mercurial/upgrade_utils/engine.py b/mercurial/upgrade_utils/engine.py
--- a/mercurial/upgrade_utils/engine.py
+++ b/mercurial/upgrade_utils/engine.py
@@ -487,12 +487,12 @@ 
         upgrade_op.removed_actions.remove(upgrade_actions.dirstatev2)
 
     if upgrade_actions.dirstatetrackedkey in upgrade_op.upgrade_actions:
-        ui.status(_(b'create dirstate-tracked-key file\n'))
-        upgrade_tracked_key(ui, srcrepo, upgrade_op, add=True)
+        ui.status(_(b'create dirstate-tracked-hint file\n'))
+        upgrade_tracked_hint(ui, srcrepo, upgrade_op, add=True)
         upgrade_op.upgrade_actions.remove(upgrade_actions.dirstatetrackedkey)
     elif upgrade_actions.dirstatetrackedkey in upgrade_op.removed_actions:
-        ui.status(_(b'remove dirstate-tracked-key file\n'))
-        upgrade_tracked_key(ui, srcrepo, upgrade_op, add=False)
+        ui.status(_(b'remove dirstate-tracked-hint file\n'))
+        upgrade_tracked_hint(ui, srcrepo, upgrade_op, add=False)
         upgrade_op.removed_actions.remove(upgrade_actions.dirstatetrackedkey)
 
     if not (upgrade_op.upgrade_actions or upgrade_op.removed_actions):
@@ -671,13 +671,13 @@ 
     scmutil.writereporequirements(srcrepo, upgrade_op.new_requirements)
 
 
-def upgrade_tracked_key(ui, srcrepo, upgrade_op, add):
+def upgrade_tracked_hint(ui, srcrepo, upgrade_op, add):
     if add:
-        srcrepo.dirstate._use_tracked_key = True
+        srcrepo.dirstate._use_tracked_hint = True
         srcrepo.dirstate._dirty = True
         srcrepo.dirstate._dirty_tracked_set = True
         srcrepo.dirstate.write(None)
     if not add:
-        srcrepo.dirstate.delete_tracked_key()
+        srcrepo.dirstate.delete_tracked_hint()
 
     scmutil.writereporequirements(srcrepo, upgrade_op.new_requirements)
diff --git a/mercurial/upgrade_utils/actions.py b/mercurial/upgrade_utils/actions.py
--- a/mercurial/upgrade_utils/actions.py
+++ b/mercurial/upgrade_utils/actions.py
@@ -201,8 +201,8 @@ 
 
 @registerformatvariant
 class dirstatetrackedkey(requirementformatvariant):
-    name = b'tracked-key'
-    _requirement = requirements.DIRSTATE_TRACKED_KEY_V1
+    name = b'tracked-hint'
+    _requirement = requirements.DIRSTATE_TRACKED_HINT_V1
 
     default = False
 
@@ -990,7 +990,7 @@ 
         requirements.REVLOGV2_REQUIREMENT,
         requirements.CHANGELOGV2_REQUIREMENT,
         requirements.REVLOGV1_REQUIREMENT,
-        requirements.DIRSTATE_TRACKED_KEY_V1,
+        requirements.DIRSTATE_TRACKED_HINT_V1,
         requirements.DIRSTATE_V2_REQUIREMENT,
     }
     for name in compression.compengines:
@@ -1013,7 +1013,7 @@ 
     supported = {
         requirements.CHANGELOGV2_REQUIREMENT,
         requirements.COPIESSDC_REQUIREMENT,
-        requirements.DIRSTATE_TRACKED_KEY_V1,
+        requirements.DIRSTATE_TRACKED_HINT_V1,
         requirements.DIRSTATE_V2_REQUIREMENT,
         requirements.DOTENCODE_REQUIREMENT,
         requirements.FNCACHE_REQUIREMENT,
@@ -1056,7 +1056,7 @@ 
         requirements.REVLOGV1_REQUIREMENT,
         requirements.REVLOGV2_REQUIREMENT,
         requirements.CHANGELOGV2_REQUIREMENT,
-        requirements.DIRSTATE_TRACKED_KEY_V1,
+        requirements.DIRSTATE_TRACKED_HINT_V1,
         requirements.DIRSTATE_V2_REQUIREMENT,
     }
     for name in compression.compengines:
diff --git a/mercurial/requirements.py b/mercurial/requirements.py
--- a/mercurial/requirements.py
+++ b/mercurial/requirements.py
@@ -18,7 +18,7 @@ 
 STORE_REQUIREMENT = b'store'
 FNCACHE_REQUIREMENT = b'fncache'
 
-DIRSTATE_TRACKED_KEY_V1 = b'dirstate-tracked-key-v1'
+DIRSTATE_TRACKED_HINT_V1 = b'dirstate-tracked-key-v1'
 DIRSTATE_V2_REQUIREMENT = b'dirstate-v2'
 
 # When narrowing is finalized and no longer subject to format changes,
@@ -97,7 +97,7 @@ 
     SHARED_REQUIREMENT,
     RELATIVE_SHARED_REQUIREMENT,
     SHARESAFE_REQUIREMENT,
-    DIRSTATE_TRACKED_KEY_V1,
+    DIRSTATE_TRACKED_HINT_V1,
     DIRSTATE_V2_REQUIREMENT,
 }
 
diff --git a/mercurial/localrepo.py b/mercurial/localrepo.py
--- a/mercurial/localrepo.py
+++ b/mercurial/localrepo.py
@@ -1278,7 +1278,7 @@ 
         requirementsmod.BOOKMARKS_IN_STORE_REQUIREMENT,
         requirementsmod.CHANGELOGV2_REQUIREMENT,
         requirementsmod.COPIESSDC_REQUIREMENT,
-        requirementsmod.DIRSTATE_TRACKED_KEY_V1,
+        requirementsmod.DIRSTATE_TRACKED_HINT_V1,
         requirementsmod.DIRSTATE_V2_REQUIREMENT,
         requirementsmod.DOTENCODE_REQUIREMENT,
         requirementsmod.FNCACHE_REQUIREMENT,
@@ -1743,9 +1743,9 @@ 
         """Extension point for wrapping the dirstate per-repo."""
         sparsematchfn = lambda: sparse.matcher(self)
         v2_req = requirementsmod.DIRSTATE_V2_REQUIREMENT
-        tk = requirementsmod.DIRSTATE_TRACKED_KEY_V1
+        th = requirementsmod.DIRSTATE_TRACKED_HINT_V1
         use_dirstate_v2 = v2_req in self.requirements
-        use_tracked_key = tk in self.requirements
+        use_tracked_hint = th in self.requirements
 
         return dirstate.dirstate(
             self.vfs,
@@ -1755,7 +1755,7 @@ 
             sparsematchfn,
             self.nodeconstants,
             use_dirstate_v2,
-            use_tracked_key=use_tracked_key,
+            use_tracked_hint=use_tracked_hint,
         )
 
     def _dirstatevalidate(self, node):
@@ -3695,14 +3695,14 @@ 
         else:
             requirements.add(requirementsmod.SHARED_REQUIREMENT)
 
-    if ui.configbool(b'format', b'use-dirstate-tracked-key'):
-        version = ui.configint(b'format', b'use-dirstate-tracked-key.version')
+    if ui.configbool(b'format', b'use-dirstate-tracked-hint'):
+        version = ui.configint(b'format', b'use-dirstate-tracked-hint.version')
         msg = _("ignoring unknown tracked key version: %d\n")
-        hint = _("see `hg help config.format.use-dirstate-tracked-key-version")
+        hint = _("see `hg help config.format.use-dirstate-tracked-hint-version")
         if version != 1:
             ui.warn(msg % version, hint=hint)
         else:
-            requirements.add(requirementsmod.DIRSTATE_TRACKED_KEY_V1)
+            requirements.add(requirementsmod.DIRSTATE_TRACKED_HINT_V1)
 
     return requirements
 
diff --git a/mercurial/helptext/config.txt b/mercurial/helptext/config.txt
--- a/mercurial/helptext/config.txt
+++ b/mercurial/helptext/config.txt
@@ -944,38 +944,37 @@ 
 
     For a more comprehensive guide, see :hg:`help internals.dirstate-v2`.
 
-``use-dirstate-tracked-key``
+``use-dirstate-tracked-hint``
     Enable or disable the writing of "tracked key" file alongside the dirstate.
     (default to disabled)
 
-    That "tracked-key" can help external automations to detect changes to the
-    set of tracked files.
-
-    The tracked-key is written in a new `.hg/dirstate-tracked-key`. That file
+    That "tracked-hint" can help external automations to detect changes to the
+    set of tracked files. (i.e the result of `hg files` or `hg status -macd`)
+
+    The tracked-hint is written in a new `.hg/dirstate-tracked-hint`. That file
     contains two lines:
     - the first line is the file version (currently: 1),
-    - the second line contains the "tracked-key".
-
-    The tracked-key changes whenever the set of file tracked in the dirstate
-    changes. The general guarantees are:
-    - if the tracked key is identical, the set of tracked file MUST not have changed,
-    - if the tracked key is different, the set of tracked file MIGHT differ.
+    - the second line contains the "tracked-hint".
+    That file is writtent right after the dirstate is written.
+
+    The tracked-hint changes whenever the set of file tracked in the dirstate
+    changes. The general idea is:
+    - if the hint is identical, the set of tracked file SHOULD be identical,
+    - if the hint is different, the set of tracked file MIGHT be different.
+
+    The "identical" use a should is a `SHOULD` as the dirstate and the hint file
+    are two distinct files and therefore that cannot be read or write in an
+    atomic way. If the key is identical, nothing garantee that the dirstate is
+    not updated right after the hint file. This is considered a negligible
+    limitation for the intended usecase. It isi actually possible to prevent this race by
+    taking the repository lock during read operation.
 
     They are two "ways" to use this feature:
 
-    1) monitoring changes to the `.hg/dirstate-tracked-key`, if the file changes
+    1) monitoring changes to the `.hg/dirstate-tracked-hint`, if the file changes
     the tracked set might have changed.
 
-    2) storing the value and comparing it to a later value. Beware that it is
-    impossible to achieve atomic writing or reading of the two files involved
-    files (`.hg/dirstate` and `.hg/dirstate-tracked-key`). So it is needed to
-    read the `tracked-key` files twice: before and after reading the tracked
-    set. The `tracked-key` is only usable as a cache key if it had the same
-    value in both cases and must be discarded otherwise.
-
-    To enforce that the `tracked-key` value can be used race-free (with double
-    reading as explained in (2)), the `.hg/dirstate-tracked-key` is written
-    twice: before and after we change the associated `.hg/dirstate` file.
+    2) storing the value and comparing it to a later value.
 
 ``use-persistent-nodemap``
     Enable or disable the "persistent-nodemap" feature which improves
diff --git a/mercurial/dirstate.py b/mercurial/dirstate.py
--- a/mercurial/dirstate.py
+++ b/mercurial/dirstate.py
@@ -101,7 +101,7 @@ 
         sparsematchfn,
         nodeconstants,
         use_dirstate_v2,
-        use_tracked_key=False,
+        use_tracked_hint=False,
     ):
         """Create a new dirstate object.
 
@@ -110,7 +110,7 @@ 
         the dirstate.
         """
         self._use_dirstate_v2 = use_dirstate_v2
-        self._use_tracked_key = use_tracked_key
+        self._use_tracked_hint = use_tracked_hint
         self._nodeconstants = nodeconstants
         self._opener = opener
         self._validate = validate
@@ -127,7 +127,7 @@ 
         self._filecache = {}
         self._parentwriters = 0
         self._filename = b'dirstate'
-        self._filename_tk = b'dirstate-tracked-key'
+        self._filename_th = b'dirstate-tracked-hint'
         self._pendingfilename = b'%s.pending' % self._filename
         self._plchangecallbacks = {}
         self._origpl = None
@@ -721,17 +721,9 @@ 
         if not self._dirty:
             return
 
-        write_key = self._use_tracked_key and self._dirty_tracked_set
+        write_key = self._use_tracked_hint and self._dirty_tracked_set
         if tr:
             # delay writing in-memory changes out
-            if write_key:
-                tr.addfilegenerator(
-                    b'dirstate-0-key-pre',
-                    (self._filename_tk,),
-                    lambda f: self._write_tracked_key(tr, f),
-                    location=b'plain',
-                    post_finalize=True,
-                )
             tr.addfilegenerator(
                 b'dirstate-1-main',
                 (self._filename,),
@@ -742,33 +734,28 @@ 
             if write_key:
                 tr.addfilegenerator(
                     b'dirstate-2-key-post',
-                    (self._filename_tk,),
-                    lambda f: self._write_tracked_key(tr, f),
+                    (self._filename_th,),
+                    lambda f: self._write_tracked_hint(tr, f),
                     location=b'plain',
                     post_finalize=True,
                 )
             return
 
         file = lambda f: self._opener(f, b"w", atomictemp=True, checkambig=True)
-        if write_key:
-            # we change the key-file before changing the dirstate to make sure
-            # reading invalidate there cache before we start writing
-            with file(self._filename_tk) as f:
-                self._write_tracked_key(tr, f)
         with file(self._filename) as f:
             self._writedirstate(tr, f)
         if write_key:
             # we update the key-file after writing to make sure reader have a
             # key that match the newly written content
-            with file(self._filename_tk) as f:
-                self._write_tracked_key(tr, f)
+            with file(self._filename_th) as f:
+                self._write_tracked_hint(tr, f)
 
-    def delete_tracked_key(self):
-        """remove the tracked_key file
+    def delete_tracked_hint(self):
+        """remove the tracked_hint file
 
         To be used by format downgrad operation"""
-        self._opener.unlink(self._filename_tk)
-        self._use_tracked_key = False
+        self._opener.unlink(self._filename_th)
+        self._use_tracked_hint = False
 
     def addparentchangecallback(self, category, callback):
         """add a callback to be called when the wd parents are changed
@@ -793,7 +780,7 @@ 
         self._dirty = False
         self._dirty_tracked_set = False
 
-    def _write_tracked_key(self, tr, f):
+    def _write_tracked_hint(self, tr, f):
         key = node.hex(uuid.uuid4().bytes)
         f.write(b"1\n%s\n" % key)  # 1 is the format version
 
diff --git a/mercurial/configitems.py b/mercurial/configitems.py
--- a/mercurial/configitems.py
+++ b/mercurial/configitems.py
@@ -1279,13 +1279,13 @@ 
 )
 coreconfigitem(
     b'format',
-    b'use-dirstate-tracked-key',
+    b'use-dirstate-tracked-hint',
     default=False,
     experimental=True,
 )
 coreconfigitem(
     b'format',
-    b'use-dirstate-tracked-key.version',
+    b'use-dirstate-tracked-hint.version',
     default=1,
     experimental=True,
 )