aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2010-04-18 21:32:25 -0700
committerJunio C Hamano <gitster@pobox.com>2010-04-18 21:32:25 -0700
commit407a963cae2867e16a62dafbdfaf6f85301d4cd6 (patch)
tree11db96a7d857a5468133c70f408798f586b625c4
parentc4df50c2d8afed81e4c3170f51eff1d11dea1d94 (diff)
parentd43427d3d9134524d3ebbe176e30cea38f2a0818 (diff)
downloadgit-407a963cae2867e16a62dafbdfaf6f85301d4cd6.tar.gz
git-407a963cae2867e16a62dafbdfaf6f85301d4cd6.tar.xz
Merge branch 'rr/remote-helper-doc'
* rr/remote-helper-doc: Documentation/remote-helpers: Fix typos and improve language Fixup: Second argument may be any arbitrary string Documentation/remote-helpers: Add invocation section Documentation/urls: Rewrite to accomodate <transport>::<address> Documentation/remote-helpers: Rewrite description
-rw-r--r--Documentation/git-remote-helpers.txt118
-rw-r--r--Documentation/urls.txt59
2 files changed, 119 insertions, 58 deletions
diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt
index 1b5f61aa0..3a23477ce 100644
--- a/Documentation/git-remote-helpers.txt
+++ b/Documentation/git-remote-helpers.txt
@@ -3,20 +3,69 @@ 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
--------
-'git remote-<transport>' <remote>
+'git remote-<transport>' <repository> [<URL>]
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'.
+
+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; it is usually of the form
+'<transport>://<address>', but any arbitrary string is possible.
+
+When git encounters a URL of the form '<transport>://<address>', where
+'<transport>' is a protocol that it cannot handle natively, it
+automatically invokes 'git remote-<transport>' 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 '<transport>::<address>' explicitly instructs git to
+invoke 'git remote-<transport>' with '<address>' as the second
+argument. If such a URL is encountered directly on the command line,
+the first argument is '<address>', 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.<name>.vcs' set to
+'<transport>', git explicitly invokes 'git remote-<transport>' with
+'<name>' as the first argument. If set, the second argument is
+'remote.<name>.url'; otherwise, the second argument is omitted.
COMMANDS
--------
@@ -25,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).
@@ -35,27 +84,27 @@ Commands are given by the caller on the helper's standard input, one per line.
[<attr> ...]". The value may be a hex sha1 hash, "@<dest>" 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' <name> <value>::
- Set the transport helper option <name> to <value>. Outputs a
+ Sets the transport helper option <name> to <value>. Outputs a
single line containing one of 'ok' (option successfully set),
'unsupported' (option not recognized) or 'error <msg>'
- (option <name> is supported but <value> is not correct
+ (option <name> is supported but <value> 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' <sha1> <name>::
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.
@@ -67,7 +116,7 @@ suitably updated.
Supported if the helper has the "fetch" capability.
'push' +<src>:<dst>::
- Pushes the given <src> commit or branch locally to the
+ Pushes the given local <src> commit or branch to the
remote branch described by <dst>. A batch sequence of
one or more push commands is terminated with a blank line.
+
@@ -91,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' <service>::
@@ -119,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
@@ -140,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
-------------------
@@ -158,19 +202,19 @@ REF LIST ATTRIBUTES
OPTIONS
-------
'option verbosity' <N>::
- 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' <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
@@ -186,11 +230,15 @@ OPTIONS
helpers this only applies to the 'push', if supported.
'option servpath <c-style-quoted-path>'::
- 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
+--------
+linkgit:git-remote[1]
+
Documentation
-------------
Documentation by Daniel Barkalow and Ilari Liusvaara
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-<transport>' remote helper, if one
+exists. To explicitly request a remote helper, the following syntax
+may be used:
+
+- <transport>::<address>
+
+where <address> 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