Google Git
Sign in
chromium / external / gitster / git-htmldocs / 0706c80eb5150908b5a08c163848c7e9328923b4 / . / technical / api-run-command.html
blob: 346cb942c7f69eec6be588626d6549d7f74d0e7a [file] [log] [blame]
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]6<meta name="generator" content="AsciiDoc 8.2.5" />
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]7<style type="text/css">
8/* Debug borders */
9p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
10/*
11 border: 1px solid red;
12*/
13}
14
15body {
16 margin: 1em 5% 1em 5%;
17}
18
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]19a {
20 color: blue;
21 text-decoration: underline;
22}
23a:visited {
24 color: fuchsia;
25}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]26
27em {
28 font-style: italic;
29}
30
31strong {
32 font-weight: bold;
33}
34
35tt {
36 color: navy;
37}
38
39h1, h2, h3, h4, h5, h6 {
40 color: #527bbd;
41 font-family: sans-serif;
42 margin-top: 1.2em;
43 margin-bottom: 0.5em;
44 line-height: 1.3;
45}
46
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]47h1, h2, h3 {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]48 border-bottom: 2px solid silver;
49}
50h2 {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]51 padding-top: 0.5em;
52}
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]53h3 {
54 float: left;
55}
56h3 + * {
57 clear: left;
58}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]59
60div.sectionbody {
61 font-family: serif;
62 margin-left: 0;
63}
64
65hr {
66 border: 1px solid silver;
67}
68
69p {
70 margin-top: 0.5em;
71 margin-bottom: 0.5em;
72}
73
74pre {
75 padding: 0;
76 margin: 0;
77}
78
79span#author {
80 color: #527bbd;
81 font-family: sans-serif;
82 font-weight: bold;
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]83 font-size: 1.1em;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]84}
85span#email {
86}
87span#revision {
88 font-family: sans-serif;
89}
90
91div#footer {
92 font-family: sans-serif;
93 font-size: small;
94 border-top: 2px solid silver;
95 padding-top: 0.5em;
96 margin-top: 4.0em;
97}
98div#footer-text {
99 float: left;
100 padding-bottom: 0.5em;
101}
102div#footer-badges {
103 float: right;
104 padding-bottom: 0.5em;
105}
106
107div#preamble,
108div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
109div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
110div.admonitionblock {
111 margin-right: 10%;
112 margin-top: 1.5em;
113 margin-bottom: 1.5em;
114}
115div.admonitionblock {
116 margin-top: 2.5em;
117 margin-bottom: 2.5em;
118}
119
120div.content { /* Block element content. */
121 padding: 0;
122}
123
124/* Block element titles. */
125div.title, caption.title {
126 font-family: sans-serif;
127 font-weight: bold;
128 text-align: left;
129 margin-top: 1.0em;
130 margin-bottom: 0.5em;
131}
132div.title + * {
133 margin-top: 0;
134}
135
136td div.title:first-child {
137 margin-top: 0.0em;
138}
139div.content div.title:first-child {
140 margin-top: 0.0em;
141}
142div.content + div.title {
143 margin-top: 0.0em;
144}
145
146div.sidebarblock > div.content {
147 background: #ffffee;
148 border: 1px solid silver;
149 padding: 0.5em;
150}
151
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]152div.listingblock {
153 margin-right: 0%;
154}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]155div.listingblock > div.content {
156 border: 1px solid silver;
157 background: #f4f4f4;
158 padding: 0.5em;
159}
160
161div.quoteblock > div.content {
162 padding-left: 2.0em;
163}
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]164
165div.attribution {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]166 text-align: right;
167}
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]168div.verseblock + div.attribution {
169 text-align: left;
170}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]171
172div.admonitionblock .icon {
173 vertical-align: top;
174 font-size: 1.1em;
175 font-weight: bold;
176 text-decoration: underline;
177 color: #527bbd;
178 padding-right: 0.5em;
179}
180div.admonitionblock td.content {
181 padding-left: 0.5em;
182 border-left: 2px solid silver;
183}
184
185div.exampleblock > div.content {
186 border-left: 2px solid silver;
187 padding: 0.5em;
188}
189
190div.verseblock div.content {
191 white-space: pre;
192}
193
194div.imageblock div.content { padding-left: 0; }
195div.imageblock img { border: 1px solid silver; }
196span.image img { border-style: none; }
197
198dl {
199 margin-top: 0.8em;
200 margin-bottom: 0.8em;
201}
202dt {
203 margin-top: 0.5em;
204 margin-bottom: 0;
205 font-style: italic;
206}
207dd > *:first-child {
208 margin-top: 0;
209}
210
211ul, ol {
212 list-style-position: outside;
213}
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]214div.olist2 ol {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]215 list-style-type: lower-alpha;
216}
217
218div.tableblock > table {
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]219 border: 3px solid #527bbd;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]220}
221thead {
222 font-family: sans-serif;
223 font-weight: bold;
224}
225tfoot {
226 font-weight: bold;
227}
228
229div.hlist {
230 margin-top: 0.8em;
231 margin-bottom: 0.8em;
232}
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]233div.hlist td {
234 padding-bottom: 5px;
235}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]236td.hlist1 {
237 vertical-align: top;
238 font-style: italic;
239 padding-right: 0.8em;
240}
241td.hlist2 {
242 vertical-align: top;
243}
244
245@media print {
246 div#footer-badges { display: none; }
247}
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]248
249div#toctitle {
250 color: #527bbd;
251 font-family: sans-serif;
252 font-size: 1.1em;
253 font-weight: bold;
254 margin-top: 1.0em;
255 margin-bottom: 0.1em;
256}
257
258div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
259 margin-top: 0;
260 margin-bottom: 0;
261}
262div.toclevel2 {
263 margin-left: 2em;
264 font-size: 0.9em;
265}
266div.toclevel3 {
267 margin-left: 4em;
268 font-size: 0.9em;
269}
270div.toclevel4 {
271 margin-left: 6em;
272 font-size: 0.9em;
273}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]274/* Workarounds for IE6's broken and incomplete CSS2. */
275
276div.sidebar-content {
277 background: #ffffee;
278 border: 1px solid silver;
279 padding: 0.5em;
280}
281div.sidebar-title, div.image-title {
282 font-family: sans-serif;
283 font-weight: bold;
284 margin-top: 0.0em;
285 margin-bottom: 0.5em;
286}
287
288div.listingblock div.content {
289 border: 1px solid silver;
290 background: #f4f4f4;
291 padding: 0.5em;
292}
293
294div.quoteblock-content {
295 padding-left: 2.0em;
296}
297
298div.exampleblock-content {
299 border-left: 2px solid silver;
300 padding-left: 0.5em;
301}
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]302
303/* IE6 sets dynamically generated links as visited. */
304div#toc a:visited { color: blue; }
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]305</style>
306<title>run-command API</title>
307</head>
308<body>
309<div id="header">
310<h1>run-command API</h1>
311</div>
312<div id="preamble">
313<div class="sectionbody">
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]314<div class="para"><p>The run-command API offers a versatile tool to run sub-processes with
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]315redirected input and output as well as with a modified environment
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]316and an alternate current directory.</p></div>
317<div class="para"><p>A similar API offers the capability to run a function asynchronously,
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]318which is primarily used to capture the output that the function
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]319produces in the caller in order to process it.</p></div>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]320</div>
321</div>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]322<h2 id="_functions">Functions</h2>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]323<div class="sectionbody">
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]324<div class="vlist"><dl>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]325<dt>
326<tt>start_command</tt>
327</dt>
328<dd>
329<p>
330 Start a sub-process. Takes a pointer to a <tt>struct child_process</tt>
331 that specifies the details and returns pipe FDs (if requested).
332 See below for details.
333</p>
334</dd>
335<dt>
336<tt>finish_command</tt>
337</dt>
338<dd>
339<p>
340 Wait for the completion of a sub-process that was started with
341 start_command().
342</p>
343</dd>
344<dt>
345<tt>run_command</tt>
346</dt>
347<dd>
348<p>
349 A convenience function that encapsulates a sequence of
350 start_command() followed by finish_command(). Takes a pointer
351 to a <tt>struct child_process</tt> that specifies the details.
352</p>
353</dd>
354<dt>
Junio C Hamanoa476efa2008-10-10 15:31:42[diff] [blame]355<tt>run_command_v_opt</tt>, <tt>run_command_v_opt_cd_env</tt>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]356</dt>
357<dd>
358<p>
359 Convenience functions that encapsulate a sequence of
360 start_command() followed by finish_command(). The argument argv
361 specifies the program and its arguments. The argument opt is zero
362 or more of the flags <tt>RUN_COMMAND_NO_STDIN</tt>, <tt>RUN_GIT_CMD</tt>, or
363 <tt>RUN_COMMAND_STDOUT_TO_STDERR</tt> that correspond to the members
364 .no_stdin, .git_cmd, .stdout_to_stderr of <tt>struct child_process</tt>.
365 The argument dir corresponds the member .dir. The argument env
366 corresponds to the member .env.
367</p>
368</dd>
369<dt>
370<tt>start_async</tt>
371</dt>
372<dd>
373<p>
374 Run a function asynchronously. Takes a pointer to a <tt>struct
375 async</tt> that specifies the details and returns a pipe FD
376 from which the caller reads. See below for details.
377</p>
378</dd>
379<dt>
380<tt>finish_async</tt>
381</dt>
382<dd>
383<p>
Junio C Hamano4f1d8c42008-03-03 02:01:16[diff] [blame]384 Wait for the completion of an asynchronous function that was
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]385 started with start_async().
386</p>
387</dd>
Junio C Hamanocc0cb312009-01-22 03:38:50[diff] [blame]388<dt>
389<tt>run_hook</tt>
390</dt>
391<dd>
392<p>
393 Run a hook.
394 The first argument is a pathname to an index file, or NULL
395 if the hook uses the default index file or no index is needed.
396 The second argument is the name of the hook.
397 The further arguments correspond to the hook arguments.
398 The last argument has to be NULL to terminate the arguments list.
399 If the hook does not exist or is not executable, the return
400 value will be zero.
401 If it is executable, the hook will be executed and the exit
402 status of the hook is returned.
403 On execution, .stdout_to_stderr and .no_stdin will be set.
404 (See below.)
405</p>
406</dd>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]407</dl></div>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]408</div>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]409<h2 id="_data_structures">Data structures</h2>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]410<div class="sectionbody">
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]411<div class="ilist"><ul>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]412<li>
413<p>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]414<tt>struct child_process</tt>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]415</p>
416</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]417</ul></div>
418<div class="para"><p>This describes the arguments, redirections, and environment of a
419command to run in a sub-process.</p></div>
420<div class="para"><p>The caller:</p></div>
421<div class="olist"><ol>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]422<li>
423<p>
Junio C Hamano7562b872008-06-18 03:17:26[diff] [blame]424allocates and clears (memset(&amp;chld, 0, sizeof(chld));) a
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]425 struct child_process variable;
426</p>
427</li>
428<li>
429<p>
430initializes the members;
431</p>
432</li>
433<li>
434<p>
435calls start_command();
436</p>
437</li>
438<li>
439<p>
440processes the data;
441</p>
442</li>
443<li>
444<p>
445closes file descriptors (if necessary; see below);
446</p>
447</li>
448<li>
449<p>
450calls finish_command().
451</p>
452</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]453</ol></div>
454<div class="para"><p>The .argv member is set up as an array of string pointers (NULL
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]455terminated), of which .argv[0] is the program name to run (usually
456without a path). If the command to run is a git command, set argv[0] to
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]457the command name without the <em>git-</em> prefix and set .git_cmd = 1.</p></div>
458<div class="para"><p>The members .in, .out, .err are used to redirect stdin, stdout,
459stderr as follows:</p></div>
460<div class="olist"><ol>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]461<li>
462<p>
463Specify 0 to request no special redirection. No new file descriptor
464 is allocated. The child process simply inherits the channel from the
465 parent.
466</p>
467</li>
468<li>
469<p>
470Specify -1 to have a pipe allocated; start_command() replaces -1
471 by the pipe FD in the following way:
472</p>
473<div class="literalblock">
474<div class="content">
475<pre><tt>.in: Returns the writable pipe end into which the caller writes;
476 the readable end of the pipe becomes the child's stdin.</tt></pre>
477</div></div>
478<div class="literalblock">
479<div class="content">
480<pre><tt>.out, .err: Returns the readable pipe end from which the caller
481 reads; the writable end of the pipe end becomes child's
482 stdout/stderr.</tt></pre>
483</div></div>
484<div class="literalblock">
485<div class="content">
486<pre><tt>The caller of start_command() must close the so returned FDs
487after it has completed reading from/writing to it!</tt></pre>
488</div></div>
489</li>
490<li>
491<p>
492Specify a file descriptor &gt; 0 to be used by the child:
493</p>
494<div class="literalblock">
495<div class="content">
496<pre><tt>.in: The FD must be readable; it becomes child's stdin.
497.out: The FD must be writable; it becomes child's stdout.
498.err &gt; 0 is not supported.</tt></pre>
499</div></div>
500<div class="literalblock">
501<div class="content">
502<pre><tt>The specified FD is closed by start_command(), even if it fails to
503run the sub-process!</tt></pre>
504</div></div>
505</li>
506<li>
507<p>
508Special forms of redirection are available by setting these members
509 to 1:
510</p>
511<div class="literalblock">
512<div class="content">
513<pre><tt>.no_stdin, .no_stdout, .no_stderr: The respective channel is
514 redirected to /dev/null.</tt></pre>
515</div></div>
516<div class="literalblock">
517<div class="content">
Junio C Hamano86bcccc2008-03-08 09:33:55[diff] [blame]518<pre><tt>.stdout_to_stderr: stdout of the child is redirected to its
519 stderr. This happens after stderr is itself redirected.
520 So stdout will follow stderr to wherever it is
521 redirected.</tt></pre>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]522</div></div>
523</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]524</ol></div>
525<div class="para"><p>To modify the environment of the sub-process, specify an array of
526string pointers (NULL terminated) in .env:</p></div>
527<div class="olist"><ol>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]528<li>
529<p>
530If the string is of the form "VAR=value", i.e. it contains <em>=</em>
531 the variable is added to the child process's environment.
532</p>
533</li>
534<li>
535<p>
Junio C Hamano4f1d8c42008-03-03 02:01:16[diff] [blame]536If the string does not contain <em>=</em>, it names an environment
537 variable that will be removed from the child process's environment.
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]538</p>
539</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]540</ol></div>
541<div class="para"><p>To specify a new initial working directory for the sub-process,
542specify it in the .dir member.</p></div>
543<div class="ilist"><ul>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]544<li>
545<p>
546<tt>struct async</tt>
547</p>
548</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]549</ul></div>
550<div class="para"><p>This describes a function to run asynchronously, whose purpose is
551to produce output that the caller reads.</p></div>
552<div class="para"><p>The caller:</p></div>
553<div class="olist"><ol>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]554<li>
555<p>
Junio C Hamano7562b872008-06-18 03:17:26[diff] [blame]556allocates and clears (memset(&amp;asy, 0, sizeof(asy));) a
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]557 struct async variable;
558</p>
559</li>
560<li>
561<p>
562initializes .proc and .data;
563</p>
564</li>
565<li>
566<p>
567calls start_async();
568</p>
569</li>
570<li>
571<p>
572processes the data by reading from the fd in .out;
573</p>
574</li>
575<li>
576<p>
577closes .out;
578</p>
579</li>
580<li>
581<p>
582calls finish_async().
583</p>
584</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]585</ol></div>
586<div class="para"><p>The function pointer in .proc has the following signature:</p></div>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]587<div class="literalblock">
588<div class="content">
589<pre><tt>int proc(int fd, void *data);</tt></pre>
590</div></div>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]591<div class="olist"><ol>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]592<li>
593<p>
594fd specifies a writable file descriptor to which the function must
595 write the data that it produces. The function <strong>must</strong> close this
596 descriptor before it returns.
597</p>
598</li>
599<li>
600<p>
601data is the value that the caller has specified in the .data member
602 of struct async.
603</p>
604</li>
605<li>
606<p>
607The return value of the function is 0 on success and non-zero
608 on failure. If the function indicates failure, finish_async() will
609 report failure as well.
610</p>
611</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]612</ol></div>
613<div class="para"><p>There are serious restrictions on what the asynchronous function can do
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]614because this facility is implemented by a pipe to a forked process on
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]615UNIX, but by a thread in the same address space on Windows:</p></div>
616<div class="olist"><ol>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]617<li>
618<p>
619It cannot change the program's state (global variables, environment,
620 etc.) in a way that the caller notices; in other words, .out is the
621 only communication channel to the caller.
622</p>
623</li>
624<li>
625<p>
626It must not change the program's state that the caller of the
627 facility also uses.
628</p>
629</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]630</ol></div>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]631</div>
632<div id="footer">
633<div id="footer-text">
Junio C Hamanoa5ec8422009-02-14 08:21:52[diff] [blame]634Last updated 2009-02-14 08:18:56 UTC
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]635</div>
636</div>
637</body>
638</html>