1
0
Fork 0
mirror of https://github.com/git/git.git synced 2024-10-30 22:07:53 +01:00

git-remote-helpers.txt: document invocation before input format

In the distant past, the order things were documented was
'Invocation', 'Commands', 'Capabilities', ...

Then it was decided that before giving a list of Commands, there
should be an overall description of the 'Input format', which was
a wise decision. However, this description was put as the very
first thing, with the rationale that any implementor would want
to know that first.

However, it seems an implementor would actually first need to
know how the remote helper will be invoked, so moving
'Invocation' to the front again seems logical. Moreover, we now
don't switch from discussing the input format to the invocation
style and then back to input related stuff.

Signed-off-by: Max Horn <max@quendi.de>
Acked-by: Sverre Rabbelier <srabbelier@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Max Horn 2012-11-28 00:03:21 +01:00 committed by Junio C Hamano
parent b7973fbbc3
commit f829a9eae6

View file

@ -35,6 +35,37 @@ 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.
The 'GIT_DIR' environment variable is set up for the remote helper
and can be used to determine where to store additional data or from
which directory to invoke auxiliary git commands.
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.
INPUT FORMAT
------------
@ -173,37 +204,6 @@ advertised with this capability must cover all refs reported by
the list command. If no 'refspec' capability is advertised,
there is an implied `refspec *:*`.
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.
The 'GIT_DIR' environment variable is set up for the remote helper
and can be used to determine where to store additional data or from
which directory to invoke auxiliary git commands.
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
--------