Jonathan NiederThe 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 she 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 just 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 <jrnieder@gmail.com> --- No documentation for "export" and "gitdir" yet (by the way: would it make sense to export the GIT_DIR environment variable so a round trip for the 'gitdir' capability would eventually be unnecessary?).
The current documentation left me lost, so I wrote this (which still probably leaves one lost). Thoughts?
Documentation/git-remote-helpers.txt | 101 +++++++++++++++++++++++++-------- 1 files changed, 76 insertions(+), 25 deletions(-)
Show changes to Documentation/git-remote-helpers.txt +76 −24
diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt index 87cd11f..e7a3985 100644 --- a/Documentation/git-remote-helpers.txt +++ b/Documentation/git-remote-helpers.txt @@ -29,16 +29,87 @@ 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'. +CAPABILITIES +------------ + +Different remote helpers expect to communicate with git in different +ways. These are declared to git through the helper's response to the +`capabilities` command (see COMMANDS, below). + +'option':: + Can accept 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. ++ +Supported commands: 'option'. + +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' <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 ---------- @@ -167,26 +238,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/*:refs/svn/origin/branches/*" 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 "*:*" - REF LIST ATTRIBUTES -------------------
-- 1.7.4.1
