From f829a9eae6adc7e1d02fa28787e43fccaf98c0cc Mon Sep 17 00:00:00 2001 From: Max Horn Date: Wed, 28 Nov 2012 00:03:21 +0100 Subject: [PATCH] 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 Acked-by: Sverre Rabbelier Signed-off-by: Junio C Hamano --- Documentation/git-remote-helpers.txt | 62 ++++++++++++++-------------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 5ce4cda8e7..9a7e5834e3 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -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 +'://
', 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 '://
', 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. + 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 -'://
', 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 '://
', 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 --------