diff mercurial/helptext/config.txt @ 49195:411d591e0a27

auto-upgrade: introduce a way to auto-upgrade to/from dirstate-v2

This is similar to what we introduced for `share-safe`, but apply to the
tracked-hint feature.

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

--- a/mercurial/helptext/config.txt	Tue Apr 05 05:20:05 2022 +0200
+++ b/mercurial/helptext/config.txt	Tue Mar 22 14:14:52 2022 +0100
@@ -944,6 +944,24 @@
 
     For a more comprehensive guide, see :hg:`help internals.dirstate-v2`.
 
+``use-dirstate-v2.automatic-upgrade-of-mismatching-repositories``
+   When enabled, an automatic upgrade will be triggered when a repository format
+   does not match its `use-dirstate-v2` config.
+
+   This is an advanced behavior that most users will not need. We recommend you
+   don't use this unless you are a seasoned administrator of a Mercurial install
+   base.
+
+   Automatic upgrade means that any process accessing the repository will
+   upgrade the repository format to use `dirstate-v2`. This only triggers if a
+   change is needed. This also applies to operations that would have been
+   read-only (like hg status).
+
+   This configuration will apply for moves in any direction, either adding the
+   `dirstate-v2` format if `format.use-dirstate-v2=yes` or removing the
+   `dirstate-v2` requirement if `format.use-dirstate-v2=no`. So we recommend
+   setting both this value and `format.use-dirstate-v2` at the same time.
+
 ``use-dirstate-tracked-hint``
     Enable or disable the writing of "tracked key" file alongside the dirstate.
     (default to disabled)