From 00b84e9dbfa6fabbac971dd70bc5a44802b0c36e Mon Sep 17 00:00:00 2001 From: Ramkumar Ramachandra Date: Sun, 28 Mar 2010 23:33:50 +0530 Subject: [PATCH 1/5] 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 Reviewed-by: Jonathan Nieder Acked-by: Sverre Rabbelier Signed-off-by: Junio C Hamano --- Documentation/git-remote-helpers.txt | 33 +++++++++++++++++++++++----- 1 file changed, 27 insertions(+), 6 deletions(-) diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 1b5f61aa0..9d86c2679 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -3,7 +3,7 @@ git-remote-helpers(1) NAME ---- -git-remote-helpers - Helper programs for interoperation with remote git +git-remote-helpers - Helper programs to interact with remote repositories SYNOPSIS -------- @@ -12,11 +12,32 @@ SYNOPSIS DESCRIPTION ----------- -These programs are normally not used directly by end users, but are -invoked by various git programs that interact with remote repositories -when the repository they would operate on will be accessed using -transport code not linked into the main git binary. Various particular -helper programs will behave as documented here. +Remote helper programs are normally not used directly by end users, +but they are invoked by git when it needs to interact with remote +repositories git does not support natively. A given helper will +implement a subset of the capabilities documented here. When git +needs to interact with a repository using a remote helper, it spawns +the helper as an independent process, sends commands to the helper's +standard input, and expects results from the helper's standard +output. Because a remote helper runs as an independent process from +git, there is no need to re-link git to add a new helper, nor any +need to link the helper with the implementation of git. + +Every helper must support the "capabilities" command, which git will +use to determine what other commands the helper will accept. Other +commands generally concern facilities like discovering and updating +remote refs, transporting objects between the object database and +the remote repository, and updating the local object store. + +Helpers supporting the 'fetch' capability can discover refs from the +remote repository and transfer objects reachable from those refs to +the local object store. Helpers supporting the 'push' capability can +transfer local objects to the remote repository and update remote refs. + +Git comes with a "curl" family of remote helpers, that handle various +transport protocols, such as 'git-remote-http', 'git-remote-https', +'git-remote-ftp' and 'git-remote-ftps'. They implement the capabilities +'fetch', 'option', and 'push'. COMMANDS -------- From 5ce4f4e3bf9894ae5a00c7b4f0ba7ba6d953b008 Mon Sep 17 00:00:00 2001 From: Ramkumar Ramachandra Date: Tue, 6 Apr 2010 14:08:19 +0530 Subject: [PATCH 2/5] Documentation/urls: Rewrite to accomodate ::
Rewrite the first part of the document to explicitly show differences between the URLs that can be used with different transport protocols. Mention ::
format to explicitly invoke a remote helper. Signed-off-by: Ramkumar Ramachandra Reviewed-by: Jonathan Nieder Acked-by: Sverre Rabbelier Signed-off-by: Junio C Hamano --- Documentation/urls.txt | 59 ++++++++++++++++++++++++++---------------- 1 file changed, 36 insertions(+), 23 deletions(-) diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 459a394dc..1dcd1e7f1 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -1,44 +1,57 @@ GIT URLS[[URLS]] ---------------- -One of the following notations can be used -to name the remote repository: +In general, URLs contain information about the transport protocol, the +address of the remote server, and the path to the repository. +Depending on the transport protocol, some of this information may be +absent. + +Git natively supports ssh, git, http, https, ftp, ftps, and rsync +protocols. The following syntaxes may be used with them: -- rsync://host.xz/path/to/repo.git/ -- http://host.xz{startsb}:port{endsb}/path/to/repo.git/ -- https://host.xz{startsb}:port{endsb}/path/to/repo.git/ -- git://host.xz{startsb}:port{endsb}/path/to/repo.git/ -- git://host.xz{startsb}:port{endsb}/~user/path/to/repo.git/ - ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/ -- ssh://{startsb}user@{endsb}host.xz/path/to/repo.git/ -- ssh://{startsb}user@{endsb}host.xz/~user/path/to/repo.git/ -- ssh://{startsb}user@{endsb}host.xz/~/path/to/repo.git +- git://host.xz{startsb}:port{endsb}/path/to/repo.git/ +- http{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/ +- ftp{startsb}s{endsb}://host.xz{startsb}:port{endsb}/path/to/repo.git/ +- rsync://host.xz/path/to/repo.git/ -SSH is the default transport protocol over the network. You can -optionally specify which user to log-in as, and an alternate, -scp-like syntax is also supported. Both syntaxes support -username expansion, as does the native git protocol, but -only the former supports port specification. The following -three are identical to the last three above, respectively: +An alternative scp-like syntax may also be used with the ssh protocol: -- {startsb}user@{endsb}host.xz:/path/to/repo.git/ -- {startsb}user@{endsb}host.xz:~user/path/to/repo.git/ -- {startsb}user@{endsb}host.xz:path/to/repo.git +- {startsb}user@{endsb}host.xz:path/to/repo.git/ -To sync with a local directory, you can use: +The ssh and git protocols additionally support ~username expansion: + +- ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/~{startsb}user{endsb}/path/to/repo.git/ +- git://host.xz{startsb}:port{endsb}/~{startsb}user{endsb}/path/to/repo.git/ +- {startsb}user@{endsb}host.xz:/~{startsb}user{endsb}/path/to/repo.git/ + +For local respositories, also supported by git natively, the following +syntaxes may be used: - /path/to/repo.git/ - file:///path/to/repo.git/ ifndef::git-clone[] -They are mostly equivalent, except when cloning. See -linkgit:git-clone[1] for details. +These two syntaxes are mostly equivalent, except when cloning, when +the former implies --local option. See linkgit:git-clone[1] for +details. endif::git-clone[] ifdef::git-clone[] -They are equivalent, except the former implies --local option. +These two syntaxes are mostly equivalent, except the former implies +--local option. endif::git-clone[] +When git doesn't know how to handle a certain transport protocol, it +attempts to use the 'remote-' remote helper, if one +exists. To explicitly request a remote helper, the following syntax +may be used: + +- ::
+ +where
may be a path, a server and path, or an arbitrary +URL-like string recognized by the specific remote helper being +invoked. See linkgit:git-remote-helpers[1] for details. If there are a large number of similarly-named remote repositories and you want to use a different format for them (such that the URLs you From b6c8d2d663234a2383cbe4634de93ca03f4717e1 Mon Sep 17 00:00:00 2001 From: Ramkumar Ramachandra Date: Wed, 7 Apr 2010 11:14:41 +0530 Subject: [PATCH 3/5] Documentation/remote-helpers: Add invocation section Add an 'Invocation' section to specify what the command line arguments mean. Also include a link to git-remote in the 'See Also' section. Signed-off-by: Ramkumar Ramachandra Acked-by: Sverre Rabbelier Signed-off-by: Junio C Hamano --- Documentation/git-remote-helpers.txt | 35 +++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 9d86c2679..1b66f57b4 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -7,7 +7,7 @@ git-remote-helpers - Helper programs to interact with remote repositories SYNOPSIS -------- -'git remote-' +'git remote-' [] DESCRIPTION ----------- @@ -39,6 +39,35 @@ transport protocols, such as 'git-remote-http', 'git-remote-https', 'git-remote-ftp' and 'git-remote-ftps'. They implement the capabilities 'fetch', 'option', and 'push'. +INVOCATION +---------- + +Remote helper programs are invoked with one or (optionally) two +arguments. The first argument specifies a remote repository as in git; +it is either the name of a configured remote or a URL. The second +argument specifies a URL of the form '://
' or +'::
', where '
' may be an arbitrary +string. + +When git encounters a URL of the form '://
', where +'' is a protocol that it cannot handle natively, it +automatically invokes 'git remote-' with the full URL as +the second argument. If such a URL is encountered directly on the +command line, the first argument is the same as the second, and if it +is encountered in a configured remote, the first argument is the name +of that remote. + +A URL of the form '::
' explicitly instructs git to +invoke 'git remote-' with '
' as the second +argument. If such a URL is encountered directly on the command line, +the first argument is '
', and if it is encountered in a +configured remote, the first argument is the name of that remote. + +Additionally, when a configured remote has 'remote..vcs' set to +'', git explicitly invokes 'git remote-' with +'' as the first argument. If set, the second argument is +'remote..url'; otherwise, the second argument is omitted. + COMMANDS -------- @@ -212,6 +241,10 @@ OPTIONS helper MUST NOT rely on this option being set before connect request occurs. +SEE ALSO +-------- +linkgit:git-remote[1] + Documentation ------------- Documentation by Daniel Barkalow and Ilari Liusvaara From 272a36b67b0df4725f3e28f3302f45274b39012f Mon Sep 17 00:00:00 2001 From: Ramkumar Ramachandra Date: Sun, 18 Apr 2010 06:26:37 +0530 Subject: [PATCH 4/5] Fixup: Second argument may be any arbitrary string This is intended to be a fixup for commit ad466d1 in pu. As Jonathan Neider pointed out, the second argument may be any arbitrary string, and need not conform to any URL-like shape. Signed-off-by: Ramkumar Ramachandra Acked-by: Sverre Rabbelier Signed-off-by: Junio C Hamano --- Documentation/git-remote-helpers.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 1b66f57b4..2dd70031c 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -45,9 +45,8 @@ INVOCATION Remote helper programs are invoked with one or (optionally) two arguments. The first argument specifies a remote repository as in git; it is either the name of a configured remote or a URL. The second -argument specifies a URL of the form '://
' or -'::
', where '
' may be an arbitrary -string. +argument specifies a URL; it is usually of the form +'://
', but any arbitrary string is possible. When git encounters a URL of the form '://
', where '' is a protocol that it cannot handle natively, it From d43427d3d9134524d3ebbe176e30cea38f2a0818 Mon Sep 17 00:00:00 2001 From: Ramkumar Ramachandra Date: Sun, 18 Apr 2010 06:27:37 +0530 Subject: [PATCH 5/5] Documentation/remote-helpers: Fix typos and improve language Fix some typos and errors in grammar and tense. Signed-off-by: Ramkumar Ramachandra Acked-by: Sverre Rabbelier Signed-off-by: Junio C Hamano --- Documentation/git-remote-helpers.txt | 51 +++++++++++++--------------- 1 file changed, 23 insertions(+), 28 deletions(-) diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 2dd70031c..3a23477ce 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -74,8 +74,8 @@ Commands are given by the caller on the helper's standard input, one per line. 'capabilities':: Lists the capabilities of the helper, one per line, ending - with a blank line. Each capability may be preceded with '*'. - This marks them mandatory for git version using the remote + with a blank line. Each capability may be preceded with '*', + which marks them mandatory for git version using the remote helper to understand (unknown mandatory capability is fatal error). @@ -84,27 +84,27 @@ Commands are given by the caller on the helper's standard input, one per line. [ ...]". The value may be a hex sha1 hash, "@" for a symref, or "?" to indicate that the helper could not get the value of the ref. A space-separated list of attributes follows - the name; unrecognized attributes are ignored. After the - complete list, outputs a blank line. + the name; unrecognized attributes are ignored. The list ends + with a blank line. + If 'push' is supported this may be called as 'list for-push' to obtain the current refs prior to sending one or more 'push' commands to the helper. 'option' :: - Set the transport helper option to . Outputs a + Sets the transport helper option to . Outputs a single line containing one of 'ok' (option successfully set), 'unsupported' (option not recognized) or 'error ' - (option is supported but is not correct + (option is supported but is not valid for it). Options should be set before other commands, - and may how those commands behave. + and may influence the behavior of those commands. + Supported if the helper has the "option" capability. 'fetch' :: Fetches the given object, writing the necessary objects to the database. Fetch commands are sent in a batch, one - per line, and the batch is terminated with a blank line. + per line, terminated with a blank line. Outputs a single blank line when all fetch commands in the same batch are complete. Only objects which were reported in the ref list with a sha1 may be fetched this way. @@ -116,7 +116,7 @@ suitably updated. Supported if the helper has the "fetch" capability. 'push' +::: - Pushes the given commit or branch locally to the + Pushes the given local commit or branch to the remote branch described by . A batch sequence of one or more push commands is terminated with a blank line. + @@ -140,6 +140,9 @@ Supported if the helper has the "push" capability. by applying the refspecs from the "refspec" capability to the name of the ref. + +Especially useful for interoperability with a foreign versioning +system. ++ Supported if the helper has the "import" capability. 'connect' :: @@ -168,16 +171,11 @@ CAPABILITIES ------------ 'fetch':: - This helper supports the 'fetch' command. - 'option':: - This helper supports the option command. - 'push':: - This helper supports the 'push' command. - 'import':: - This helper supports the 'import' command. +'connect':: + This helper supports the corresponding command with the same name. 'refspec' 'spec':: When using the import command, expect the source ref to have @@ -189,9 +187,6 @@ CAPABILITIES all, it must cover all refs reported by the list command; if it is not used, it is effectively "*:*" -'connect':: - This helper supports the 'connect' command. - REF LIST ATTRIBUTES ------------------- @@ -207,19 +202,19 @@ REF LIST ATTRIBUTES OPTIONS ------- 'option verbosity' :: - Change the level of messages displayed by the helper. - When N is 0 the end-user has asked the process to be - quiet, and the helper should produce only error output. - N of 1 is the default level of verbosity, higher values + Changes the verbosity of messages displayed by the helper. + A value of 0 for N means that processes operate + quietly, and the helper produces only error output. + 1 is the default level of verbosity, and higher values of N correspond to the number of -v flags passed on the command line. 'option progress' \{'true'|'false'\}:: - Enable (or disable) progress messages displayed by the + Enables (or disables) progress messages displayed by the transport helper during a command. 'option depth' :: - Deepen the history of a shallow repository. + Deepens the history of a shallow repository. 'option followtags' \{'true'|'false'\}:: If enabled the helper should automatically fetch annotated @@ -235,9 +230,9 @@ OPTIONS helpers this only applies to the 'push', if supported. 'option servpath ':: - Set service path (--upload-pack, --receive-pack etc.) for - next connect. Remote helper MAY support this option. Remote - helper MUST NOT rely on this option being set before + Sets service path (--upload-pack, --receive-pack etc.) for + next connect. Remote helper may support this option, but + must not rely on this option being set before connect request occurs. SEE ALSO