From bd4a3d616894c009a4500395e016ee8f0d4751a6 Mon Sep 17 00:00:00 2001 From: John Keeping Date: Thu, 31 Jan 2013 21:59:50 +0000 Subject: Rename {git- => git}remote-helpers.txt When looking up a topic via "git help ", git-help prepends "git-" to topics that are the names of commands (either builtin or found on the path) and "git" (no hyphen) to any other topic name. "git-remote-helpers" is not the name of a command, so "git help remote-helpers" looks for "gitremote-helpers" and does not find it. Fix this by renaming "git-remote-helpers.txt" to "gitremote-helpers.txt". Signed-off-by: John Keeping Signed-off-by: Junio C Hamano --- Documentation/Makefile | 11 +- Documentation/git-remote-helpers.txt | 423 ---------------------------------- Documentation/git-remote-helpers.txto | 9 + Documentation/git-remote-testgit.txt | 2 +- Documentation/gitremote-helpers.txt | 423 ++++++++++++++++++++++++++++++++++ Documentation/urls.txt | 2 +- 6 files changed, 443 insertions(+), 427 deletions(-) delete mode 100644 Documentation/git-remote-helpers.txt create mode 100644 Documentation/git-remote-helpers.txto create mode 100644 Documentation/gitremote-helpers.txt (limited to 'Documentation') diff --git a/Documentation/Makefile b/Documentation/Makefile index 971977b8aa..3c538e3de7 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,7 +1,7 @@ MAN1_TXT= \ $(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \ $(wildcard git-*.txt)) \ - gitk.txt gitweb.txt git.txt + gitk.txt gitweb.txt git.txt gitremote-helpers.txt MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \ gitrepository-layout.txt gitweb.conf.txt MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \ @@ -13,7 +13,8 @@ MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT) MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT)) MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT)) -DOC_HTML=$(MAN_HTML) +OBSOLETE_HTML = git-remote-helpers.html +DOC_HTML=$(MAN_HTML) $(OBSOLETE_HTML) ARTICLES = howto-index ARTICLES += everyday @@ -261,6 +262,12 @@ $(MAN_HTML): %.html : %.txt asciidoc.conf $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \ mv $@+ $@ +$(OBSOLETE_HTML): %.html : %.txto asciidoc.conf + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b xhtml11 -f asciidoc.conf \ + $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \ + mv $@+ $@ + manpage-base-url.xsl: manpage-base-url.xsl.in sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@ diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt deleted file mode 100644 index 6d696e0f90..0000000000 --- a/Documentation/git-remote-helpers.txt +++ /dev/null @@ -1,423 +0,0 @@ -git-remote-helpers(1) -===================== - -NAME ----- -git-remote-helpers - Helper programs to interact with remote repositories - -SYNOPSIS --------- -[verse] -'git remote-' [] - -DESCRIPTION ------------ - -Remote helper programs are normally not used directly by end users, -but they are invoked by git when it needs to interact with remote -repositories git does not support natively. A given helper will -implement a subset of the capabilities documented here. When git -needs to interact with a repository using a remote helper, it spawns -the helper as an independent process, sends commands to the helper's -standard input, and expects results from the helper's standard -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 -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'. - -INVOCATION ----------- - -Remote helper programs are invoked with one or (optionally) two -arguments. The first argument specifies a remote repository as in git; -it is either the name of a configured remote or a URL. The second -argument specifies a URL; it is usually of the form -'://
', but any arbitrary string is possible. -The 'GIT_DIR' environment variable is set up for the remote helper -and can be used to determine where to store additional data or from -which directory to invoke auxiliary git commands. - -When git encounters a URL of the form '://
', where -'' is a protocol that it cannot handle natively, it -automatically invokes 'git remote-' with the full URL as -the second argument. If such a URL is encountered directly on the -command line, the first argument is the same as the second, and if it -is encountered in a configured remote, the first argument is the name -of that remote. - -A URL of the form '::
' explicitly instructs git to -invoke 'git remote-' with '
' as the second -argument. If such a URL is encountered directly on the command line, -the first argument is '
', and if it is encountered in a -configured remote, the first argument is the name of that remote. - -Additionally, when a configured remote has 'remote..vcs' set to -'', git explicitly invokes 'git remote-' with -'' as the first argument. If set, the second argument is -'remote..url'; otherwise, the second argument is omitted. - -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). - -In the following, we list all defined capabilities and for -each we list which commands a helper with that capability -must provide. - -Capabilities for Pushing -^^^^^^^^^^^^^^^^^^^^^^^^ -'connect':: - Can attempt to connect to 'git receive-pack' (for pushing), - 'git upload-pack', etc for communication using - git's native packfile protocol. This - requires a bidirectional, full-duplex connection. -+ -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'. - -'export':: - Can discover remote refs and push specified objects from a - fast-import stream to remote refs. -+ -Supported commands: 'list for-push', 'export'. - -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 'push' and 'export', git prefers 'push'. -Other frontends may have some other order of preference. - - -Capabilities for Fetching -^^^^^^^^^^^^^^^^^^^^^^^^^ -'connect':: - Can try to connect to 'git upload-pack' (for fetching), - 'git receive-pack', etc for communication using the - git's native packfile protocol. This - requires a bidirectional, full-duplex connection. -+ -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. - -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' :: - 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':: - 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' :: - This modifies the 'export' capability, instructing git to dump the - internal marks table to when complete. For details, - read up on '--export-marks=' in linkgit:git-fast-export[1]. - -'import-marks' :: - This modifies the 'export' capability, instructing git to load the - marks specified in before processing any input. For details, - read up on '--import-marks=' in linkgit:git-fast-export[1]. - - - - -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 preceded with '*', - which marks them mandatory for git versions using the remote - helper to understand. Any unknown mandatory capability is a - fatal error. -+ -Support for this command is mandatory. - -'list':: - Lists the refs, one per line, in the format " - [ ...]". The value may be a hex sha1 hash, "@" 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. The list ends - with a blank line. -+ -See REF LIST ATTRIBUTES for a list of currently defined attributes. -+ -Supported if the helper has the "fetch" or "import" capability. - -'list for-push':: - Similar to 'list', except that it is used if and only if - the caller wants to the resulting ref list to prepare - push commands. - A helper supporting both push and fetch can use this - to distinguish for which operation the output of 'list' - is going to be used, possibly reducing the amount - of work that needs to be performed. -+ -Supported if the helper has the "push" or "export" capability. - -'option' :: - Sets the transport helper option to . Outputs a - single line containing one of 'ok' (option successfully set), - 'unsupported' (option not recognized) or 'error ' - (option is supported but is not valid - for it). Options should be set before other commands, - and may influence the behavior of those commands. -+ -See OPTIONS for a list of currently defined options. -+ -Supported if the helper has the "option" capability. - -'fetch' :: - Fetches the given object, writing the necessary objects - to the database. Fetch commands are sent in a batch, one - per line, 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 output of 'list' with a sha1 may be fetched this way. -+ -Optionally may output a 'lock ' 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' +::: - Pushes the given local commit or branch to the - remote branch described by . A batch sequence of - 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. -+ -When the push is complete, outputs one or more 'ok ' or -'error ?' lines to indicate success or failure of -each pushed ref. The status report output is terminated by -a blank line. The option field may be quoted in a C -style string if it contains an LF. -+ -Supported if the helper has the "push" capability. - -'import' :: - 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. -+ -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. -+ -Note that if the 'bidi-import' capability is used the complete batch -sequence has to be buffered before starting to send data to fast-import -to prevent mixing of commands and fast-import responses on the helper's -stdin. -+ -Supported if the helper has the "import" capability. - -'export':: - Instructs the remote helper that any subsequent input is - part of a fast-import stream (generated by 'git fast-export') - containing objects which should be pushed to the remote. -+ -Especially useful for interoperability with a foreign versioning -system. -+ -The 'export-marks' and 'import-marks' capabilities, if specified, -affect this command in so far as they are passed on to 'git -fast-export', which then will load/store a table of marks for -local objects. This can be used to implement for incremental -operations. -+ -Supported if the helper has the "export" capability. - -'connect' :: - 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. - -REF LIST ATTRIBUTES -------------------- - -The 'list' command produces a list of refs in which each ref -may be followed by a list of attributes. The following ref list -attributes are defined. - -'unchanged':: - This ref is unchanged since the last import or fetch, although - the helper cannot necessarily determine what value that produced. - -OPTIONS -------- - -The following options are defined and (under suitable circumstances) -set by git if the remote helper has the 'option' capability. - -'option verbosity' :: - Changes the verbosity of messages displayed by the helper. - A value of 0 for means that processes operate - quietly, and the helper produces only error output. - 1 is the default level of verbosity, and higher values - of correspond to the number of -v flags passed on the - command line. - -'option progress' \{'true'|'false'\}:: - Enables (or disables) progress messages displayed by the - transport helper during a command. - -'option depth' :: - Deepens 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 ':: - Sets service path (--upload-pack, --receive-pack etc.) for - next connect. Remote helper may support this option, but - must not rely on this option being set before - connect request occurs. - -SEE ALSO --------- -linkgit:git-remote[1] - -linkgit:git-remote-testgit[1] - -GIT ---- -Part of the linkgit:git[1] suite diff --git a/Documentation/git-remote-helpers.txto b/Documentation/git-remote-helpers.txto new file mode 100644 index 0000000000..49233f5d26 --- /dev/null +++ b/Documentation/git-remote-helpers.txto @@ -0,0 +1,9 @@ +git-remote-helpers +================== + +This document has been moved to linkgit:gitremote-helpers[1]. + +Please let the owners of the referring site know so that they can update the +link you clicked to get here. + +Thanks. diff --git a/Documentation/git-remote-testgit.txt b/Documentation/git-remote-testgit.txt index 2a67d456a3..4c871b92e9 100644 --- a/Documentation/git-remote-testgit.txt +++ b/Documentation/git-remote-testgit.txt @@ -23,7 +23,7 @@ The best way to learn more is to read the comments and source code in SEE ALSO -------- -linkgit:git-remote-helpers[1] +linkgit:gitremote-helpers[1] GIT --- diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt new file mode 100644 index 0000000000..0f21367ca5 --- /dev/null +++ b/Documentation/gitremote-helpers.txt @@ -0,0 +1,423 @@ +gitremote-helpers(1) +==================== + +NAME +---- +gitremote-helpers - Helper programs to interact with remote repositories + +SYNOPSIS +-------- +[verse] +'git remote-' [] + +DESCRIPTION +----------- + +Remote helper programs are normally not used directly by end users, +but they are invoked by git when it needs to interact with remote +repositories git does not support natively. A given helper will +implement a subset of the capabilities documented here. When git +needs to interact with a repository using a remote helper, it spawns +the helper as an independent process, sends commands to the helper's +standard input, and expects results from the helper's standard +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 +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'. + +INVOCATION +---------- + +Remote helper programs are invoked with one or (optionally) two +arguments. The first argument specifies a remote repository as in git; +it is either the name of a configured remote or a URL. The second +argument specifies a URL; it is usually of the form +'://
', but any arbitrary string is possible. +The 'GIT_DIR' environment variable is set up for the remote helper +and can be used to determine where to store additional data or from +which directory to invoke auxiliary git commands. + +When git encounters a URL of the form '://
', where +'' is a protocol that it cannot handle natively, it +automatically invokes 'git remote-' with the full URL as +the second argument. If such a URL is encountered directly on the +command line, the first argument is the same as the second, and if it +is encountered in a configured remote, the first argument is the name +of that remote. + +A URL of the form '::
' explicitly instructs git to +invoke 'git remote-' with '
' as the second +argument. If such a URL is encountered directly on the command line, +the first argument is '
', and if it is encountered in a +configured remote, the first argument is the name of that remote. + +Additionally, when a configured remote has 'remote..vcs' set to +'', git explicitly invokes 'git remote-' with +'' as the first argument. If set, the second argument is +'remote..url'; otherwise, the second argument is omitted. + +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). + +In the following, we list all defined capabilities and for +each we list which commands a helper with that capability +must provide. + +Capabilities for Pushing +^^^^^^^^^^^^^^^^^^^^^^^^ +'connect':: + Can attempt to connect to 'git receive-pack' (for pushing), + 'git upload-pack', etc for communication using + git's native packfile protocol. This + requires a bidirectional, full-duplex connection. ++ +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'. + +'export':: + Can discover remote refs and push specified objects from a + fast-import stream to remote refs. ++ +Supported commands: 'list for-push', 'export'. + +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 'push' and 'export', git prefers 'push'. +Other frontends may have some other order of preference. + + +Capabilities for Fetching +^^^^^^^^^^^^^^^^^^^^^^^^^ +'connect':: + Can try to connect to 'git upload-pack' (for fetching), + 'git receive-pack', etc for communication using the + git's native packfile protocol. This + requires a bidirectional, full-duplex connection. ++ +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. + +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' :: + 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':: + 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' :: + This modifies the 'export' capability, instructing git to dump the + internal marks table to when complete. For details, + read up on '--export-marks=' in linkgit:git-fast-export[1]. + +'import-marks' :: + This modifies the 'export' capability, instructing git to load the + marks specified in before processing any input. For details, + read up on '--import-marks=' in linkgit:git-fast-export[1]. + + + + +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 preceded with '*', + which marks them mandatory for git versions using the remote + helper to understand. Any unknown mandatory capability is a + fatal error. ++ +Support for this command is mandatory. + +'list':: + Lists the refs, one per line, in the format " + [ ...]". The value may be a hex sha1 hash, "@" 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. The list ends + with a blank line. ++ +See REF LIST ATTRIBUTES for a list of currently defined attributes. ++ +Supported if the helper has the "fetch" or "import" capability. + +'list for-push':: + Similar to 'list', except that it is used if and only if + the caller wants to the resulting ref list to prepare + push commands. + A helper supporting both push and fetch can use this + to distinguish for which operation the output of 'list' + is going to be used, possibly reducing the amount + of work that needs to be performed. ++ +Supported if the helper has the "push" or "export" capability. + +'option' :: + Sets the transport helper option to . Outputs a + single line containing one of 'ok' (option successfully set), + 'unsupported' (option not recognized) or 'error ' + (option is supported but is not valid + for it). Options should be set before other commands, + and may influence the behavior of those commands. ++ +See OPTIONS for a list of currently defined options. ++ +Supported if the helper has the "option" capability. + +'fetch' :: + Fetches the given object, writing the necessary objects + to the database. Fetch commands are sent in a batch, one + per line, 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 output of 'list' with a sha1 may be fetched this way. ++ +Optionally may output a 'lock ' 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' +::: + Pushes the given local commit or branch to the + remote branch described by . A batch sequence of + 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. ++ +When the push is complete, outputs one or more 'ok ' or +'error ?' lines to indicate success or failure of +each pushed ref. The status report output is terminated by +a blank line. The option field may be quoted in a C +style string if it contains an LF. ++ +Supported if the helper has the "push" capability. + +'import' :: + 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. ++ +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. ++ +Note that if the 'bidi-import' capability is used the complete batch +sequence has to be buffered before starting to send data to fast-import +to prevent mixing of commands and fast-import responses on the helper's +stdin. ++ +Supported if the helper has the "import" capability. + +'export':: + Instructs the remote helper that any subsequent input is + part of a fast-import stream (generated by 'git fast-export') + containing objects which should be pushed to the remote. ++ +Especially useful for interoperability with a foreign versioning +system. ++ +The 'export-marks' and 'import-marks' capabilities, if specified, +affect this command in so far as they are passed on to 'git +fast-export', which then will load/store a table of marks for +local objects. This can be used to implement for incremental +operations. ++ +Supported if the helper has the "export" capability. + +'connect' :: + 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. + +REF LIST ATTRIBUTES +------------------- + +The 'list' command produces a list of refs in which each ref +may be followed by a list of attributes. The following ref list +attributes are defined. + +'unchanged':: + This ref is unchanged since the last import or fetch, although + the helper cannot necessarily determine what value that produced. + +OPTIONS +------- + +The following options are defined and (under suitable circumstances) +set by git if the remote helper has the 'option' capability. + +'option verbosity' :: + Changes the verbosity of messages displayed by the helper. + A value of 0 for means that processes operate + quietly, and the helper produces only error output. + 1 is the default level of verbosity, and higher values + of correspond to the number of -v flags passed on the + command line. + +'option progress' \{'true'|'false'\}:: + Enables (or disables) progress messages displayed by the + transport helper during a command. + +'option depth' :: + Deepens 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 ':: + Sets service path (--upload-pack, --receive-pack etc.) for + next connect. Remote helper may support this option, but + must not rely on this option being set before + connect request occurs. + +SEE ALSO +-------- +linkgit:git-remote[1] + +linkgit:git-remote-testgit[1] + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 1d15ee7e52..cea5462ff8 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -55,7 +55,7 @@ may be used: where
may be a path, a server and path, or an arbitrary URL-like string recognized by the specific remote helper being -invoked. See linkgit:git-remote-helpers[1] for details. +invoked. See linkgit:gitremote-helpers[1] for details. If there are a large number of similarly-named remote repositories and you want to use a different format for them (such that the URLs you -- cgit v1.2.1