Commit e4945032 authored by Junio C Hamano's avatar Junio C Hamano

Merge branch 'jn/remote-helpers-doc'

* jn/remote-helpers-doc:
  (short) documentation for the testgit remote helper
  Documentation/git-remote-helpers: explain how import works with multiple refs
  Documentation/remote-helpers: explain capabilities first
parents 2f9e2e75 9609dc9d
......@@ -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' <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' <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
----------
......@@ -122,7 +241,22 @@ Supported if the helper has the "fetch" capability.
'push' +<src>:<dst>::
Pushes the given local <src> commit or branch to the
remote branch described by <dst>. 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.
......@@ -147,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' <service>::
......@@ -171,26 +310,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
-------------------
......@@ -243,6 +362,8 @@ SEE ALSO
--------
linkgit:git-remote[1]
linkgit:git-remote-testgit[1]
GIT
---
Part of the linkgit:git[1] suite
git-remote-testgit(1)
=====================
NAME
----
git-remote-testgit - Example remote-helper
SYNOPSIS
--------
[verse]
git clone testgit::<source-repo> [<destination>]
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
#!/usr/bin/env python
# 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.
#
# This is a Git <-> Git importer/exporter, that simply uses git
# fast-import and git fast-export to consume and produce fast-import
# streams.
#
# To understand better the way things work, one can activate debug
# traces by setting (to any value) the environment variables
# GIT_TRANSPORT_HELPER_DEBUG and GIT_DEBUG_TESTGIT, to see messages
# from the transport-helper side, or from this example remote-helper.
# hashlib is only available in python >= 2.5
try:
import hashlib
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment