D9839: doc: improves the share-safe documentation

[marmoute (Pierre-Yves David)]

marmoute created this revision.
Herald added a reviewer: hg-reviewers.
Herald added a subscriber: mercurial-patches.

REVISION SUMMARY
  The associated behavior is now clearer and we point to the other configuration
  that control the mismatching behavior.

REPOSITORY
  rHG Mercurial

BRANCH
  default

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

AFFECTED FILES
  mercurial/helptext/config.txt

CHANGE DETAILS

diff --git a/mercurial/helptext/config.txt b/mercurial/helptext/config.txt
--- a/mercurial/helptext/config.txt
+++ b/mercurial/helptext/config.txt
@@ -913,8 +913,28 @@
     Disabled by default.
 
 ``use-share-safe``
-    Enable or disable the "share-safe" functionality, which enables shares
-    to read requirements and configuration of its source repository.
+    Enforce "safe" behaviors for all "share" that access this repository.
+
+    With this feature "share" using this repository as source will:
+
+    * read the source repositories configuration (`<source>/.hg/hgrc`)
+    * read and use the source repositories "requirements"
+      (except the working copy specific one.)
+
+    Without this feature, "share" using this repository as source will:
+
+    * keep tracking the repository "requirements" in the share only, ignoring
+      the source one, possibly diverging from them.
+    * ignore source repository config. This can create problem, like silently
+      ignoring important hooks
+
+    Beware that upgrading/downgrading a repository to use this feature will not
+    affect any of its share. The existing share will be upgraded and, by
+    default, Mercurial will refuse to interract with them until the mismatch is
+    resolve. See :hg:`help congfig share.safe-mismatch.source-safe` and
+    :hg:`help congfig share.safe-mismatch.source-not-safe` for details.
+
+    Introduced in Mercurial 5.7.
 
     Disabled by default.
 



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