Google Git
Sign in
chromium / external / gitster / git-htmldocs / bc4852e8d68ccfc18b8d3c0cf4c3d602917d454a / . / technical / api-run-command.html
blob: e11cd5f18d0ae41ab11df78d035aa0a9f14870c2 [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 Hamano915cd9b2008-07-20 01:24:17[diff] [blame]388</dl></div>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]389</div>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]390<h2 id="_data_structures">Data structures</h2>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]391<div class="sectionbody">
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]392<div class="ilist"><ul>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]393<li>
394<p>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]395<tt>struct child_process</tt>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]396</p>
397</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]398</ul></div>
399<div class="para"><p>This describes the arguments, redirections, and environment of a
400command to run in a sub-process.</p></div>
401<div class="para"><p>The caller:</p></div>
402<div class="olist"><ol>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]403<li>
404<p>
Junio C Hamano7562b872008-06-18 03:17:26[diff] [blame]405allocates and clears (memset(&amp;chld, 0, sizeof(chld));) a
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]406 struct child_process variable;
407</p>
408</li>
409<li>
410<p>
411initializes the members;
412</p>
413</li>
414<li>
415<p>
416calls start_command();
417</p>
418</li>
419<li>
420<p>
421processes the data;
422</p>
423</li>
424<li>
425<p>
426closes file descriptors (if necessary; see below);
427</p>
428</li>
429<li>
430<p>
431calls finish_command().
432</p>
433</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]434</ol></div>
435<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]436terminated), of which .argv[0] is the program name to run (usually
437without 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]438the command name without the <em>git-</em> prefix and set .git_cmd = 1.</p></div>
439<div class="para"><p>The members .in, .out, .err are used to redirect stdin, stdout,
440stderr as follows:</p></div>
441<div class="olist"><ol>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]442<li>
443<p>
444Specify 0 to request no special redirection. No new file descriptor
445 is allocated. The child process simply inherits the channel from the
446 parent.
447</p>
448</li>
449<li>
450<p>
451Specify -1 to have a pipe allocated; start_command() replaces -1
452 by the pipe FD in the following way:
453</p>
454<div class="literalblock">
455<div class="content">
456<pre><tt>.in: Returns the writable pipe end into which the caller writes;
457 the readable end of the pipe becomes the child's stdin.</tt></pre>
458</div></div>
459<div class="literalblock">
460<div class="content">
461<pre><tt>.out, .err: Returns the readable pipe end from which the caller
462 reads; the writable end of the pipe end becomes child's
463 stdout/stderr.</tt></pre>
464</div></div>
465<div class="literalblock">
466<div class="content">
467<pre><tt>The caller of start_command() must close the so returned FDs
468after it has completed reading from/writing to it!</tt></pre>
469</div></div>
470</li>
471<li>
472<p>
473Specify a file descriptor &gt; 0 to be used by the child:
474</p>
475<div class="literalblock">
476<div class="content">
477<pre><tt>.in: The FD must be readable; it becomes child's stdin.
478.out: The FD must be writable; it becomes child's stdout.
479.err &gt; 0 is not supported.</tt></pre>
480</div></div>
481<div class="literalblock">
482<div class="content">
483<pre><tt>The specified FD is closed by start_command(), even if it fails to
484run the sub-process!</tt></pre>
485</div></div>
486</li>
487<li>
488<p>
489Special forms of redirection are available by setting these members
490 to 1:
491</p>
492<div class="literalblock">
493<div class="content">
494<pre><tt>.no_stdin, .no_stdout, .no_stderr: The respective channel is
495 redirected to /dev/null.</tt></pre>
496</div></div>
497<div class="literalblock">
498<div class="content">
Junio C Hamano86bcccc2008-03-08 09:33:55[diff] [blame]499<pre><tt>.stdout_to_stderr: stdout of the child is redirected to its
500 stderr. This happens after stderr is itself redirected.
501 So stdout will follow stderr to wherever it is
502 redirected.</tt></pre>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]503</div></div>
504</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]505</ol></div>
506<div class="para"><p>To modify the environment of the sub-process, specify an array of
507string pointers (NULL terminated) in .env:</p></div>
508<div class="olist"><ol>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]509<li>
510<p>
511If the string is of the form "VAR=value", i.e. it contains <em>=</em>
512 the variable is added to the child process's environment.
513</p>
514</li>
515<li>
516<p>
Junio C Hamano4f1d8c42008-03-03 02:01:16[diff] [blame]517If the string does not contain <em>=</em>, it names an environment
518 variable that will be removed from the child process's environment.
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]519</p>
520</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]521</ol></div>
522<div class="para"><p>To specify a new initial working directory for the sub-process,
523specify it in the .dir member.</p></div>
524<div class="ilist"><ul>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]525<li>
526<p>
527<tt>struct async</tt>
528</p>
529</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]530</ul></div>
531<div class="para"><p>This describes a function to run asynchronously, whose purpose is
532to produce output that the caller reads.</p></div>
533<div class="para"><p>The caller:</p></div>
534<div class="olist"><ol>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]535<li>
536<p>
Junio C Hamano7562b872008-06-18 03:17:26[diff] [blame]537allocates and clears (memset(&amp;asy, 0, sizeof(asy));) a
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]538 struct async variable;
539</p>
540</li>
541<li>
542<p>
543initializes .proc and .data;
544</p>
545</li>
546<li>
547<p>
548calls start_async();
549</p>
550</li>
551<li>
552<p>
553processes the data by reading from the fd in .out;
554</p>
555</li>
556<li>
557<p>
558closes .out;
559</p>
560</li>
561<li>
562<p>
563calls finish_async().
564</p>
565</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]566</ol></div>
567<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]568<div class="literalblock">
569<div class="content">
570<pre><tt>int proc(int fd, void *data);</tt></pre>
571</div></div>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]572<div class="olist"><ol>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]573<li>
574<p>
575fd specifies a writable file descriptor to which the function must
576 write the data that it produces. The function <strong>must</strong> close this
577 descriptor before it returns.
578</p>
579</li>
580<li>
581<p>
582data is the value that the caller has specified in the .data member
583 of struct async.
584</p>
585</li>
586<li>
587<p>
588The return value of the function is 0 on success and non-zero
589 on failure. If the function indicates failure, finish_async() will
590 report failure as well.
591</p>
592</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]593</ol></div>
594<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]595because this facility is implemented by a pipe to a forked process on
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]596UNIX, but by a thread in the same address space on Windows:</p></div>
597<div class="olist"><ol>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]598<li>
599<p>
600It cannot change the program's state (global variables, environment,
601 etc.) in a way that the caller notices; in other words, .out is the
602 only communication channel to the caller.
603</p>
604</li>
605<li>
606<p>
607It must not change the program's state that the caller of the
608 facility also uses.
609</p>
610</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]611</ol></div>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]612</div>
613<div id="footer">
614<div id="footer-text">
Junio C Hamanoec87f522008-12-10 08:35:25[diff] [blame]615Last updated 2008-12-10 08:33:40 UTC
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]616</div>
617</div>
618</body>
619</html>