From b4fc8d6ac638723e4f4452752f8fb41efe1ec356 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Mon, 29 Aug 2011 22:56:08 -0500 Subject: Documentation/remote-helpers: explain capabilities first The current remote helper documentation is from the perspective of git, so to speak: it presents a full menu of commands for a person invoking a remote helper to choose from. In practice, that's less useful than it could be, since the daunted novice remote-helper author probably just wanted a list of commands needs to implement to get started. So preface the command list with an overview of each capability, its purpose, and what commands it requires. As a side effect, this makes it a little clearer that git doesn't choose arbitrary commands to run, even if the remote helper advertises all capabilities --- instead, there are well defined command sequences for various tasks. Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-remote-helpers.txt | 159 ++++++++++++++++++++++++++++------- 1 file changed, 129 insertions(+), 30 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 4f83dea5a3..760b1645fd 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -24,22 +24,141 @@ 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. +Every helper must support the "capabilities" command, which git +uses to determine what other commands the helper will accept. Those +other commands can be used to discover and update remote refs, +transport objects between the object database and the remote repository, +and update the local object store. 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'. +INPUT FORMAT +------------ + +Git sends the remote helper a list of commands on standard input, one +per line. The first command is always the 'capabilities' command, in +response to which the remote helper must print a list of the +capabilities it supports (see below) followed by a blank line. The +response to the capabilities command determines what commands Git uses +in the remainder of the command stream. + +The command stream is terminated by a blank line. In some cases +(indicated in the documentation of the relevant commands), this blank +line is followed by a payload in some other protocol (e.g., the pack +protocol), while in others it indicates the end of input. + +Capabilities +~~~~~~~~~~~~ + +Each remote helper is expected to support only a subset of commands. +The operations a helper supports are declared to git in the response +to the `capabilities` command (see COMMANDS, below). + +'option':: + For specifying settings like `verbosity` (how much output to + write to stderr) and `depth` (how much history is wanted in the + case of a shallow clone) that affect how other commands are + carried out. + +'connect':: + For fetching and pushing using git's native packfile protocol + that requires a bidirectional, full-duplex connection. + +'push':: + For listing remote refs and pushing specified objects from the + local object store to remote refs. + +'fetch':: + For listing remote refs and fetching the associated history to + the local object store. + +'import':: + For listing remote refs and fetching the associated history as + a fast-import stream. + +'refspec' :: + This modifies the 'import' capability, allowing the produced + fast-import stream to modify refs in a private namespace + instead of writing to refs/heads or refs/remotes directly. + It is recommended that all importers providing the 'import' + capability use this. ++ +A helper advertising the capability +`refspec refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}` +is saying that, when it is asked to `import refs/heads/topic`, the +stream it outputs will update the `refs/svn/origin/branches/topic` +ref. ++ +This capability can be advertised multiple times. The first +applicable refspec takes precedence. The left-hand of refspecs +advertised with this capability must cover all refs reported by +the list command. If no 'refspec' capability is advertised, +there is an implied `refspec {asterisk}:{asterisk}`. + +Capabilities for Pushing +~~~~~~~~~~~~~~~~~~~~~~~~ +'connect':: + Can attempt to connect to 'git receive-pack' (for pushing), + 'git upload-pack', etc for communication using the + packfile protocol. ++ +Supported commands: 'connect'. + +'push':: + Can discover remote refs and push local commits and the + history leading up to them to new or existing remote refs. ++ +Supported commands: 'list for-push', 'push'. + +If a helper advertises both 'connect' and 'push', git will use +'connect' if possible and fall back to 'push' if the helper requests +so when connecting (see the 'connect' command under COMMANDS). + +Capabilities for Fetching +~~~~~~~~~~~~~~~~~~~~~~~~~ +'connect':: + Can try to connect to 'git upload-pack' (for fetching), + 'git receive-pack', etc for communication using the + packfile protocol. ++ +Supported commands: 'connect'. + +'fetch':: + Can discover remote refs and transfer objects reachable from + them to the local object store. ++ +Supported commands: 'list', 'fetch'. + +'import':: + Can discover remote refs and output objects reachable from + them as a stream in fast-import format. ++ +Supported commands: 'list', 'import'. + +If a helper advertises 'connect', git will use it if possible and +fall back to another capability if the helper requests so when +connecting (see the 'connect' command under COMMANDS). +When choosing between 'fetch' and 'import', git prefers 'fetch'. +Other frontends may have some other order of preference. + +'refspec' :: + This modifies the 'import' capability. ++ +A helper advertising +`refspec refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}` +in its capabilities is saying that, when it handles +`import refs/heads/topic`, the stream it outputs will update the +`refs/svn/origin/branches/topic` ref. ++ +This capability can be advertised multiple times. The first +applicable refspec takes precedence. The left-hand of refspecs +advertised with this capability must cover all refs reported by +the list command. If no 'refspec' capability is advertised, +there is an implied `refspec {asterisk}:{asterisk}`. + INVOCATION ---------- @@ -171,26 +290,6 @@ completing a valid response for the current command. Additional commands may be supported, as may be determined from capabilities reported by the helper. -CAPABILITIES ------------- - -'fetch':: -'option':: -'push':: -'import':: -'connect':: - This helper supports the corresponding command with the same name. - -'refspec' 'spec':: - When using the import command, expect the source ref to have - been written to the destination ref. The earliest applicable - refspec takes precedence. For example - "refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}" means - that, after an "import refs/heads/name", the script has written to - refs/svn/origin/branches/name. If this capability is used at - all, it must cover all refs reported by the list command; if - it is not used, it is effectively "{asterisk}:{asterisk}" - REF LIST ATTRIBUTES ------------------- -- cgit v1.2.3 From 960e3114963dbb290c12f7a4d19c5776584d43ff Mon Sep 17 00:00:00 2001 From: Matthieu Moy Date: Thu, 1 Sep 2011 18:49:37 +0200 Subject: Documentation/git-remote-helpers: explain how import works with multiple refs This is important for two reasons: * when two "import" lines follow each other, only one "done" command should be issued in the fast-import stream, not one per "import". * The blank line terminating an import command should not be confused with the one terminating the sequence of commands. While we're there, illustrate the corresponding explanation for push batches with an example. Signed-off-by: Matthieu Moy Acked-by: Sverre Rabbelier Signed-off-by: Junio C Hamano --- Documentation/git-remote-helpers.txt | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 760b1645fd..526fc6abbd 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -241,7 +241,22 @@ Supported if the helper has the "fetch" capability. 'push' +::: 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. + one or more 'push' commands is terminated with a blank line + (if there is only one reference to push, a single 'push' command + is followed by a blank line). For example, the following would + be two batches of 'push', the first asking the remote-helper + to push the local ref 'master' to the remote ref 'master' and + the local 'HEAD' to the remote 'branch', and the second + asking to push ref 'foo' to ref 'bar' (forced update requested + by the '+'). ++ +------------ +push refs/heads/master:refs/heads/master +push HEAD:refs/heads/branch +\n +push +refs/heads/foo:refs/heads/bar +\n +------------ + Zero or more protocol options may be entered after the last 'push' command, before the batch's terminating blank line. @@ -266,6 +281,11 @@ Supported if the helper has the "push" capability. Especially useful for interoperability with a foreign versioning system. + +Just like 'push', a batch sequence of one or more 'import' is +terminated with a blank line. For each batch of 'import', the remote +helper should produce a fast-import stream terminated by a 'done' +command. ++ Supported if the helper has the "import" capability. 'connect' :: -- cgit v1.2.3 From 9609dc9ddcb1a79112eb45c88244cdbb622bd5bc Mon Sep 17 00:00:00 2001 From: Matthieu Moy Date: Thu, 1 Sep 2011 18:49:38 +0200 Subject: (short) documentation for the testgit remote helper While it's not a command meant to be used by actual users (hence, not mentionned in git(1)), this command is a very precious help for remote-helpers authors. The best place for such technical doc is the source code, but users may not find it without a link in a manpage. Signed-off-by: Matthieu Moy Acked-by: Sverre Rabbelier Signed-off-by: Junio C Hamano --- Documentation/git-remote-helpers.txt | 2 ++ Documentation/git-remote-testgit.txt | 30 ++++++++++++++++++++++++++++++ 2 files changed, 32 insertions(+) create mode 100644 Documentation/git-remote-testgit.txt (limited to 'Documentation') diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 526fc6abbd..674797cd83 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -362,6 +362,8 @@ SEE ALSO -------- linkgit:git-remote[1] +linkgit:git-remote-testgit[1] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-remote-testgit.txt b/Documentation/git-remote-testgit.txt new file mode 100644 index 0000000000..2a67d456a3 --- /dev/null +++ b/Documentation/git-remote-testgit.txt @@ -0,0 +1,30 @@ +git-remote-testgit(1) +===================== + +NAME +---- +git-remote-testgit - Example remote-helper + + +SYNOPSIS +-------- +[verse] +git clone testgit:: [] + +DESCRIPTION +----------- + +This command is a simple remote-helper, that is used both as a +testcase for the remote-helper functionality, and as an example to +show remote-helper authors one possible implementation. + +The best way to learn more is to read the comments and source code in +'git-remote-testgit.py'. + +SEE ALSO +-------- +linkgit:git-remote-helpers[1] + +GIT +--- +Part of the linkgit:git[1] suite -- cgit v1.2.3