mirror of
https://github.com/git/git
synced 2024-11-05 18:59:29 +00:00
fa8c097cc9
Signed-off-by: Ilari Liusvaara <ilari.liusvaara@elisanet.fi> Signed-off-by: Junio C Hamano <gitster@pobox.com>
200 lines
7 KiB
Text
200 lines
7 KiB
Text
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 preceeded 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
|