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
This commit is contained in:
Junio C Hamano
commit
407a963cae
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user