Merge branch 'mm/remote-helpers-doc'

* mm/remote-helpers-doc:
Documentation/remote-helpers: document common use-case for private ref

diff --combined Documentation/gitremote-helpers.txt
index be7e224a03c4c5079342c3bbb23b39ad38ca9a5c,9ae36da7aa418c24a96defc41a4c29afe57faf8e..f1f4ca972791892126f757b2f697758e4e5fe26d
--- 1/Documentation/gitremote-helpers.txt
--- 2/Documentation/gitremote-helpers.txt
+++ b/Documentation/gitremote-helpers.txt
@@@ -120,11 -120,6 +120,11 @@@ connecting (see the 'connect' command u
  When choosing between 'push' and 'export', Git prefers 'push'.
  Other frontends may have some other order of preference.
  
 +'no-private-update'::
 +      When using the 'refspec' capability, git normally updates the
 +      private ref on successful push. This update is disabled when
 +      the remote-helper declares the capability 'no-private-update'.
 +
  
  Capabilities for Fetching
  ^^^^^^^^^^^^^^^^^^^^^^^^^
@@@ -148,10 -143,6 +148,10 @@@ Supported commands: 'list', 'fetch'
  +
  Supported commands: 'list', 'import'.
  
 +'check-connectivity'::
 +      Can guarantee that when a clone is requested, the received
 +      pack is self contained and is connected.
 +
  If a helper advertises 'connect', Git will use it if possible and
  fall back to another capability if the helper requests so when
  connecting (see the 'connect' command under COMMANDS).
@@@ -185,6 -176,12 +185,12 @@@ applicable refspec takes precedence.  T
  advertised with this capability must cover all refs reported by
  the list command.  If no 'refspec' capability is advertised,
  there is an implied `refspec *:*`.
+ +
+ When writing remote-helpers for decentralized version control
+ systems, it is advised to keep a local copy of the repository to
+ interact with, and to let the private namespace refs point to this
+ local repository, while the refs/remotes namespace is used to track
+ the remote repository.
  
  'bidi-import'::
        This modifies the 'import' capability.
@@@ -279,9 -276,6 +285,9 @@@ Optionally may output a 'lock <file>' l
  GIT_DIR/objects/pack which is keeping a pack until refs can be
  suitably updated.
  +
 +If option 'check-connectivity' is requested, the helper must output
 +'connectivity-ok' if the clone is self-contained and connected.
 ++
  Supported if the helper has the "fetch" capability.
  
  'push' +<src>:<dst>::
@@@ -428,9 -422,6 +434,9 @@@ set by Git if the remote helper has th
        must not rely on this option being set before
        connect request occurs.
  
 +'option check-connectivity' \{'true'|'false'\}::
 +      Request the helper to check connectivity of a clone.
 +
  SEE ALSO
  --------
  linkgit:git-remote[1]