diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/RelNotes-1.5.4.3.txt | 27 | ||||
| -rw-r--r-- | Documentation/config.txt | 13 | ||||
| -rw-r--r-- | Documentation/git-add.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-am.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-bundle.txt | 44 | ||||
| -rw-r--r-- | Documentation/git-describe.txt | 5 | ||||
| -rw-r--r-- | Documentation/git-filter-branch.txt | 15 | ||||
| -rw-r--r-- | Documentation/git-grep.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-merge-index.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-pack-objects.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-pull.txt | 20 | ||||
| -rw-r--r-- | Documentation/git-push.txt | 55 | ||||
| -rw-r--r-- | Documentation/git-rev-list.txt | 1 | ||||
| -rw-r--r-- | Documentation/git-stash.txt | 5 | ||||
| -rw-r--r-- | Documentation/git.txt | 3 | ||||
| -rw-r--r-- | Documentation/rev-list-options.txt | 5 | ||||
| -rw-r--r-- | Documentation/technical/api-remote.txt | 123 | ||||
| -rw-r--r-- | Documentation/technical/api-run-command.txt | 171 |
18 files changed, 467 insertions, 34 deletions
diff --git a/Documentation/RelNotes-1.5.4.3.txt b/Documentation/RelNotes-1.5.4.3.txt new file mode 100644 index 0000000000..b0fc67fb2a --- /dev/null +++ b/Documentation/RelNotes-1.5.4.3.txt @@ -0,0 +1,27 @@ +GIT v1.5.4.3 Release Notes +========================== + +Fixes since v1.5.4.2 +-------------------- + + * RPM spec used to pull in everything with 'git'. This has been + changed so that 'git' package contains just the core parts, + and we now supply 'git-all' metapackage to slurp in everything. + This should match end user's expectation better. + + * When some refs failed to update, git-push reported "failure" + which was unclear if some other refs were updated or all of + them failed atomically (the answer is the former). Reworded + the message to clarify this. + + * "git clone" from a repository whose HEAD was misconfigured + did not set up the remote properly. Now it tries to do + better. + + * Updated git-push documentation to clarify what "matching" + means, in order to reduce user confusion. + + * Updated git-add documentation to clarify "add -u" operates in + the current subdirectory you are in, just like other commands. + + * git-gui updates to work on OSX and Windows better. diff --git a/Documentation/config.txt b/Documentation/config.txt index 57b9b99863..8e361a1e77 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -353,6 +353,10 @@ core.whitespace:: error (enabled by default). * `indent-with-non-tab` treats a line that is indented with 8 or more space characters as an error (not enabled by default). +* `cr-at-eol` treats a carriage-return at the end of line as + part of the line terminator, i.e. with it, `trailing-space` + does not trigger if the character before such a carriage-return + is not a whitespace (not enabled by default). alias.*:: Command aliases for the linkgit:git[1] command wrapper - e.g. @@ -489,6 +493,13 @@ color.status.<slot>:: commit.template:: Specify a file to use as the template for new commit messages. +color.ui:: + When set to `always`, always use colors in all git commands which + are capable of colored output. When false (or `never`), never. When + set to `true` or `auto`, use colors only when the output is to the + terminal. When more specific variables of color.* are set, they always + take precedence over this setting. Defaults to false. + diff.autorefreshindex:: When using `git diff` to compare with work tree files, do not consider stat-only change as changed. @@ -801,6 +812,8 @@ pack.threads:: warning. This is meant to reduce packing time on multiprocessor machines. The required amount of memory for the delta search window is however multiplied by the number of threads. + Specifying 0 will cause git to auto-detect the number of CPU's + and set the number of threads accordingly. pack.indexVersion:: Specify the default pack index version. Valid values are 1 for diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 9d2ac865d2..47799097ce 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -74,8 +74,8 @@ OPTIONS Update only files that git already knows about. This is similar to what "git commit -a" does in preparation for making a commit, except that the update is limited to paths specified on the - command line. If no paths are specified, all tracked files are - updated. + command line. If no paths are specified, all tracked files in the + current directory and its subdirectories are updated. \--refresh:: Don't add the file(s), but only refresh their stat() diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 2ffba2102b..e640fc75cd 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -138,7 +138,7 @@ aborts in the middle,. You can recover from this in one of two ways: The command refuses to process new mailboxes while `.dotest` directory exists, so if you decide to start over from scratch, -run `rm -f .dotest` before running the command with mailbox +run `rm -f -r .dotest` before running the command with mailbox names. diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 72f080a972..505ac056e6 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -99,36 +99,62 @@ Assume two repositories exist as R1 on machine A, and R2 on machine B. For whatever reason, direct connection between A and B is not allowed, but we can move data from A to B via some mechanism (CD, email, etc). We want to update R2 with developments made on branch master in R1. + +To create the bundle you have to specify the basis. You have some options: + +- Without basis. ++ +This is useful when sending the whole history. + +------------ +$ git bundle create mybundle master +------------ + +- Using temporally tags. ++ We set a tag in R1 (lastR2bundle) after the previous such transport, and move it afterwards to help build the bundle. -in R1 on A: - ------------ $ git-bundle create mybundle master ^lastR2bundle $ git tag -f lastR2bundle master ------------ -(move mybundle from A to B by some mechanism) +- Using a tag present in both repositories + +------------ +$ git bundle create mybundle master ^v1.0.0 +------------ + +- A basis based on time. + +------------ +$ git bundle create mybundle master --since=10.days.ago +------------ -in R2 on B: +- With a limit on the number of commits ------------ -$ git-bundle verify mybundle -$ git-fetch mybundle refspec +$ git bundle create mybundle master -n 10 ------------ -where refspec is refInBundle:localRef +Then you move mybundle from A to B, and in R2 on B: +------------ +$ git-bundle verify mybundle +$ git-fetch mybundle master:localRef +------------ -Also, with something like this in your config: +With something like this in the config in R2: +------------------------ [remote "bundle"] url = /home/me/tmp/file.bdl fetch = refs/heads/*:refs/remotes/origin/* +------------------------ You can first sneakernet the bundle file to ~/tmp/file.bdl and -then these commands: +then these commands on machine B: ------------ $ git ls-remote bundle diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 1c3dfb40c6..fbb40a2916 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -45,6 +45,11 @@ OPTIONS candidates to describe the input committish consider up to <n> candidates. Increasing <n> above 10 will take slightly longer but may produce a more accurate result. + An <n> of 0 will cause only exact matches to be output. + +--exact-match:: + Only output exact matches (a tag directly references the + supplied commit). This is a synonym for --candidates=0. --debug:: Verbosely display information about the searching strategy diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index e22dfa5803..543a1cf105 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -56,7 +56,9 @@ notable exception of the commit filter, for technical reasons). Prior to that, the $GIT_COMMIT environment variable will be set to contain the id of the commit being rewritten. Also, GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_AUTHOR_DATE, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL, -and GIT_COMMITTER_DATE are set according to the current commit. +and GIT_COMMITTER_DATE are set according to the current commit. If any +evaluation of <command> returns a non-zero exit status, the whole operation +will be aborted. A 'map' function is available that takes an "original sha1 id" argument and outputs a "rewritten sha1 id" if the commit has been already @@ -197,7 +199,7 @@ happened). If this is not the case, use: -------------------------------------------------------------------------- git filter-branch --parent-filter \ - 'cat; test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>"' HEAD + 'test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>" || cat' HEAD -------------------------------------------------------------------------- or even simpler: @@ -240,6 +242,15 @@ committed a merge between P1 and P2, it will be propagated properly and all children of the merge will become merge commits with P1,P2 as their parents instead of the merge commit. +You can rewrite the commit log messages using `--message-filter`. For +example, `git-svn-id` strings in a repository created by `git-svn` can +be removed this way: + +------------------------------------------------------- +git filter-branch --message-filter ' + sed -e "/^git-svn-id:/d" +' +------------------------------------------------------- To restrict rewriting to only part of the history, specify a revision range in addition to the new branch name. The new branch name will diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index f3cb24f252..71a73354f8 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -75,9 +75,11 @@ OPTIONS -n:: Prefix the line number to matching lines. --l | --files-with-matches | -L | --files-without-match:: +-l | --files-with-matches | --name-only | -L | --files-without-match:: Instead of showing every matched line, show only the names of files that contain (or do not contain) matches. + For better compatability with git-diff, --name-only is a + synonym for --files-with-matches. -c | --count:: Instead of showing every matched line, show the number of diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index 5d816d0d8b..19ee017aed 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -8,7 +8,7 @@ git-merge-index - Run a merge for files needing merging SYNOPSIS -------- -'git-merge-index' [-o] [-q] <merge-program> (-a | \-- | <file>\*) +'git-merge-index' [-o] [-q] <merge-program> (-a | [--] <file>\*) DESCRIPTION ----------- diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index 8353be186f..5c1bd3b081 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -177,6 +177,8 @@ base-name:: This is meant to reduce packing time on multiprocessor machines. The required amount of memory for the delta search window is however multiplied by the number of threads. + Specifying 0 will cause git to auto-detect the number of CPU's + and set the number of threads accordingly. --index-version=<version>[,<offset>]:: This is intended to be used by the test suite only. It allows diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 179bdfc69d..737894390d 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -15,6 +15,7 @@ DESCRIPTION ----------- Runs `git-fetch` with the given parameters, and calls `git-merge` to merge the retrieved head(s) into the current branch. +With `--rebase`, calls `git-rebase` instead of `git-merge`. Note that you can use `.` (current directory) as the <repository> to pull from the local repository -- this is useful @@ -26,19 +27,14 @@ OPTIONS include::merge-options.txt[] :git-pull: 1 -include::fetch-options.txt[] - -include::pull-fetch-param.txt[] - -include::urls-remotes.txt[] - -include::merge-strategies.txt[] \--rebase:: Instead of a merge, perform a rebase after fetching. If there is a remote ref for the upstream branch, and this branch was rebased since last fetched, the rebase uses that information - to avoid rebasing non-local changes. + to avoid rebasing non-local changes. To make this the default + for branch `<name>`, set configuration `branch.<name>.rebase` + to `true`. + *NOTE:* This is a potentially _dangerous_ mode of operation. It rewrites history, which does not bode well when you @@ -48,6 +44,14 @@ unless you have read linkgit:git-rebase[1] carefully. \--no-rebase:: Override earlier \--rebase. +include::fetch-options.txt[] + +include::pull-fetch-param.txt[] + +include::urls-remotes.txt[] + +include::merge-strategies.txt[] + DEFAULT BEHAVIOUR ----------------- diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 5f2494495b..3128170bcd 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -47,9 +47,9 @@ even if it does not result in a fast forward update. + Note: If no explicit refspec is found, (that is neither on the command line nor in any Push line of the -corresponding remotes file---see below), then all the -heads that exist both on the local side and on the remote -side are updated. +corresponding remotes file---see below), then "matching" heads are +pushed: for every head that exists on the local side, the remote side is +updated if a head of the same name already exists on the remote side. + `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`. + @@ -108,6 +108,55 @@ the remote repository. include::urls-remotes.txt[] +OUTPUT +------ + +The output of "git push" depends on the transport method used; this +section describes the output when pushing over the git protocol (either +locally or via ssh). + +The status of the push is output in tabular form, with each line +representing the status of a single ref. Each line is of the form: + +------------------------------- + <flag> <summary> <from> -> <to> (<reason>) +------------------------------- + +flag:: + A single character indicating the status of the ref. This is + blank for a successfully pushed ref, `!` for a ref that was + rejected or failed to push, and '=' for a ref that was up to + date and did not need pushing (note that the status of up to + date refs is shown only when `git push` is running verbosely). + +summary:: + For a successfully pushed ref, the summary shows the old and new + values of the ref in a form suitable for using as an argument to + `git log` (this is `<old>..<new>` in most cases, and + `<old>...<new>` for forced non-fast forward updates). For a + failed update, more details are given for the failure. + The string `rejected` indicates that git did not try to send the + ref at all (typically because it is not a fast forward). The + string `remote rejected` indicates that the remote end refused + the update; this rejection is typically caused by a hook on the + remote side. The string `remote failure` indicates that the + remote end did not report the successful update of the ref + (perhaps because of a temporary error on the remote side, a + break in the network connection, or other transient error). + +from:: + The name of the local ref being pushed, minus its + `refs/<type>/` prefix. In the case of deletion, the + name of the local ref is omitted. + +to:: + The name of the remote ref being updated, minus its + `refs/<type>/` prefix. + +reason:: + A human-readable explanation. In the case of successfully pushed + refs, no explanation is needed. For a failed ref, the reason for + failure is described. Examples -------- diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 5b96eabfce..a8d489f9f2 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -31,6 +31,7 @@ SYNOPSIS [ \--(author|committer|grep)=<pattern> ] [ \--regexp-ignore-case | \-i ] [ \--extended-regexp | \-E ] + [ \--fixed-strings | \-F ] [ \--date={local|relative|default|iso|rfc|short} ] [ [\--objects | \--objects-edge] [ \--unpacked ] ] [ \--pretty | \--header ] diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index cd0dc1bd9d..48e6f5a3f7 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -43,7 +43,7 @@ save [<message>]:: subcommand is given. The <message> part is optional and gives the description along with the stashed state. -list:: +list [<options>]:: List the stashes that you currently have. Each 'stash' is listed with its name (e.g. `stash@\{0}` is the latest stash, `stash@\{1}` is @@ -55,6 +55,9 @@ list:: stash@{0}: WIP on submit: 6ebd0e2... Update git-stash documentation stash@{1}: On master: 9cc0589... Add git-stash ---------------------------------------------------------------- ++ +The command takes options applicable to the linkgit:git-log[1] +command to control what is shown and how. show [<stash>]:: diff --git a/Documentation/git.txt b/Documentation/git.txt index d57bed618f..741ae0e4c8 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,10 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.5.4.2/git.html[documentation for release 1.5.4.2] +* link:v1.5.4.3/git.html[documentation for release 1.5.4.3] * release notes for + link:RelNotes-1.5.4.3.txt[1.5.4.3], link:RelNotes-1.5.4.2.txt[1.5.4.2], link:RelNotes-1.5.4.1.txt[1.5.4.1], link:RelNotes-1.5.4.txt[1.5.4]. diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index a8138e27a1..259072c078 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -153,6 +153,11 @@ limiting may be applied. Consider the limiting patterns to be extended regular expressions instead of the default basic regular expressions. +-F, --fixed-strings:: + + Consider the limiting patterns to be fixed strings (don't interpret + pattern as a regular expression). + --remove-empty:: Stop when a given path disappears from the tree. diff --git a/Documentation/technical/api-remote.txt b/Documentation/technical/api-remote.txt new file mode 100644 index 0000000000..073b22bd83 --- /dev/null +++ b/Documentation/technical/api-remote.txt @@ -0,0 +1,123 @@ +Remotes configuration API +========================= + +The API in remote.h gives access to the configuration related to +remotes. It handles all three configuration mechanisms historically +and currently used by git, and presents the information in a uniform +fashion. Note that the code also handles plain URLs without any +configuration, giving them just the default information. + +struct remote +------------- + +`name`:: + + The user's nickname for the remote + +`url`:: + + An array of all of the url_nr URLs configured for the remote + +`push`:: + + An array of refspecs configured for pushing, with + push_refspec being the literal strings, and push_refspec_nr + being the quantity. + +`fetch`:: + + An array of refspecs configured for fetching, with + fetch_refspec being the literal strings, and fetch_refspec_nr + being the quantity. + +`fetch_tags`:: + + The setting for whether to fetch tags (as a separate rule from + the configured refspecs); -1 means never to fetch tags, 0 + means to auto-follow tags based on the default heuristic, 1 + means to always auto-follow tags, and 2 means to fetch all + tags. + +`receivepack`, `uploadpack`:: + + The configured helper programs to run on the remote side, for + git-native protocols. + +`http_proxy`:: + + The proxy to use for curl (http, https, ftp, etc.) URLs. + +struct remotes can be found by name with remote_get(), and iterated +through with for_each_remote(). remote_get(NULL) will return the +default remote, given the current branch and configuration. + +struct refspec +-------------- + +A struct refspec holds the parsed interpretation of a refspec. If it +will force updates (starts with a '+'), force is true. If it is a +pattern (sides end with '*') pattern is true. src and dest are the two +sides (if a pattern, only the part outside of the wildcards); if there +is only one side, it is src, and dst is NULL; if sides exist but are +empty (i.e., the refspec either starts or ends with ':'), the +corresponding side is "". + +This parsing can be done to an array of strings to give an array of +struct refpsecs with parse_ref_spec(). + +remote_find_tracking(), given a remote and a struct refspec with +either src or dst filled out, will fill out the other such that the +result is in the "fetch" specification for the remote (note that this +evaluates patterns and returns a single result). + +struct branch +------------- + +Note that this may end up moving to branch.h + +struct branch holds the configuration for a branch. It can be looked +up with branch_get(name) for "refs/heads/{name}", or with +branch_get(NULL) for HEAD. + +It contains: + +`name`:: + + The short name of the branch. + +`refname`:: + + The full path for the branch ref. + +`remote_name`:: + + The name of the remote listed in the configuration. + +`remote`:: + + The struct remote for that remote. + +`merge_name`:: + + An array of the "merge" lines in the configuration. + +`merge`:: + + An array of the struct refspecs used for the merge lines. That + is, merge[i]->dst is a local tracking ref which should be + merged into this branch by default. + +`merge_nr`:: + + The number of merge configurations + +branch_has_merge_config() returns true if the given branch has merge +configuration given. + +Other stuff +----------- + +There is other stuff in remote.h that is related, in general, to the +process of interacting with remotes. + +(Daniel Barkalow) diff --git a/Documentation/technical/api-run-command.txt b/Documentation/technical/api-run-command.txt index 19d2f64f73..dfbf9ac5d0 100644 --- a/Documentation/technical/api-run-command.txt +++ b/Documentation/technical/api-run-command.txt @@ -1,10 +1,171 @@ run-command API =============== -Talk about <run-command.h>, and things like: +The run-command API offers a versatile tool to run sub-processes with +redirected input and output as well as with a modified environment +and an alternate current directory. -* Environment the command runs with (e.g. GIT_DIR); -* File descriptors and pipes; -* Exit status; +A similar API offers the capability to run a function asynchronously, +which is primarily used to capture the output that the function +produces in the caller in order to process it. -(Hannes, Dscho, Shawn) + +Functions +--------- + +`start_command`:: + + Start a sub-process. Takes a pointer to a `struct child_process` + that specifies the details and returns pipe FDs (if requested). + See below for details. + +`finish_command`:: + + Wait for the completion of a sub-process that was started with + start_command(). + +`run_command`:: + + A convenience function that encapsulates a sequence of + start_command() followed by finish_command(). Takes a pointer + to a `struct child_process` that specifies the details. + +`run_command_v_opt`, `run_command_v_opt_dir`, `run_command_v_opt_cd_env`:: + + Convenience functions that encapsulate a sequence of + start_command() followed by finish_command(). The argument argv + specifies the program and its arguments. The argument opt is zero + or more of the flags `RUN_COMMAND_NO_STDIN`, `RUN_GIT_CMD`, or + `RUN_COMMAND_STDOUT_TO_STDERR` that correspond to the members + .no_stdin, .git_cmd, .stdout_to_stderr of `struct child_process`. + The argument dir corresponds the member .dir. The argument env + corresponds to the member .env. + +`start_async`:: + + Run a function asynchronously. Takes a pointer to a `struct + async` that specifies the details and returns a pipe FD + from which the caller reads. See below for details. + +`finish_async`:: + + Wait for the completeion of an asynchronous function that was + started with start_async(). + + +Data structures +--------------- + +* `struct child_process` + +This describes the arguments, redirections, and environment of a +command to run in a sub-process. + +The caller: + +1. allocates and clears (memset(&chld, '0', sizeof(chld));) a + struct child_process variable; +2. initializes the members; +3. calls start_command(); +4. processes the data; +5. closes file descriptors (if necessary; see below); +6. calls finish_command(). + +The .argv member is set up as an array of string pointers (NULL +terminated), of which .argv[0] is the program name to run (usually +without a path). If the command to run is a git command, set argv[0] to +the command name without the 'git-' prefix and set .git_cmd = 1. + +The members .in, .out, .err are used to redirect stdin, stdout, +stderr as follows: + +. Specify 0 to request no special redirection. No new file descriptor + is allocated. The child process simply inherits the channel from the + parent. + +. Specify -1 to have a pipe allocated; start_command() replaces -1 + by the pipe FD in the following way: + + .in: Returns the writable pipe end into which the caller writes; + the readable end of the pipe becomes the child's stdin. + + .out, .err: Returns the readable pipe end from which the caller + reads; the writable end of the pipe end becomes child's + stdout/stderr. + + The caller of start_command() must close the so returned FDs + after it has completed reading from/writing to it! + +. Specify a file descriptor > 0 to be used by the child: + + .in: The FD must be readable; it becomes child's stdin. + .out: The FD must be writable; it becomes child's stdout. + .err > 0 is not supported. + + The specified FD is closed by start_command(), even if it fails to + run the sub-process! + +. Special forms of redirection are available by setting these members + to 1: + + .no_stdin, .no_stdout, .no_stderr: The respective channel is + redirected to /dev/null. + + .stdout_to_stderr: stdout of the child is redirected to the + parent's stderr (i.e. *not* to what .err or + .no_stderr specify). + +To modify the environment of the sub-process, specify an array of +string pointers (NULL terminated) in .env: + +. If the string is of the form "VAR=value", i.e. it contains '=' + the variable is added to the child process's environment. + +. If the string does not contain '=', it names an environement + variable that will be removed from the child process's envionment. + +To specify a new initial working directory for the sub-process, +specify it in the .dir member. + + +* `struct async` + +This describes a function to run asynchronously, whose purpose is +to produce output that the caller reads. + +The caller: + +1. allocates and clears (memset(&asy, '0', sizeof(asy));) a + struct async variable; +2. initializes .proc and .data; +3. calls start_async(); +4. processes the data by reading from the fd in .out; +5. closes .out; +6. calls finish_async(). + +The function pointer in .proc has the following signature: + + int proc(int fd, void *data); + +. fd specifies a writable file descriptor to which the function must + write the data that it produces. The function *must* close this + descriptor before it returns. + +. data is the value that the caller has specified in the .data member + of struct async. + +. The return value of the function is 0 on success and non-zero + on failure. If the function indicates failure, finish_async() will + report failure as well. + + +There are serious restrictions on what the asynchronous function can do +because this facility is implemented by a pipe to a forked process on +UNIX, but by a thread in the same address space on Windows: + +. It cannot change the program's state (global variables, environment, + etc.) in a way that the caller notices; in other words, .out is the + only communication channel to the caller. + +. It must not change the program's state that the caller of the + facility also uses. |