git-remote-helpers.txt: rearrange description of capabilities
This also remove some duplication in the descriptions (e.g. refspec was explained twice with similar level of detail). Signed-off-by: Max Horn <max@quendi.de> Acked-by: Sverre Rabbelier <srabbelier@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>maint
parent
b20c457a39
commit
0673bb28d0
|
@ -88,81 +88,17 @@ Each remote helper is expected to support only a subset of commands.
|
||||||
The operations a helper supports are declared to git in the response
|
The operations a helper supports are declared to git in the response
|
||||||
to the `capabilities` command (see COMMANDS, below).
|
to the `capabilities` command (see COMMANDS, below).
|
||||||
|
|
||||||
'option'::
|
In the following, we list all defined capabilities and for
|
||||||
For specifying settings like `verbosity` (how much output to
|
each we list which commands a helper with that capability
|
||||||
write to stderr) and `depth` (how much history is wanted in the
|
must provide.
|
||||||
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.
|
|
||||||
|
|
||||||
'export'::
|
|
||||||
For listing remote refs and pushing specified objects from a
|
|
||||||
fast-import stream to remote refs.
|
|
||||||
|
|
||||||
'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/*:refs/svn/origin/branches/*`
|
|
||||||
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 *:*`.
|
|
||||||
|
|
||||||
'bidi-import'::
|
|
||||||
The fast-import commands 'cat-blob' and 'ls' can be used by remote-helpers
|
|
||||||
to retrieve information about blobs and trees that already exist in
|
|
||||||
fast-import's memory. This requires a channel from fast-import to the
|
|
||||||
remote-helper.
|
|
||||||
If it is advertised in addition to "import", git establishes a pipe from
|
|
||||||
fast-import to the remote-helper's stdin.
|
|
||||||
It follows that git and fast-import are both connected to the
|
|
||||||
remote-helper's stdin. Because git can send multiple commands to
|
|
||||||
the remote-helper it is required that helpers that use 'bidi-import'
|
|
||||||
buffer all 'import' commands of a batch before sending data to fast-import.
|
|
||||||
This is to prevent mixing commands and fast-import responses on the
|
|
||||||
helper's stdin.
|
|
||||||
|
|
||||||
'export-marks' <file>::
|
|
||||||
This modifies the 'export' capability, instructing git to dump the
|
|
||||||
internal marks table to <file> when complete. For details,
|
|
||||||
read up on '--export-marks=<file>' in linkgit:git-fast-export[1].
|
|
||||||
|
|
||||||
'import-marks' <file>::
|
|
||||||
This modifies the 'export' capability, instructing git to load the
|
|
||||||
marks specified in <file> before processing any input. For details,
|
|
||||||
read up on '--import-marks=<file>' in linkgit:git-fast-export[1].
|
|
||||||
|
|
||||||
Capabilities for Pushing
|
Capabilities for Pushing
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
'connect'::
|
'connect'::
|
||||||
Can attempt to connect to 'git receive-pack' (for pushing),
|
Can attempt to connect to 'git receive-pack' (for pushing),
|
||||||
'git upload-pack', etc for communication using the
|
'git upload-pack', etc for communication using
|
||||||
packfile protocol.
|
git's native packfile protocol. This
|
||||||
|
requires a bidirectional, full-duplex connection.
|
||||||
+
|
+
|
||||||
Supported commands: 'connect'.
|
Supported commands: 'connect'.
|
||||||
|
|
||||||
|
@ -186,11 +122,12 @@ Other frontends may have some other order of preference.
|
||||||
|
|
||||||
|
|
||||||
Capabilities for Fetching
|
Capabilities for Fetching
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
'connect'::
|
'connect'::
|
||||||
Can try to connect to 'git upload-pack' (for fetching),
|
Can try to connect to 'git upload-pack' (for fetching),
|
||||||
'git receive-pack', etc for communication using the
|
'git receive-pack', etc for communication using the
|
||||||
packfile protocol.
|
git's native packfile protocol. This
|
||||||
|
requires a bidirectional, full-duplex connection.
|
||||||
+
|
+
|
||||||
Supported commands: 'connect'.
|
Supported commands: 'connect'.
|
||||||
|
|
||||||
|
@ -212,14 +149,27 @@ connecting (see the 'connect' command under COMMANDS).
|
||||||
When choosing between 'fetch' and 'import', git prefers 'fetch'.
|
When choosing between 'fetch' and 'import', git prefers 'fetch'.
|
||||||
Other frontends may have some other order of preference.
|
Other frontends may have some other order of preference.
|
||||||
|
|
||||||
|
Miscellaneous capabilities
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
'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.
|
||||||
|
|
||||||
'refspec' <refspec>::
|
'refspec' <refspec>::
|
||||||
This modifies the 'import' capability.
|
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
|
A helper advertising the capability
|
||||||
`refspec refs/heads/*:refs/svn/origin/branches/*`
|
`refspec refs/heads/*:refs/svn/origin/branches/*`
|
||||||
in its capabilities is saying that, when it handles
|
is saying that, when it is asked to `import refs/heads/topic`, the
|
||||||
`import refs/heads/topic`, the stream it outputs will update the
|
stream it outputs will update the `refs/svn/origin/branches/topic`
|
||||||
`refs/svn/origin/branches/topic` ref.
|
ref.
|
||||||
+
|
+
|
||||||
This capability can be advertised multiple times. The first
|
This capability can be advertised multiple times. The first
|
||||||
applicable refspec takes precedence. The left-hand of refspecs
|
applicable refspec takes precedence. The left-hand of refspecs
|
||||||
|
@ -227,6 +177,34 @@ advertised with this capability must cover all refs reported by
|
||||||
the list command. If no 'refspec' capability is advertised,
|
the list command. If no 'refspec' capability is advertised,
|
||||||
there is an implied `refspec *:*`.
|
there is an implied `refspec *:*`.
|
||||||
|
|
||||||
|
'bidi-import'::
|
||||||
|
This modifies the 'import' capability.
|
||||||
|
The fast-import commands 'cat-blob' and 'ls' can be used by remote-helpers
|
||||||
|
to retrieve information about blobs and trees that already exist in
|
||||||
|
fast-import's memory. This requires a channel from fast-import to the
|
||||||
|
remote-helper.
|
||||||
|
If it is advertised in addition to "import", git establishes a pipe from
|
||||||
|
fast-import to the remote-helper's stdin.
|
||||||
|
It follows that git and fast-import are both connected to the
|
||||||
|
remote-helper's stdin. Because git can send multiple commands to
|
||||||
|
the remote-helper it is required that helpers that use 'bidi-import'
|
||||||
|
buffer all 'import' commands of a batch before sending data to fast-import.
|
||||||
|
This is to prevent mixing commands and fast-import responses on the
|
||||||
|
helper's stdin.
|
||||||
|
|
||||||
|
'export-marks' <file>::
|
||||||
|
This modifies the 'export' capability, instructing git to dump the
|
||||||
|
internal marks table to <file> when complete. For details,
|
||||||
|
read up on '--export-marks=<file>' in linkgit:git-fast-export[1].
|
||||||
|
|
||||||
|
'import-marks' <file>::
|
||||||
|
This modifies the 'export' capability, instructing git to load the
|
||||||
|
marks specified in <file> before processing any input. For details,
|
||||||
|
read up on '--import-marks=<file>' in linkgit:git-fast-export[1].
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
COMMANDS
|
COMMANDS
|
||||||
--------
|
--------
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue