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
This commit is contained in:
Junio C Hamano
commit
e49450327e
@ -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
|
||||
|
||||
30
Documentation/git-remote-testgit.txt
Normal file
30
Documentation/git-remote-testgit.txt
Normal file
@ -0,0 +1,30 @@
|
||||
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
|
||||
@ -1,5 +1,18 @@
|
||||
#!/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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user