Skip to content

Commit e494503

Browse files
gitstergitster
committed
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
2 parents 2f9e2e7 + 9609dc9 commit e494503

File tree

3 files changed

+195
-31
lines changed

3 files changed

+195
-31
lines changed

‎Documentation/git-remote-helpers.txt

Lines changed: 152 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -24,22 +24,141 @@ output. Because a remote helper runs as an independent process from
2424
git, there is no need to re-link git to add a new helper, nor any
2525
need to link the helper with the implementation of git.
2626

27-
Every helper must support the "capabilities" command, which git will
28-
use to determine what other commands the helper will accept. Other
29-
commands generally concern facilities like discovering and updating
30-
remote refs, transporting objects between the object database and
31-
the remote repository, and updating the local object store.
32-
33-
Helpers supporting the 'fetch' capability can discover refs from the
34-
remote repository and transfer objects reachable from those refs to
35-
the local object store. Helpers supporting the 'push' capability can
36-
transfer local objects to the remote repository and update remote refs.
27+
Every helper must support the "capabilities" command, which git
28+
uses to determine what other commands the helper will accept. Those
29+
other commands can be used to discover and update remote refs,
30+
transport objects between the object database and the remote repository,
31+
and update the local object store.
3732

3833
Git comes with a "curl" family of remote helpers, that handle various
3934
transport protocols, such as 'git-remote-http', 'git-remote-https',
4035
'git-remote-ftp' and 'git-remote-ftps'. They implement the capabilities
4136
'fetch', 'option', and 'push'.
4237

38+
INPUT FORMAT
39+
------------
40+
41+
Git sends the remote helper a list of commands on standard input, one
42+
per line. The first command is always the 'capabilities' command, in
43+
response to which the remote helper must print a list of the
44+
capabilities it supports (see below) followed by a blank line. The
45+
response to the capabilities command determines what commands Git uses
46+
in the remainder of the command stream.
47+
48+
The command stream is terminated by a blank line. In some cases
49+
(indicated in the documentation of the relevant commands), this blank
50+
line is followed by a payload in some other protocol (e.g., the pack
51+
protocol), while in others it indicates the end of input.
52+
53+
Capabilities
54+
~~~~~~~~~~~~
55+
56+
Each remote helper is expected to support only a subset of commands.
57+
The operations a helper supports are declared to git in the response
58+
to the `capabilities` command (see COMMANDS, below).
59+
60+
'option'::
61+
For specifying settings like `verbosity` (how much output to
62+
write to stderr) and `depth` (how much history is wanted in the
63+
case of a shallow clone) that affect how other commands are
64+
carried out.
65+
66+
'connect'::
67+
For fetching and pushing using git's native packfile protocol
68+
that requires a bidirectional, full-duplex connection.
69+
70+
'push'::
71+
For listing remote refs and pushing specified objects from the
72+
local object store to remote refs.
73+
74+
'fetch'::
75+
For listing remote refs and fetching the associated history to
76+
the local object store.
77+
78+
'import'::
79+
For listing remote refs and fetching the associated history as
80+
a fast-import stream.
81+
82+
'refspec' <refspec>::
83+
This modifies the 'import' capability, allowing the produced
84+
fast-import stream to modify refs in a private namespace
85+
instead of writing to refs/heads or refs/remotes directly.
86+
It is recommended that all importers providing the 'import'
87+
capability use this.
88+
+
89+
A helper advertising the capability
90+
`refspec refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}`
91+
is saying that, when it is asked to `import refs/heads/topic`, the
92+
stream it outputs will update the `refs/svn/origin/branches/topic`
93+
ref.
94+
+
95+
This capability can be advertised multiple times. The first
96+
applicable refspec takes precedence. The left-hand of refspecs
97+
advertised with this capability must cover all refs reported by
98+
the list command. If no 'refspec' capability is advertised,
99+
there is an implied `refspec {asterisk}:{asterisk}`.
100+
101+
Capabilities for Pushing
102+
~~~~~~~~~~~~~~~~~~~~~~~~
103+
'connect'::
104+
Can attempt to connect to 'git receive-pack' (for pushing),
105+
'git upload-pack', etc for communication using the
106+
packfile protocol.
107+
+
108+
Supported commands: 'connect'.
109+
110+
'push'::
111+
Can discover remote refs and push local commits and the
112+
history leading up to them to new or existing remote refs.
113+
+
114+
Supported commands: 'list for-push', 'push'.
115+
116+
If a helper advertises both 'connect' and 'push', git will use
117+
'connect' if possible and fall back to 'push' if the helper requests
118+
so when connecting (see the 'connect' command under COMMANDS).
119+
120+
Capabilities for Fetching
121+
~~~~~~~~~~~~~~~~~~~~~~~~~
122+
'connect'::
123+
Can try to connect to 'git upload-pack' (for fetching),
124+
'git receive-pack', etc for communication using the
125+
packfile protocol.
126+
+
127+
Supported commands: 'connect'.
128+
129+
'fetch'::
130+
Can discover remote refs and transfer objects reachable from
131+
them to the local object store.
132+
+
133+
Supported commands: 'list', 'fetch'.
134+
135+
'import'::
136+
Can discover remote refs and output objects reachable from
137+
them as a stream in fast-import format.
138+
+
139+
Supported commands: 'list', 'import'.
140+
141+
If a helper advertises 'connect', git will use it if possible and
142+
fall back to another capability if the helper requests so when
143+
connecting (see the 'connect' command under COMMANDS).
144+
When choosing between 'fetch' and 'import', git prefers 'fetch'.
145+
Other frontends may have some other order of preference.
146+
147+
'refspec' <refspec>::
148+
This modifies the 'import' capability.
149+
+
150+
A helper advertising
151+
`refspec refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}`
152+
in its capabilities is saying that, when it handles
153+
`import refs/heads/topic`, the stream it outputs will update the
154+
`refs/svn/origin/branches/topic` ref.
155+
+
156+
This capability can be advertised multiple times. The first
157+
applicable refspec takes precedence. The left-hand of refspecs
158+
advertised with this capability must cover all refs reported by
159+
the list command. If no 'refspec' capability is advertised,
160+
there is an implied `refspec {asterisk}:{asterisk}`.
161+
43162
INVOCATION
44163
----------
45164

