1git-remote-helpers(1) 2===================== 3 4NAME 5---- 6git-remote-helpers - Helper programs to interact with remote repositories 7 8SYNOPSIS 9-------- 10'git remote-<transport>' <repository> [<URL>] 11 12DESCRIPTION 13----------- 14 15Remote helper programs are normally not used directly by end users, 16but they are invoked by git when it needs to interact with remote 17repositories git does not support natively. A given helper will 18implement a subset of the capabilities documented here. When git 19needs to interact with a repository using a remote helper, it spawns 20the helper as an independent process, sends commands to the helper's 21standard input, and expects results from the helper's standard 22output. Because a remote helper runs as an independent process from 23git, there is no need to re-link git to add a new helper, nor any 24need to link the helper with the implementation of git. 25 26Every helper must support the "capabilities" command, which git will 27use to determine what other commands the helper will accept. Other 28commands generally concern facilities like discovering and updating 29remote refs, transporting objects between the object database and 30the remote repository, and updating the local object store. 31 32Helpers supporting the 'fetch' capability can discover refs from the 33remote repository and transfer objects reachable from those refs to 34the local object store. Helpers supporting the 'push' capability can 35transfer local objects to the remote repository and update remote refs. 36 37Git comes with a "curl" family of remote helpers, that handle various 38transport protocols, such as 'git-remote-http', 'git-remote-https', 39'git-remote-ftp' and 'git-remote-ftps'. They implement the capabilities 40'fetch', 'option', and 'push'. 41 42INVOCATION 43---------- 44 45Remote helper programs are invoked with one or (optionally) two 46arguments. The first argument specifies a remote repository as in git; 47it is either the name of a configured remote or a URL. The second 48argument specifies a URL; it is usually of the form 49'<transport>://<address>', but any arbitrary string is possible. 50 51When git encounters a URL of the form '<transport>://<address>', where 52'<transport>' is a protocol that it cannot handle natively, it 53automatically invokes 'git remote-<transport>' with the full URL as 54the second argument. If such a URL is encountered directly on the 55command line, the first argument is the same as the second, and if it 56is encountered in a configured remote, the first argument is the name 57of that remote. 58 59A URL of the form '<transport>::<address>' explicitly instructs git to 60invoke 'git remote-<transport>' with '<address>' as the second 61argument. If such a URL is encountered directly on the command line, 62the first argument is '<address>', and if it is encountered in a 63configured remote, the first argument is the name of that remote. 64 65Additionally, when a configured remote has 'remote.<name>.vcs' set to 66'<transport>', git explicitly invokes 'git remote-<transport>' with 67'<name>' as the first argument. If set, the second argument is 68'remote.<name>.url'; otherwise, the second argument is omitted. 69 70COMMANDS 71-------- 72 73Commands are given by the caller on the helper's standard input, one per line. 74 75'capabilities':: 76 Lists the capabilities of the helper, one per line, ending 77 with a blank line. Each capability may be preceded with '*', 78 which marks them mandatory for git version using the remote 79 helper to understand (unknown mandatory capability is fatal 80 error). 81 82'list':: 83 Lists the refs, one per line, in the format "<value> <name> 84 [<attr> ...]". The value may be a hex sha1 hash, "@<dest>" for 85 a symref, or "?" to indicate that the helper could not get the 86 value of the ref. A space-separated list of attributes follows 87 the name; unrecognized attributes are ignored. The list ends 88 with a blank line. 89+ 90If 'push' is supported this may be called as 'list for-push' 91to obtain the current refs prior to sending one or more 'push' 92commands to the helper. 93 94'option' <name> <value>:: 95 Sets the transport helper option <name> to <value>. Outputs a 96 single line containing one of 'ok' (option successfully set), 97 'unsupported' (option not recognized) or 'error <msg>' 98 (option <name> is supported but <value> is not valid 99 for it). Options should be set before other commands, 100 and may influence the behavior of those commands. 101+ 102Supported if the helper has the "option" capability. 103 104'fetch' <sha1> <name>:: 105 Fetches the given object, writing the necessary objects 106 to the database. Fetch commands are sent in a batch, one 107 per line, terminated with a blank line. 108 Outputs a single blank line when all fetch commands in the 109 same batch are complete. Only objects which were reported 110 in the ref list with a sha1 may be fetched this way. 111+ 112Optionally may output a 'lock <file>' line indicating a file under 113GIT_DIR/objects/pack which is keeping a pack until refs can be 114suitably updated. 115+ 116Supported if the helper has the "fetch" capability. 117 118'push' +<src>:<dst>:: 119 Pushes the given local <src> commit or branch to the 120 remote branch described by <dst>. A batch sequence of 121 one or more push commands is terminated with a blank line. 122+ 123Zero or more protocol options may be entered after the last 'push' 124command, before the batch's terminating blank line. 125+ 126When the push is complete, outputs one or more 'ok <dst>' or 127'error <dst> <why>?' lines to indicate success or failure of 128each pushed ref. The status report output is terminated by 129a blank line. The option field <why> may be quoted in a C 130style string if it contains an LF. 131+ 132Supported if the helper has the "push" capability. 133 134'import' <name>:: 135 Produces a fast-import stream which imports the current value 136 of the named ref. It may additionally import other refs as 137 needed to construct the history efficiently. The script writes 138 to a helper-specific private namespace. The value of the named 139 ref should be written to a location in this namespace derived 140 by applying the refspecs from the "refspec" capability to the 141 name of the ref. 142+ 143Especially useful for interoperability with a foreign versioning 144system. 145+ 146Supported if the helper has the "import" capability. 147 148'connect' <service>:: 149 Connects to given service. Standard input and standard output 150 of helper are connected to specified service (git prefix is 151 included in service name so e.g. fetching uses 'git-upload-pack' 152 as service) on remote side. Valid replies to this command are 153 empty line (connection established), 'fallback' (no smart 154 transport support, fall back to dumb transports) and just 155 exiting with error message printed (can't connect, don't 156 bother trying to fall back). After line feed terminating the 157 positive (empty) response, the output of service starts. After 158 the connection ends, the remote helper exits. 159+ 160Supported if the helper has the "connect" capability. 161 162If a fatal error occurs, the program writes the error message to 163stderr and exits. The caller should expect that a suitable error 164message has been printed if the child closes the connection without 165completing a valid response for the current command. 166 167Additional commands may be supported, as may be determined from 168capabilities reported by the helper. 169 170CAPABILITIES 171------------ 172 173'fetch':: 174'option':: 175'push':: 176'import':: 177'connect':: 178 This helper supports the corresponding command with the same name. 179 180'refspec' 'spec':: 181 When using the import command, expect the source ref to have 182 been written to the destination ref. The earliest applicable 183 refspec takes precedence. For example 184 "refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}" means 185 that, after an "import refs/heads/name", the script has written to 186 refs/svn/origin/branches/name. If this capability is used at 187 all, it must cover all refs reported by the list command; if 188 it is not used, it is effectively "{asterisk}:{asterisk}" 189 190REF LIST ATTRIBUTES 191------------------- 192 193'for-push':: 194 The caller wants to use the ref list to prepare push 195 commands. A helper might chose to acquire the ref list by 196 opening a different type of connection to the destination. 197 198'unchanged':: 199 This ref is unchanged since the last import or fetch, although 200 the helper cannot necessarily determine what value that produced. 201 202OPTIONS 203------- 204'option verbosity' <n>:: 205 Changes the verbosity of messages displayed by the helper. 206 A value of 0 for <n> means that processes operate 207 quietly, and the helper produces only error output. 208 1 is the default level of verbosity, and higher values 209 of <n> correspond to the number of -v flags passed on the 210 command line. 211 212'option progress' \{'true'|'false'\}:: 213 Enables (or disables) progress messages displayed by the 214 transport helper during a command. 215 216'option depth' <depth>:: 217 Deepens the history of a shallow repository. 218 219'option followtags' \{'true'|'false'\}:: 220 If enabled the helper should automatically fetch annotated 221 tag objects if the object the tag points at was transferred 222 during the fetch command. If the tag is not fetched by 223 the helper a second fetch command will usually be sent to 224 ask for the tag specifically. Some helpers may be able to 225 use this option to avoid a second network connection. 226 227'option dry-run' \{'true'|'false'\}: 228 If true, pretend the operation completed successfully, 229 but don't actually change any repository data. For most 230 helpers this only applies to the 'push', if supported. 231 232'option servpath <c-style-quoted-path>':: 233 Sets service path (--upload-pack, --receive-pack etc.) for 234 next connect. Remote helper may support this option, but 235 must not rely on this option being set before 236 connect request occurs. 237 238SEE ALSO 239-------- 240linkgit:git-remote[1] 241 242GIT 243--- 244Part of the linkgit:git[1] suite