summaryrefslogtreecommitdiff
path: root/Documentation/git-remote-helpers.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/git-remote-helpers.txt')
-rw-r--r--Documentation/git-remote-helpers.txt200
1 files changed, 200 insertions, 0 deletions
diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt
new file mode 100644
index 0000000000..1b5f61aa0b
--- /dev/null
+++ b/Documentation/git-remote-helpers.txt
@@ -0,0 +1,200 @@
+git-remote-helpers(1)
+=====================
+
+NAME
+----
+git-remote-helpers - Helper programs for interoperation with remote git
+
+SYNOPSIS
+--------
+'git remote-<transport>' <remote>
+
+DESCRIPTION
+-----------
+
+These programs are normally not used directly by end users, but are
+invoked by various git programs that interact with remote repositories
+when the repository they would operate on will be accessed using
+transport code not linked into the main git binary. Various particular
+helper programs will behave as documented here.
+
+COMMANDS
+--------
+
+Commands are given by the caller on the helper's standard input, one per line.
+
+'capabilities'::
+ Lists the capabilities of the helper, one per line, ending
+ with a blank line. Each capability may be preceded with '*'.
+ This marks them mandatory for git version using the remote
+ helper to understand (unknown mandatory capability is fatal
+ error).
+
+'list'::
+ Lists the refs, one per line, in the format "<value> <name>
+ [<attr> ...]". The value may be a hex sha1 hash, "@<dest>" for
+ a symref, or "?" to indicate that the helper could not get the
+ value of the ref. A space-separated list of attributes follows
+ the name; unrecognized attributes are ignored. After the
+ complete list, outputs a blank line.
++
+If 'push' is supported this may be called as 'list for-push'
+to obtain the current refs prior to sending one or more 'push'
+commands to the helper.
+
+'option' <name> <value>::
+ Set the transport helper option <name> to <value>. Outputs a
+ single line containing one of 'ok' (option successfully set),
+ 'unsupported' (option not recognized) or 'error <msg>'
+ (option <name> is supported but <value> is not correct
+ for it). Options should be set before other commands,
+ and may how those commands behave.
++
+Supported if the helper has the "option" capability.
+
+'fetch' <sha1> <name>::
+ Fetches the given object, writing the necessary objects
+ to the database. Fetch commands are sent in a batch, one
+ per line, and the batch is terminated with a blank line.
+ Outputs a single blank line when all fetch commands in the
+ same batch are complete. Only objects which were reported
+ in the ref list with a sha1 may be fetched this way.
++
+Optionally may output a 'lock <file>' line indicating a file under
+GIT_DIR/objects/pack which is keeping a pack until refs can be
+suitably updated.
++
+Supported if the helper has the "fetch" capability.
+
+'push' +<src>:<dst>::
+ Pushes the given <src> commit or branch locally to the
+ remote branch described by <dst>. A batch sequence of
+ one or more push commands is terminated with a blank line.
++
+Zero or more protocol options may be entered after the last 'push'
+command, before the batch's terminating blank line.
++
+When the push is complete, outputs one or more 'ok <dst>' or
+'error <dst> <why>?' lines to indicate success or failure of
+each pushed ref. The status report output is terminated by
+a blank line. The option field <why> may be quoted in a C
+style string if it contains an LF.
++
+Supported if the helper has the "push" capability.
+
+'import' <name>::
+ Produces a fast-import stream which imports the current value
+ of the named ref. It may additionally import other refs as
+ needed to construct the history efficiently. The script writes
+ to a helper-specific private namespace. The value of the named
+ ref should be written to a location in this namespace derived
+ by applying the refspecs from the "refspec" capability to the
+ name of the ref.
++
+Supported if the helper has the "import" capability.
+
+'connect' <service>::
+ Connects to given service. Standard input and standard output
+ of helper are connected to specified service (git prefix is
+ included in service name so e.g. fetching uses 'git-upload-pack'
+ as service) on remote side. Valid replies to this command are
+ empty line (connection established), 'fallback' (no smart
+ transport support, fall back to dumb transports) and just
+ exiting with error message printed (can't connect, don't
+ bother trying to fall back). After line feed terminating the
+ positive (empty) response, the output of service starts. After
+ the connection ends, the remote helper exits.
++
+Supported if the helper has the "connect" capability.
+
+If a fatal error occurs, the program writes the error message to
+stderr and exits. The caller should expect that a suitable error
+message has been printed if the child closes the connection without
+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'::
+ This helper supports the 'fetch' command.
+
+'option'::
+ This helper supports the option command.
+
+'push'::
+ This helper supports the 'push' command.
+
+'import'::
+ This helper supports the 'import' command.
+
+'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 "*:*"
+
+'connect'::
+ This helper supports the 'connect' command.
+
+REF LIST ATTRIBUTES
+-------------------
+
+'for-push'::
+ The caller wants to use the ref list to prepare push
+ commands. A helper might chose to acquire the ref list by
+ opening a different type of connection to the destination.
+
+'unchanged'::
+ This ref is unchanged since the last import or fetch, although
+ the helper cannot necessarily determine what value that produced.
+
+OPTIONS
+-------
+'option verbosity' <N>::
+ Change the level of messages displayed by the helper.
+ When N is 0 the end-user has asked the process to be
+ quiet, and the helper should produce only error output.
+ N of 1 is the default level of verbosity, higher values
+ of N correspond to the number of -v flags passed on the
+ command line.
+
+'option progress' \{'true'|'false'\}::
+ Enable (or disable) progress messages displayed by the
+ transport helper during a command.
+
+'option depth' <depth>::
+ Deepen the history of a shallow repository.
+
+'option followtags' \{'true'|'false'\}::
+ If enabled the helper should automatically fetch annotated
+ tag objects if the object the tag points at was transferred
+ during the fetch command. If the tag is not fetched by
+ the helper a second fetch command will usually be sent to
+ ask for the tag specifically. Some helpers may be able to
+ use this option to avoid a second network connection.
+
+'option dry-run' \{'true'|'false'\}:
+ If true, pretend the operation completed successfully,
+ but don't actually change any repository data. For most
+ helpers this only applies to the 'push', if supported.
+
+'option servpath <c-style-quoted-path>'::
+ Set service path (--upload-pack, --receive-pack etc.) for
+ next connect. Remote helper MAY support this option. Remote
+ helper MUST NOT rely on this option being set before
+ connect request occurs.
+
+Documentation
+-------------
+Documentation by Daniel Barkalow and Ilari Liusvaara
+
+GIT
+---
+Part of the linkgit:git[1] suite