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

The current documentation mentions the private ref namespace, but does
not really explain why it can be useful.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt
index 0827f691396ba698d3976eba1eddedd9e7ff3e9e..9ae36da7aa418c24a96defc41a4c29afe57faf8e 100644 (file)
--- a/Documentation/gitremote-helpers.txt
+++ b/Documentation/gitremote-helpers.txt
@@ -176,6 +176,12 @@ applicable refspec takes precedence.  The left-hand of refspecs
 advertised with this capability must cover all refs reported by
 the list command.  If no 'refspec' capability is advertised,
 there is an implied `refspec *:*`.
 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.
 
 'bidi-import'::
        This modifies the 'import' capability.