--- a/mercurial/bookmarks.py	Fri Oct 15 03:28:28 2021 +0200
+++ b/mercurial/bookmarks.py	Fri Oct 15 03:49:05 2021 +0200
@@ -772,9 +772,11 @@
     return changed
 
 
-def updatefromremote(ui, repo, remotemarks, path, trfunc, explicit=()):
+def updatefromremote(
+    ui, repo, remotemarks, path, trfunc, explicit=(), mode=None
+):
     ui.debug(b"checking for updated bookmarks\n")
-    if ui.configbool(b'bookmarks', b'mirror'):
+    if mode == b'mirror':
         changed = mirroring_remote(ui, repo, remotemarks)
     else:
         changed = merging_from_remote(ui, repo, remotemarks, path, explicit)

--- a/mercurial/configitems.py	Fri Oct 15 03:28:28 2021 +0200
+++ b/mercurial/configitems.py	Fri Oct 15 03:49:05 2021 +0200
@@ -207,11 +207,6 @@
     b'pushing',
     default=list,
 )
-coreconfigitem(
-    b'bookmarks',
-    b'mirror',
-    default=False,
-)
 # bundle.mainreporoot: internal hack for bundlerepo
 coreconfigitem(
     b'bundle',

--- a/mercurial/exchange.py	Fri Oct 15 03:28:28 2021 +0200
+++ b/mercurial/exchange.py	Fri Oct 15 03:49:05 2021 +0200
@@ -2028,6 +2028,9 @@
     pullop.stepsdone.add(b'bookmarks')
     repo = pullop.repo
     remotebookmarks = pullop.remotebookmarks
+    bookmarks_mode = None
+    if pullop.remote_path is not None:
+        bookmarks_mode = pullop.remote_path.bookmarks_mode
     bookmod.updatefromremote(
         repo.ui,
         repo,
@@ -2035,6 +2038,7 @@
         pullop.remote.url(),
         pullop.gettransaction,
         explicit=pullop.explicitbookmarks,
+        mode=bookmarks_mode,
     )
 
 

--- a/mercurial/helptext/config.txt	Fri Oct 15 03:28:28 2021 +0200
+++ b/mercurial/helptext/config.txt	Fri Oct 15 03:49:05 2021 +0200
@@ -418,16 +418,6 @@
 If no suitable authentication entry is found, the user is prompted
 for credentials as usual if required by the remote.
 
-``bookmarks``
--------------
-
-Controls some aspect of bookmarks.
-
-``mirror``
-    When pulling, instead of merging local bookmarks and remote bookmarks,
-    replace local bookmarks by remote bookmarks. This is useful to replicate
-    a repository, or as an optimization. (default: False)
-
 ``cmdserver``
 -------------
 
@@ -1758,6 +1748,15 @@
    Revsets specifying bookmarks will not result in the bookmark being
    pushed.
 
+``bookmarks.mode``
+  How bookmark will be dealt during the exchange. It support the following value
+
+  - ``default``: the default behavior, local and remote bookmarks are "merged"
+    on push/pull.
+
+  - ``mirror``: when pulling, replace local bookmarks by remote bookmarks. This
+    is useful to replicate a repository, or as an optimization.
+
 The following special named paths exist:
 
 ``default``

--- a/mercurial/utils/urlutil.py	Fri Oct 15 03:28:28 2021 +0200
+++ b/mercurial/utils/urlutil.py	Fri Oct 15 03:49:05 2021 +0200
@@ -766,6 +766,27 @@
     return value
 
 
+SUPPORTED_BOOKMARKS_MODES = {
+    b'default',
+    b'mirror',
+}
+
+
+@pathsuboption(b'bookmarks.mode', b'bookmarks_mode')
+def bookmarks_mode_option(ui, path, value):
+    if value not in SUPPORTED_BOOKMARKS_MODES:
+        path_name = path.name
+        if path_name is None:
+            # this is an "anonymous" path, config comes from the global one
+            path_name = b'*'
+        msg = _(b'(paths.%s:bookmarks.mode has unknown value: "%s")\n')
+        msg %= (path_name, value)
+        ui.warn(msg)
+    if value == b'default':
+        value = None
+    return value
+
+
 @pathsuboption(b'multi-urls', b'multi_urls')
 def multiurls_pathoption(ui, path, value):
     res = stringutil.parsebool(value)

--- a/relnotes/next	Fri Oct 15 03:28:28 2021 +0200
+++ b/relnotes/next	Fri Oct 15 03:49:05 2021 +0200
@@ -1,6 +1,10 @@
 == New Features ==
   * `debugrebuildfncache` now has an option to rebuild only the index files
 
+  * a new `bookmarks.mode` path option have been introduced to control the
+    bookmark update strategy during exchange with a peer. See hg help paths for
+    details.
+
 
 == Default Format Change ==
 

--- a/tests/test-bookmarks-pushpull.t	Fri Oct 15 03:28:28 2021 +0200
+++ b/tests/test-bookmarks-pushpull.t	Fri Oct 15 03:49:05 2021 +0200
@@ -503,7 +503,7 @@
    * foobar                    1:9b140be10808
   $ cp .hg/bookmarks .hg/bookmarks.bak
   $ hg book -d X
-  $ hg pull ../a --config bookmarks.mirror=true
+  $ hg pull ../a --config 'paths.*:bookmarks.mode=mirror'
   pulling from ../a
   searching for changes
   no changes found

--- a/tests/test-help.t	Fri Oct 15 03:28:28 2021 +0200
+++ b/tests/test-help.t	Fri Oct 15 03:49:05 2021 +0200
@@ -1900,6 +1900,15 @@
          Revsets specifying bookmarks will not result in the bookmark being
          pushed.
   
+      "bookmarks.mode"
+        How bookmark will be dealt during the exchange. It support the following
+        value
+  
+        - "default": the default behavior, local and remote bookmarks are
+          "merged" on push/pull.
+        - "mirror": when pulling, replace local bookmarks by remote bookmarks.
+          This is useful to replicate a repository, or as an optimization.
+  
       The following special named paths exist:
   
       "default"