@@ -122,7 +241,22 @@ Supported if the helper has the "fetch" capability.
122241
'push' +<src>:<dst>::
123242
Pushes the given local <src> commit or branch to the
124243
remote branch described by <dst>. A batch sequence of
125-
one or more push commands is terminated with a blank line.
244+
one or more 'push' commands is terminated with a blank line
245+
(if there is only one reference to push, a single 'push' command
246+
is followed by a blank line). For example, the following would
247+
be two batches of 'push', the first asking the remote-helper
248+
to push the local ref 'master' to the remote ref 'master' and
249+
the local 'HEAD' to the remote 'branch', and the second
250+
asking to push ref 'foo' to ref 'bar' (forced update requested
251+
by the '+').
252+
+
253+
------------
254+
push refs/heads/master:refs/heads/master
255+
push HEAD:refs/heads/branch
256+
\n
257+
push +refs/heads/foo:refs/heads/bar
258+
\n
259+
------------
126260
+
127261
Zero or more protocol options may be entered after the last 'push'
128262
command, before the batch's terminating blank line.
@@ -147,6 +281,11 @@ Supported if the helper has the "push" capability.
147281
Especially useful for interoperability with a foreign versioning
148282
system.
149283
+
284+
Just like 'push', a batch sequence of one or more 'import' is
285+
terminated with a blank line. For each batch of 'import', the remote
286+
helper should produce a fast-import stream terminated by a 'done'
287+
command.
288+
+
150289
Supported if the helper has the "import" capability.
151290

152291
'connect' <service>::
@@ -171,26 +310,6 @@ completing a valid response for the current command.
171310
Additional commands may be supported, as may be determined from
172311
capabilities reported by the helper.
173312

174-
CAPABILITIES
175-
------------
176-
177-
'fetch'::
178-
'option'::
179-
'push'::
180-
'import'::
181-
'connect'::
182-
This helper supports the corresponding command with the same name.
183-
184-
'refspec' 'spec'::
185-
When using the import command, expect the source ref to have
186-
been written to the destination ref. The earliest applicable
187-
refspec takes precedence. For example
188-
"refs/heads/{asterisk}:refs/svn/origin/branches/{asterisk}" means
189-
that, after an "import refs/heads/name", the script has written to
190-
refs/svn/origin/branches/name. If this capability is used at
191-
all, it must cover all refs reported by the list command; if
192-
it is not used, it is effectively "{asterisk}:{asterisk}"
193-
194313
REF LIST ATTRIBUTES
195314
-------------------
196315

@@ -243,6 +362,8 @@ SEE ALSO
243362
--------
244363
linkgit:git-remote[1]
245364

365+
linkgit:git-remote-testgit[1]
366+
246367
GIT
247368
---
248369
Part of the linkgit:git[1] suite

‎Documentation/git-remote-testgit.txt

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
git-remote-testgit(1)
2+
=====================
3+
4+
NAME
5+
----
6+
git-remote-testgit - Example remote-helper
7+
8+
9+
SYNOPSIS
10+
--------
11+
[verse]
12+
git clone testgit::<source-repo> [<destination>]
13+
14+
DESCRIPTION
15+
-----------
16+
17+
This command is a simple remote-helper, that is used both as a
18+
testcase for the remote-helper functionality, and as an example to
19+
show remote-helper authors one possible implementation.
20+
21+
The best way to learn more is to read the comments and source code in
22+
'git-remote-testgit.py'.
23+
24+
SEE ALSO
25+
--------
26+
linkgit:git-remote-helpers[1]
27+
28+
GIT
29+
---
30+
Part of the linkgit:git[1] suite

‎git-remote-testgit.py

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,18 @@
11
#!/usr/bin/env python
22

3+
# This command is a simple remote-helper, that is used both as a
4+
# testcase for the remote-helper functionality, and as an example to
5+
# show remote-helper authors one possible implementation.
6+
#
7+
# This is a Git <-> Git importer/exporter, that simply uses git
8+
# fast-import and git fast-export to consume and produce fast-import
9+
# streams.
10+
#
11+
# To understand better the way things work, one can activate debug
12+
# traces by setting (to any value) the environment variables
13+
# GIT_TRANSPORT_HELPER_DEBUG and GIT_DEBUG_TESTGIT, to see messages
14+
# from the transport-helper side, or from this example remote-helper.
15+
316
# hashlib is only available in python >= 2.5
417
try:
518
import hashlib

0 commit comments

Comments
 (0)