]>
Commit | Line | Data |
---|---|---|
6eb996b5 DB |
1 | git-remote-helpers(1) |
2 | ===================== | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-remote-helpers - Helper programs for interoperation with remote git | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | 'git remote-<transport>' <remote> | |
11 | ||
12 | DESCRIPTION | |
13 | ----------- | |
14 | ||
15 | These programs are normally not used directly by end users, but are | |
16 | invoked by various git programs that interact with remote repositories | |
17 | when the repository they would operate on will be accessed using | |
18 | transport code not linked into the main git binary. Various particular | |
19 | helper programs will behave as documented here. | |
20 | ||
21 | COMMANDS | |
22 | -------- | |
23 | ||
24 | Commands are given by the caller on the helper's standard input, one per line. | |
25 | ||
26 | 'capabilities':: | |
27 | Lists the capabilities of the helper, one per line, ending | |
28ed5b35 IL |
28 | with a blank line. Each capability may be preceeded with '*'. |
29 | This marks them mandatory for git version using the remote | |
30 | helper to understand (unknown mandatory capability is fatal | |
31 | error). | |
6eb996b5 DB |
32 | |
33 | 'list':: | |
34 | Lists the refs, one per line, in the format "<value> <name> | |
35 | [<attr> ...]". The value may be a hex sha1 hash, "@<dest>" for | |
36 | a symref, or "?" to indicate that the helper could not get the | |
37 | value of the ref. A space-separated list of attributes follows | |
38 | the name; unrecognized attributes are ignored. After the | |
39 | complete list, outputs a blank line. | |
ae4efe19 SP |
40 | + |
41 | If 'push' is supported this may be called as 'list for-push' | |
42 | to obtain the current refs prior to sending one or more 'push' | |
43 | commands to the helper. | |
6eb996b5 | 44 | |
ef08ef9e SP |
45 | 'option' <name> <value>:: |
46 | Set the transport helper option <name> to <value>. Outputs a | |
47 | single line containing one of 'ok' (option successfully set), | |
48 | 'unsupported' (option not recognized) or 'error <msg>' | |
49 | (option <name> is supported but <value> is not correct | |
50 | for it). Options should be set before other commands, | |
51 | and may how those commands behave. | |
52 | + | |
53 | Supported if the helper has the "option" capability. | |
6eb996b5 DB |
54 | |
55 | 'fetch' <sha1> <name>:: | |
292ce46b SP |
56 | Fetches the given object, writing the necessary objects |
57 | to the database. Fetch commands are sent in a batch, one | |
58 | per line, and the batch is terminated with a blank line. | |
59 | Outputs a single blank line when all fetch commands in the | |
60 | same batch are complete. Only objects which were reported | |
61 | in the ref list with a sha1 may be fetched this way. | |
62 | + | |
63 | Optionally may output a 'lock <file>' line indicating a file under | |
64 | GIT_DIR/objects/pack which is keeping a pack until refs can be | |
65 | suitably updated. | |
6eb996b5 DB |
66 | + |
67 | Supported if the helper has the "fetch" capability. | |
68 | ||
ae4efe19 SP |
69 | 'push' +<src>:<dst>:: |
70 | Pushes the given <src> commit or branch locally to the | |
71 | remote branch described by <dst>. A batch sequence of | |
72 | one or more push commands is terminated with a blank line. | |
73 | + | |
74 | Zero or more protocol options may be entered after the last 'push' | |
75 | command, before the batch's terminating blank line. | |
76 | + | |
77 | When the push is complete, outputs one or more 'ok <dst>' or | |
78 | 'error <dst> <why>?' lines to indicate success or failure of | |
79 | each pushed ref. The status report output is terminated by | |
80 | a blank line. The option field <why> may be quoted in a C | |
81 | style string if it contains an LF. | |
82 | + | |
83 | Supported if the helper has the "push" capability. | |
84 | ||
e65e91ed DB |
85 | 'import' <name>:: |
86 | Produces a fast-import stream which imports the current value | |
87 | of the named ref. It may additionally import other refs as | |
72ff8943 DB |
88 | needed to construct the history efficiently. The script writes |
89 | to a helper-specific private namespace. The value of the named | |
90 | ref should be written to a location in this namespace derived | |
91 | by applying the refspecs from the "refspec" capability to the | |
92 | name of the ref. | |
e65e91ed DB |
93 | + |
94 | Supported if the helper has the "import" capability. | |
95 | ||
6eb996b5 DB |
96 | If a fatal error occurs, the program writes the error message to |
97 | stderr and exits. The caller should expect that a suitable error | |
98 | message has been printed if the child closes the connection without | |
99 | completing a valid response for the current command. | |
100 | ||
101 | Additional commands may be supported, as may be determined from | |
102 | capabilities reported by the helper. | |
103 | ||
104 | CAPABILITIES | |
105 | ------------ | |
106 | ||
107 | 'fetch':: | |
108 | This helper supports the 'fetch' command. | |
109 | ||
ef08ef9e SP |
110 | 'option':: |
111 | This helper supports the option command. | |
112 | ||
ae4efe19 SP |
113 | 'push':: |
114 | This helper supports the 'push' command. | |
115 | ||
e65e91ed DB |
116 | 'import':: |
117 | This helper supports the 'import' command. | |
118 | ||
72ff8943 DB |
119 | 'refspec' 'spec':: |
120 | When using the import command, expect the source ref to have | |
121 | been written to the destination ref. The earliest applicable | |
122 | refspec takes precedence. For example | |
123 | "refs/heads/*:refs/svn/origin/branches/*" means that, after an | |
124 | "import refs/heads/name", the script has written to | |
125 | refs/svn/origin/branches/name. If this capability is used at | |
126 | all, it must cover all refs reported by the list command; if | |
127 | it is not used, it is effectively "*:*" | |
128 | ||
6eb996b5 DB |
129 | REF LIST ATTRIBUTES |
130 | ------------------- | |
131 | ||
ae4efe19 SP |
132 | 'for-push':: |
133 | The caller wants to use the ref list to prepare push | |
134 | commands. A helper might chose to acquire the ref list by | |
135 | opening a different type of connection to the destination. | |
6eb996b5 | 136 | |
f8ec9167 DB |
137 | 'unchanged':: |
138 | This ref is unchanged since the last import or fetch, although | |
139 | the helper cannot necessarily determine what value that produced. | |
6eb996b5 | 140 | |
ef08ef9e SP |
141 | OPTIONS |
142 | ------- | |
143 | 'option verbosity' <N>:: | |
144 | Change the level of messages displayed by the helper. | |
145 | When N is 0 the end-user has asked the process to be | |
146 | quiet, and the helper should produce only error output. | |
147 | N of 1 is the default level of verbosity, higher values | |
148 | of N correspond to the number of -v flags passed on the | |
149 | command line. | |
150 | ||
151 | 'option progress' \{'true'|'false'\}:: | |
152 | Enable (or disable) progress messages displayed by the | |
153 | transport helper during a command. | |
154 | ||
155 | 'option depth' <depth>:: | |
156 | Deepen the history of a shallow repository. | |
157 | ||
158 | 'option followtags' \{'true'|'false'\}:: | |
159 | If enabled the helper should automatically fetch annotated | |
160 | tag objects if the object the tag points at was transferred | |
161 | during the fetch command. If the tag is not fetched by | |
162 | the helper a second fetch command will usually be sent to | |
163 | ask for the tag specifically. Some helpers may be able to | |
164 | use this option to avoid a second network connection. | |
165 | ||
ae4efe19 SP |
166 | 'option dry-run' \{'true'|'false'\}: |
167 | If true, pretend the operation completed successfully, | |
168 | but don't actually change any repository data. For most | |
169 | helpers this only applies to the 'push', if supported. | |
170 | ||
6eb996b5 DB |
171 | Documentation |
172 | ------------- | |
173 | Documentation by Daniel Barkalow. | |
174 | ||
175 | GIT | |
176 | --- | |
177 | Part of the linkgit:git[1] suite |