Documentation/remote-helpers: Rewrite description
Rewrite the description section to describe what exactly remote helpers are and the need for them. Also mention the curl family of remote helpers as an example. [jc: with readability fixes from Jonathan squashed in] Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Acked-by: Sverre Rabbelier <srabbelier@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ramkumar Ramachandra committed
Mar 28, 2010 at 23:33 UTC
00b84e9dbfa6fabbac971dd70bc5a44802b0c36e
1 file changed
+27
-6
Documentation/git-remote-helpers.txt
+27
-6
@@ -3,7 +3,7 @@ git-remote-helpers(1)
3
4
NAME
5
----
6
-git-remote-helpers - Helper programs for interoperation with remote git
6
+git-remote-helpers - Helper programs to interact with remote repositories
7
8
SYNOPSIS
9
--------
@@ -12,11 +12,32 @@ SYNOPSIS
12
DESCRIPTION
13
-----------
14
15
-These programs are normally not used directly by end users, but are
16
-invoked by various git programs that interact with remote repositories
17
-when the repository they would operate on will be accessed using
18
-transport code not linked into the main git binary. Various particular
19
-helper programs will behave as documented here.
15
+Remote helper programs are normally not used directly by end users,
16
+but they are invoked by git when it needs to interact with remote
17
+repositories git does not support natively. A given helper will
18
+implement a subset of the capabilities documented here. When git
19
+needs to interact with a repository using a remote helper, it spawns
20
+the helper as an independent process, sends commands to the helper's
21
+standard input, and expects results from the helper's standard
22
+output. Because a remote helper runs as an independent process from
23
+git, there is no need to re-link git to add a new helper, nor any
24
+need to link the helper with the implementation of git.
25
+
26
+Every helper must support the "capabilities" command, which git will
27
+use to determine what other commands the helper will accept. Other
28
+commands generally concern facilities like discovering and updating
29
+remote refs, transporting objects between the object database and
30
+the remote repository, and updating the local object store.
31
+
32
+Helpers supporting the 'fetch' capability can discover refs from the
33
+remote repository and transfer objects reachable from those refs to
34
+the local object store. Helpers supporting the 'push' capability can
35
+transfer local objects to the remote repository and update remote refs.
36
+
37
+Git comes with a "curl" family of remote helpers, that handle various
38
+transport protocols, such as 'git-remote-http', 'git-remote-https',
39
+'git-remote-ftp' and 'git-remote-ftps'. They implement the capabilities
40
+'fetch', 'option', and 'push'.
41
42
COMMANDS
43
--------