diff options
Diffstat (limited to 'Documentation')
37 files changed, 528 insertions, 162 deletions
diff --git a/Documentation/RelNotes-1.7.0.1.txt b/Documentation/RelNotes-1.7.0.1.txt new file mode 100644 index 0000000000..8ff5bcada8 --- /dev/null +++ b/Documentation/RelNotes-1.7.0.1.txt @@ -0,0 +1,35 @@ +Git v1.7.0.1 Release Notes +========================== + +Fixes since v1.7.0 +------------------ + + * In a freshly created repository "rev-parse HEAD^0" complained that + it is dangling symref, even though "rev-parse HEAD" didn't. + + * "git show :no-such-name" tried to access the index without bounds + check, leading to a potential segfault. + + * Message from "git cherry-pick" was harder to read and use than necessary + when it stopped due to conflicting changes. + + * We referred to ".git/refs/" throughout the documentation when we + meant to talk about abstract notion of "ref namespace". Because + people's repositories often have packed refs these days, this was + confusing. + + * "git diff --output=/path/that/cannot/be/written" did not correctly + error out. + + * "git grep -e -pattern-that-begin-with-dash paths..." could not be + spelled as "git grep -- -pattern-that-begin-with-dash paths..." which + would be a GNU way to use "--" as "end of options". + + * "git grep" compiled with threading support tried to access an + uninitialized mutex on boxes with a single CPU. + + * "git stash pop -q --index" failed because the unnecessary --index + option was propagated to "git stash drop" that is internally run at the + end. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes-1.7.0.2.txt b/Documentation/RelNotes-1.7.0.2.txt new file mode 100644 index 0000000000..fcb46ca6a4 --- /dev/null +++ b/Documentation/RelNotes-1.7.0.2.txt @@ -0,0 +1,40 @@ +Git v1.7.0.2 Release Notes +========================== + +Fixes since v1.7.0.1 +-------------------- + + * GIT_PAGER was not honored consistently by some scripted Porcelains, most + notably "git am". + + * updating working tree files after telling git to add them to the + index and while it is still working created garbage object files in + the repository without diagnosing it as an error. + + * "git bisect -- pathspec..." did not diagnose an error condition properly when + the simplification with given pathspec made the history empty. + + * "git rev-list --cherry-pick A...B" now has an obvious optimization when the + histories haven't diverged (i.e. when one end is an ancestor of the other). + + * "git diff --quiet -w" did not work as expected. + + * "git fast-import" didn't work with a large input, as it lacked support + for producing the pack index in v2 format. + + * "git imap-send" didn't use CRLF line endings over the imap protocol + when storing its payload to the draft box, violating RFC 3501. + + * "git log --format='%w(x,y,z)%b'" and friends that rewrap message + has been optimized for utf-8 payload. + + * Error messages generated on the receiving end did not come back to "git + push". + + * "git status" in 1.7.0 lacked the optimization we used to have in 1.6.X series + to speed up scanning of large working tree. + + * "gitweb" did not diagnose parsing errors properly while reading tis configuration + file. + +And other minor fixes and documentation updates. diff --git a/Documentation/RelNotes-1.7.0.3.txt b/Documentation/RelNotes-1.7.0.3.txt new file mode 100644 index 0000000000..ed936385a5 --- /dev/null +++ b/Documentation/RelNotes-1.7.0.3.txt @@ -0,0 +1,34 @@ +Git v1.7.0.3 Release Notes (draft) +================================== + +Fixes since v1.7.0.2 +-------------------- + + * Object files are created in a more ACL friendly way in repositories + where group permission is ACL controlled. + + * "git add -i" didn't handle a deleted path very well. + + * "git fetch --all/--multi" used to discard information for remotes that + are fetched earlier. + + * "git log --author=me --grep=it" tried to find commits that have "it" + or are written by "me", instead of the ones that have "it" _and_ are + written by "me". + + * "git mailinfo" (hence "git am") incorrectly removed initial indent from + paragraphs. + + * "git prune" and "git reflog" (hence "git gc" as well) didn't honor + an instruction never to expire by setting gc.reflogexpire to never. + + * "git push" misbehaved when branch.<name>.merge was configured without + matching branch.<name>.remote. + +And other minor fixes and documentation updates. + +-- +exec >/var/tmp/1 +echo O=$(git describe) +O=v1.7.0.2-53-g6eb3adf +git shortlog --no-merges $O.. diff --git a/Documentation/RelNotes-1.7.1.txt b/Documentation/RelNotes-1.7.1.txt new file mode 100644 index 0000000000..dfc06cb3de --- /dev/null +++ b/Documentation/RelNotes-1.7.1.txt @@ -0,0 +1,38 @@ +Git v1.7.1 Release Notes (draft) +================================ + +Updates since v1.7.0 +-------------------- + + * "git cvsimport" learned -R option to leave revision mapping between + CVS revisions and resulting git commits. + + * "git for-each-ref" learned %(symref), %(symref:short) and %(flag) + tokens. + + * "git grep" learned "--no-index" option, to search inside contents that + are not managed by git. + + * "git grep" learned --color=auto/always/never. + + * "git hash-object --stdin-paths" can take "--no-filters" option now. + + * "git request-pull" identifies the commit the request is relative to in + a more readable way. + + * "git svn" should work better when interacting with repositories + with CRLF line endings. + + * "git imap-send" learned to support CRAM-MD5 authentication. + +Fixes since v1.7.0 +------------------ + +All of the fixes in v1.7.0.X maintenance series are included in this +release, unless otherwise noted. + +--- +exec >/var/tmp/1 +echo O=$(git describe) +O=v1.7.0.2-181-gc6830a3 +git shortlog --no-merges ^maint $O.. diff --git a/Documentation/config.txt b/Documentation/config.txt index 4c36aa95b7..c80262bc37 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -138,6 +138,11 @@ advice.*:: Advice on how to set your identity configuration when your information is guessed from the system username and domain name. Default: true. + + detachedHead:: + Advice shown when you used linkgit::git-checkout[1] to + move to the detach HEAD state, to instruct how to create + a local branch after the fact. Default: true. -- core.fileMode:: @@ -550,6 +555,13 @@ it will be treated as a shell command. For example, defining executed from the top-level directory of a repository, which may not necessarily be the current directory. +am.keepcr:: + If true, git-am will call git-mailsplit for patches in mbox format + with parameter '--keep-cr'. In this case git-mailsplit will + not remove `\r` from lines ending with `\r\n`. Can be overrriden + by giving '--no-keep-cr' from the command line. + See linkgit:git-am[1], linkgit:git-mailsplit[1]. + apply.ignorewhitespace:: When set to 'change', tells 'git apply' to ignore changes in whitespace, in the same way as the '--ignore-space-change' @@ -680,9 +692,7 @@ color.grep:: color.grep.match:: Use customized color for matches. The value of this variable - may be specified as in color.branch.<slot>. It is passed using - the environment variables 'GREP_COLOR' and 'GREP_COLORS' when - calling an external 'grep'. + may be specified as in color.branch.<slot>. color.interactive:: When set to `always`, always use colors for interactive prompts @@ -1200,6 +1210,10 @@ imap:: The configuration variables in the 'imap' section are described in linkgit:git-imap-send[1]. +init.templatedir:: + Specify the directory from which templates will be copied. + (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) + instaweb.browser:: Specify the program that will be used to browse your working repository in gitweb. See linkgit:git-instaweb[1]. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 8707d0e740..60e922e6ef 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -117,12 +117,14 @@ any of those replacements occurred. option and lists the commits in that commit range like the 'summary' option of linkgit:git-submodule[1] does. ---color:: +--color[=<when>]:: Show colored diff. + The value must be always (the default), never, or auto. --no-color:: Turn off colored diff, even when the configuration file gives the default to color output. + Same as `--color=never`. --color-words[=<regex>]:: Show colored word diff, i.e., color words which have changed. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index fe716b2e42..044ec882cc 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -78,9 +78,16 @@ ifndef::git-pull[] -q:: --quiet:: Pass --quiet to git-fetch-pack and silence any other internally - used git commands. + used git commands. Progress is not reported to the standard error + stream. -v:: --verbose:: Be verbose. endif::git-pull[] + +--progress:: + Progress status is reported on the standard error stream + by default when it is attached to a terminal, unless -q + is specified. This flag forces progress status even if the + standard error stream is not directed to a terminal. diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index c66c565bbe..9e62f8778f 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -9,7 +9,7 @@ git-am - Apply a series of patches from a mailbox SYNOPSIS -------- [verse] -'git am' [--signoff] [--keep] [--utf8 | --no-utf8] +'git am' [--signoff] [--keep] [--keep-cr | --no-keep-cr] [--utf8 | --no-utf8] [--3way] [--interactive] [--committer-date-is-author-date] [--ignore-date] [--ignore-space-change | --ignore-whitespace] [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>] @@ -39,12 +39,19 @@ OPTIONS --keep:: Pass `-k` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). +--keep-cr:: +--no-keep-cr:: + With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1]) + with the same option, to prevent it from stripping CR at the end of + lines. `am.keepcr` configuration variable can be used to specify the + default behaviour. `--no-keep-cr` is useful to override `am.keepcr`. + -c:: --scissors:: Remove everything in body before a scissors line (see linkgit:git-mailinfo[1]). ----no-scissors:: +--no-scissors:: Ignore scissors lines (see linkgit:git-mailinfo[1]). -q:: diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 6b6c3da2d9..903a690f10 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -8,7 +8,7 @@ git-branch - List, create, or delete branches SYNOPSIS -------- [verse] -'git branch' [--color | --no-color] [-r | -a] +'git branch' [--color[=<when>] | --no-color] [-r | -a] [-v [--abbrev=<length> | --no-abbrev]] [(--merged | --no-merged | --contains) [<commit>]] 'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>] @@ -84,12 +84,14 @@ OPTIONS -M:: Move/rename a branch even if the new branch name already exists. ---color:: +--color[=<when>]:: Color branches to highlight current, local, and remote branches. + The value must be always (the default), never, or auto. --no-color:: Turn off branch colors, even when the configuration file gives the default to color output. + Same as `--color=never`. -r:: List or delete (if used with -d) the remote-tracking branches. diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index e1c4320f02..379eee6734 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -19,8 +19,9 @@ status if it is not. A reference is used in git to specify branches and tags. A branch head is stored under the `$GIT_DIR/refs/heads` directory, and -a tag is stored under the `$GIT_DIR/refs/tags` directory. git -imposes the following rules on how references are named: +a tag is stored under the `$GIT_DIR/refs/tags` directory (or, if refs +are packed by `git gc`, as entries in the `$GIT_DIR/packed-refs` file). +git imposes the following rules on how references are named: . They can include slash `/` for hierarchical (directory) grouping, but no slash-separated component can begin with a diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index f43c8b2c08..43cfba0e45 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -29,7 +29,7 @@ arguments will in addition merge the remote master branch into the current master branch, if any. This default configuration is achieved by creating references to -the remote branch heads under `$GIT_DIR/refs/remotes/origin` and +the remote branch heads under `refs/remotes/origin` and by initializing `remote.origin.url` and `remote.origin.fetch` configuration variables. @@ -102,7 +102,8 @@ objects from the source repository into a pack in the cloned repository. --verbose:: -v:: - Run verbosely. + Run verbosely. Does not affect the reporting of progress status + to the standard error stream. --progress:: Progress status is reported on the standard error stream @@ -149,8 +150,7 @@ objects from the source repository into a pack in the cloned repository. --template=<template_directory>:: Specify the directory from which templates will be used; - if unset the templates are taken from the installation - defined default, typically `/usr/share/git-core/templates`. + (See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].) --depth <depth>:: Create a 'shallow' clone with a history truncated to the diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index e99bb14754..64fb458b45 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -197,13 +197,13 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) Show untracked files (Default: 'all'). + The mode parameter is optional, and is used to specify -the handling of untracked files. The possible options are: +the handling of untracked files. ++ +The possible options are: + --- - 'no' - Show no untracked files - 'normal' - Shows untracked files and directories - 'all' - Also shows individual files in untracked directories. --- + See linkgit:git-config[1] for configuration variable used to change the default for when the option is not diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index ddfcb3d143..8bcd875a67 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -13,7 +13,7 @@ SYNOPSIS [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>] [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>] [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>] - [-r <remote>] [<CVS_module>] + [-r <remote>] [-R] [<CVS_module>] DESCRIPTION @@ -157,6 +157,22 @@ It is not recommended to use this feature if you intend to export changes back to CVS again later with 'git cvsexportcommit'. +-R:: + Generate a `$GIT_DIR/cvs-revisions` file containing a mapping from CVS + revision numbers to newly-created Git commit IDs. The generated file + will contain one line for each (filename, revision) pair imported; + each line will look like ++ +--------- +src/widget.c 1.1 1d862f173cdc7325b6fa6d2ae1cfd61fd1b512b7 +--------- ++ +The revision data is appended to the file if it already exists, for use when +doing incremental imports. ++ +This option may be useful if you have CVS revision numbers stored in commit +messages, bug-tracking systems, email archives, and the like. + -h:: Print a short usage message and exit. diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 6764ff1886..19082b04eb 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -45,10 +45,7 @@ OPTIONS --max-pack-size=<n>:: Maximum size of each output packfile. - The default is 4 GiB as that is the maximum allowed - packfile size (due to file format limitations). Some - importers may wish to lower this, such as to ensure the - resulting packfiles fit on CDs. + The default is unlimited. --big-file-threshold=<n>:: Maximum size of a blob that fast-import will attempt to diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index e9952e8210..4a8487c154 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -18,7 +18,7 @@ higher level wrapper of this command, instead. Invokes 'git-upload-pack' on a possibly remote repository and asks it to send objects missing from this repository, to update the named heads. The list of commits available locally -is found out by scanning local $GIT_DIR/refs/ and sent to +is found out by scanning the local refs/ hierarchy and sent to 'git-upload-pack' running on the other end. This command degenerates to download everything to complete the @@ -44,8 +44,8 @@ OPTIONS locked against repacking. --thin:: - Spend extra cycles to minimize the number of objects to be sent. - Use it on slower connection. + Fetch a "thin" pack, which records objects in deltified form based + on objects not included in the pack to reduce network traffic. --include-tag:: If the remote side supports it, annotated tags objects will diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index e019e760b4..4b32322a67 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -9,8 +9,7 @@ git-grep - Print lines matching a pattern SYNOPSIS -------- [verse] -'git grep' [--cached] - [-a | --text] [-I] [-i | --ignore-case] [-w | --word-regexp] +'git grep' [-a | --text] [-I] [-i | --ignore-case] [-w | --word-regexp] [-v | --invert-match] [-h|-H] [--full-name] [-E | --extended-regexp] [-G | --basic-regexp] [-F | --fixed-strings] [-n] @@ -18,23 +17,27 @@ SYNOPSIS [-z | --null] [-c | --count] [--all-match] [-q | --quiet] [--max-depth <depth>] - [--color | --no-color] + [--color[=<when>] | --no-color] [-A <post-context>] [-B <pre-context>] [-C <context>] [-f <file>] [-e] <pattern> - [--and|--or|--not|(|)|-e <pattern>...] [<tree>...] - [--] [<path>...] + [--and|--or|--not|(|)|-e <pattern>...] + [--cached | --no-index | <tree>...] + [--] [<pathspec>...] DESCRIPTION ----------- -Look for specified patterns in the working tree files, blobs -registered in the index file, or given tree objects. +Look for specified patterns in the tracked files in the work tree, blobs +registered in the index file, or blobs in given tree objects. OPTIONS ------- --cached:: - Instead of searching in the working tree files, check - the blobs registered in the index file. + Instead of searching tracked files in the working tree, search + blobs registered in the index file. + +--no-index:: + Search files in the current directory, not just those tracked by git. -a:: --text:: @@ -49,7 +52,7 @@ OPTIONS Don't match the pattern in binary files. --max-depth <depth>:: - For each pathspec given on command line, descend at most <depth> + For each <pathspec> given on command line, descend at most <depth> levels of directories. A negative value means no limit. -w:: @@ -98,8 +101,8 @@ OPTIONS --files-without-match:: Instead of showing every matched line, show only the names of files that contain (or do not contain) matches. - For better compatibility with 'git diff', --name-only is a - synonym for --files-with-matches. + For better compatibility with 'git diff', `--name-only` is a + synonym for `--files-with-matches`. -z:: --null:: @@ -111,12 +114,14 @@ OPTIONS Instead of showing every matched line, show the number of lines that match. ---color:: +--color[=<when>]:: Show colored matches. + The value must be always (the default), never, or auto. --no-color:: Turn off match highlighting, even when the configuration file gives the default to color output. + Same as `--color=never`. -[ABC] <context>:: Show `context` trailing (`A` -- after), or leading (`B` @@ -125,7 +130,7 @@ OPTIONS matches. -<num>:: - A shortcut for specifying -C<num>. + A shortcut for specifying `-C<num>`. -p:: --show-function:: @@ -140,7 +145,7 @@ OPTIONS -e:: The next parameter is the pattern. This option has to be - used for patterns starting with - and should be used in + used for patterns starting with `-` and should be used in scripts passing user input to grep. Multiple patterns are combined by 'or'. @@ -163,16 +168,24 @@ OPTIONS Do not output matched lines; instead, exit with status 0 when there is a match and with non-zero status when there isn't. -`<tree>...`:: - Search blobs in the trees for specified patterns. +<tree>...:: + Instead of searching tracked files in the working tree, search + blobs in the given trees. \--:: Signals the end of options; the rest of the parameters - are <path> limiters. + are <pathspec> limiters. +<pathspec>...:: + If given, limit the search to paths matching at least one pattern. + Both leading paths match and glob(7) patterns are supported. -Example -------- +Examples +-------- + +git grep 'time_t' -- '*.[ch]':: + Looks for `time_t` in all tracked .c and .h files in the working + directory and its subdirectories. git grep -e \'#define\' --and \( -e MAX_PATH -e PATH_MAX \):: Looks for a line that has `#define` and either `MAX_PATH` or diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index 479fce4693..6904739a48 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin] [--] <file>... -'git hash-object' [-t <type>] [-w] --stdin-paths < <list-of-paths> +'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters] < <list-of-paths> DESCRIPTION ----------- diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt index 57db955bd4..6cafbe2ec1 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -71,6 +71,10 @@ imap.preformattedHTML:: option causes Thunderbird to send the patch as a plain/text, format=fixed email. Default is `false`. +imap.authMethod:: + Specify authenticate method for authentication with IMAP server. + Current supported method is 'CRAM-MD5' only. + Examples ~~~~~~~~ diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index 65a301bece..f3ccc72f0d 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -46,14 +46,10 @@ OPTIONS 'git repack'. --fix-thin:: - It is possible for 'git pack-objects' to build - "thin" pack, which records objects in deltified form based on - objects not included in the pack to reduce network traffic. - Those objects are expected to be present on the receiving end - and they must be included in the pack for that pack to be self - contained and indexable. Without this option any attempt to - index a thin pack will fail. This option only makes sense in - conjunction with --stdin. + Fix a "thin" pack produced by `git pack-objects --thin` (see + linkgit:git-pack-objects[1] for details) by adding the + excluded objects the deltified objects are based on to the + pack. This option only makes sense in conjunction with --stdin. --keep:: Before moving the index into its final destination diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 7ee102da48..246b07ebf9 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -28,14 +28,8 @@ current working directory. --template=<template_directory>:: -Provide the directory from which templates will be used. The default template -directory is `/usr/share/git-core/templates`. - -When specified, `<template_directory>` is used as the source of the template -files rather than the default. The template files include some directory -structure, some suggested "exclude patterns", and copies of non-executing -"hook" files. The suggested patterns and hook files are all modifiable and -extensible. +Specify the directory from which templates will be used. (See the "TEMPLATE +DIRECTORY" section below.) --shared[={false|true|umask|group|all|world|everybody|0xxx}]:: @@ -106,6 +100,25 @@ of the repository, such as installing the default hooks and setting the configuration variables. The old name is retained for backward compatibility reasons. +TEMPLATE DIRECTORY +------------------ + +The template directory contains files and directories that will be copied to +the `$GIT_DIR` after it is created. + +The template directory used will (in order): + + - The argument given with the `--template` option. + + - The contents of the `$GIT_TEMPLATE_DIR` environment variable. + + - The `init.templatedir` configuration variable. + + - The default template directory: `/usr/share/git-core/templates`. + +The default template directory includes some directory structure, some +suggested "exclude patterns", and copies of sample "hook" files. +The suggested patterns and hook files are all modifiable and extensible. EXAMPLES -------- diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt index 5cc94ec53d..a634485281 100644 --- a/Documentation/git-mailsplit.txt +++ b/Documentation/git-mailsplit.txt @@ -7,7 +7,7 @@ git-mailsplit - Simple UNIX mbox splitter program SYNOPSIS -------- -'git mailsplit' [-b] [-f<nn>] [-d<prec>] -o<directory> [--] [<mbox>|<Maildir>...] +'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] -o<directory> [--] [<mbox>|<Maildir>...] DESCRIPTION ----------- @@ -43,6 +43,9 @@ OPTIONS Skip the first <nn> numbers, for example if -f3 is specified, start the numbering with 0004. +--keep-cr:: + Do not remove `\r` from lines ending with `\r\n`. + Author ------ Written by Linus Torvalds <torvalds@osdl.org> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index d4487cab52..bef2f3942e 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -3,57 +3,112 @@ git-notes(1) NAME ---- -git-notes - Add/inspect commit notes +git-notes - Add/inspect object notes SYNOPSIS -------- [verse] -'git notes' (edit [-F <file> | -m <msg>] | show) [commit] +'git notes' [list [<object>]] +'git notes' add [-f] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' copy [-f] <from-object> <to-object> +'git notes' append [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' edit [<object>] +'git notes' show [<object>] +'git notes' remove [<object>] +'git notes' prune + DESCRIPTION ----------- -This command allows you to add notes to commit messages, without -changing the commit. To discern these notes from the message stored -in the commit object, the notes are indented like the message, after -an unindented line saying "Notes:". +This command allows you to add/remove notes to/from objects, without +changing the objects themselves. + +A typical use of notes is to extend a commit message without having +to change the commit itself. Such commit notes can be shown by `git log` +along with the original commit message. To discern these notes from the +message stored in the commit object, the notes are indented like the +message, after an unindented line saying "Notes:". -To disable commit notes, you have to set the config variable -core.notesRef to the empty string. Alternatively, you can set it -to a different ref, something like "refs/notes/bugzilla". This setting -can be overridden by the environment variable "GIT_NOTES_REF". +To disable notes, you have to set the config variable core.notesRef to +the empty string. Alternatively, you can set it to a different ref, +something like "refs/notes/bugzilla". This setting can be overridden +by the environment variable "GIT_NOTES_REF". SUBCOMMANDS ----------- +list:: + List the notes object for a given object. If no object is + given, show a list of all note objects and the objects they + annotate (in the format "<note object> <annotated object>"). + This is the default subcommand if no subcommand is given. + +add:: + Add notes for a given object (defaults to HEAD). Abort if the + object already has notes (use `-f` to overwrite an + existing note). + +copy:: + Copy the notes for the first object onto the second object. + Abort if the second object already has notes, or if the first + object has none (use -f to overwrite existing notes to the + second object). This subcommand is equivalent to: + `git notes add [-f] -C $(git notes list <from-object>) <to-object>` + +append:: + Append to the notes of an existing object (defaults to HEAD). + Creates a new notes object if needed. + edit:: - Edit the notes for a given commit (defaults to HEAD). + Edit the notes for a given object (defaults to HEAD). show:: - Show the notes for a given commit (defaults to HEAD). + Show the notes for a given object (defaults to HEAD). + +remove:: + Remove the notes for a given object (defaults to HEAD). + This is equivalent to specifying an empty note message to + the `edit` subcommand. +prune:: + Remove all notes for non-existing/unreachable objects. OPTIONS ------- +-f:: +--force:: + When adding notes to an object that already has notes, + overwrite the existing notes (instead of aborting). + -m <msg>:: +--message=<msg>:: Use the given note message (instead of prompting). - If multiple `-m` (or `-F`) options are given, their - values are concatenated as separate paragraphs. + If multiple `-m` options are given, their values + are concatenated as separate paragraphs. -F <file>:: +--file=<file>:: Take the note message from the given file. Use '-' to read the note message from the standard input. - If multiple `-F` (or `-m`) options are given, their - values are concatenated as separate paragraphs. +-C <object>:: +--reuse-message=<object>:: + Reuse the note message from the given note object. + +-c <object>:: +--reedit-message=<object>:: + Like '-C', but with '-c' the editor is invoked, so that + the user can further edit the note message. Author ------ -Written by Johannes Schindelin <johannes.schindelin@gmx.de> +Written by Johannes Schindelin <johannes.schindelin@gmx.de> and +Johan Herland <johan@herland.net> Documentation ------------- -Documentation by Johannes Schindelin +Documentation by Johannes Schindelin and Johan Herland GIT --- diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index ffd5025f7b..8ed09c0b3c 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -21,16 +21,21 @@ DESCRIPTION Reads list of objects from the standard input, and writes a packed archive with specified base-name, or to the standard output. -A packed archive is an efficient way to transfer set of objects -between two repositories, and also is an archival format which -is efficient to access. The packed archive format (.pack) is -designed to be self contained so that it can be unpacked without -any further information, but for fast, random access to the objects -in the pack, a pack index file (.idx) will be generated. - -Placing both in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or +A packed archive is an efficient way to transfer a set of objects +between two repositories as well as an access efficient archival +format. In a packed archive, an object is either stored as a +compressed whole or as a difference from some other object. +The latter is often called a delta. + +The packed archive format (.pack) is designed to be self-contained +so that it can be unpacked without any further information. Therefore, +each object that a delta depends upon must be present within the pack. + +A pack index file (.idx) is generated for fast, random access to the +objects in the pack. Placing both the index file (.idx) and the packed +archive (.pack) in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or any of the directories on $GIT_ALTERNATE_OBJECT_DIRECTORIES) -enables git to read from such an archive. +enables git to read from the pack archive. The 'git unpack-objects' command can read the packed archive and expand the objects contained in the pack into "one-file @@ -38,10 +43,6 @@ one-object" format; this is typically done by the smart-pull commands when a pack is created on-the-fly for efficient network transport by their peers. -In a packed archive, an object is either stored as a compressed -whole, or as a difference from some other object. The latter is -often called a delta. - OPTIONS ------- @@ -73,7 +74,7 @@ base-name:: --all:: This implies `--revs`. In addition to the list of revision arguments read from the standard input, pretend - as if all refs under `$GIT_DIR/refs` are specified to be + as if all refs under `refs/` are specified to be included. --include-tag:: @@ -114,18 +115,17 @@ base-name:: --honor-pack-keep:: This flag causes an object already in a local pack that - has a .keep file to be ignored, even if it appears in the - standard input. + has a .keep file to be ignored, even if it it would have + otherwise been packed. --incremental:: - This flag causes an object already in a pack ignored - even if it appears in the standard input. + This flag causes an object already in a pack to be ignored + even if it would have otherwise been packed. --local:: - This flag is similar to `--incremental`; instead of - ignoring all packed objects, it only ignores objects - that are packed and/or not in the local object store - (i.e. borrowed from an alternate). + This flag causes an object that is borrowed from an alternate + object store to be ignored even if it would have otherwise been + packed. --non-empty:: Only create a packed archive if it would contain at @@ -179,6 +179,16 @@ base-name:: Add --no-reuse-object if you want to force a uniform compression level on all data no matter the source. +--thin:: + Create a "thin" pack by omitting the common objects between a + sender and a receiver in order to reduce network transfer. This + option only makes sense in conjunction with --stdout. ++ +Note: A thin pack violates the packed archive format by omitting +required objects and is thus unusable by git without making it +self-contained. Use `git index-pack --fix-thin` +(see linkgit:git-index-pack[1]) to restore the self-contained property. + --delta-base-offset:: A packed archive can express base object of a delta as either 20-byte object name or as an offset in the diff --git a/Documentation/git-prune.txt b/Documentation/git-prune.txt index 3bb7304517..15cfb7a8dc 100644 --- a/Documentation/git-prune.txt +++ b/Documentation/git-prune.txt @@ -17,7 +17,7 @@ NOTE: In most cases, users should run 'git gc', which calls 'git prune'. See the section "NOTES", below. This runs 'git fsck --unreachable' using all the refs -available in `$GIT_DIR/refs`, optionally with additional set of +available in `refs/`, optionally with additional set of objects specified on the command line, and prunes all unpacked objects unreachable from any of these head objects from the object database. In addition, it diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 31f42ea21a..ab4de10358 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -31,6 +31,16 @@ in a state that is hard to back out of in the case of a conflict. OPTIONS ------- +-q:: +--quiet:: + This is passed to both underlying git-fetch to squelch reporting of + during transfer, and underlying git-merge to squelch output during + merging. + +-v:: +--verbose:: + Pass --verbose to git-fetch and git-merge. + Options related to merging ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index bd79119dd3..59dc8b197e 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -69,11 +69,11 @@ nor in any Push line of the corresponding remotes file---see below). --all:: Instead of naming each ref to push, specifies that all - refs under `$GIT_DIR/refs/heads/` be pushed. + refs under `refs/heads/` be pushed. --mirror:: Instead of naming each ref to push, specifies that all - refs under `$GIT_DIR/refs/` (which includes but is not + refs under `refs/` (which includes but is not limited to `refs/heads/`, `refs/remotes/`, and `refs/tags/`) be mirrored to the remote repository. Newly created local refs will be pushed to the remote end, locally updated refs @@ -96,7 +96,7 @@ nor in any Push line of the corresponding remotes file---see below). the same as prefixing all refs with a colon. --tags:: - All refs under `$GIT_DIR/refs/tags` are pushed, in + All refs under `refs/tags` are pushed, in addition to refspecs explicitly listed on the command line. @@ -141,18 +141,26 @@ useful if you write an alias or script around 'git push'. --thin:: --no-thin:: - These options are passed to 'git send-pack'. Thin - transfer spends extra cycles to minimize the number of - objects to be sent and meant to be used on slower connection. + These options are passed to linkgit:git-send-pack[1]. A thin transfer + significantly reduces the amount of sent data when the sender and + receiver share many of the same objects in common. The default is + \--thin. + +-q:: +--quiet:: + Suppress all output, including the listing of updated refs, + unless an error occurs. Progress is not reported to the standard + error stream. -v:: --verbose:: Run verbosely. --q:: ---quiet:: - Suppress all output, including the listing of updated refs, - unless an error occurs. +--progress:: + Progress status is reported on the standard error stream + by default when it is attached to a terminal, unless -q + is specified. This flag forces progress status even if the + standard error stream is not directed to a terminal. include::urls-remotes.txt[] diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index d677c72d5e..8db600f6ba 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -101,15 +101,14 @@ OPTIONS abbreviation mode. --all:: - Show all refs found in `$GIT_DIR/refs`. + Show all refs found in `refs/`. --branches[=pattern]:: --tags[=pattern]:: --remotes[=pattern]:: Show all branches, tags, or remote-tracking branches, - respectively (i.e., refs found in `$GIT_DIR/refs/heads`, - `$GIT_DIR/refs/tags`, or `$GIT_DIR/refs/remotes`, - respectively). + respectively (i.e., refs found in `refs/heads`, + `refs/tags`, or `refs/remotes`, respectively). + If a `pattern` is given, only refs matching the given shell glob are shown. If the pattern does not contain a globbing character (`?`, @@ -149,6 +148,12 @@ shown. If the pattern does not contain a globbing character (`?`, --is-bare-repository:: When the repository is bare print "true", otherwise "false". +--local-env-vars:: + List the GIT_* environment variables that are local to the + repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR). + Only the names of the variables are listed, not their value, + even if they are set. + --short:: --short=number:: Instead of outputting the full SHA1 values of object names try to @@ -189,7 +194,7 @@ blobs contained in a commit. `g`, and an abbreviated object name. * A symbolic ref name. E.g. 'master' typically means the commit - object referenced by $GIT_DIR/refs/heads/master. If you + object referenced by refs/heads/master. If you happen to have both heads/master and tags/master, you can explicitly say 'heads/master' to tell git which one you mean. When ambiguous, a `<name>` is disambiguated by taking the @@ -198,15 +203,15 @@ blobs contained in a commit. . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD` and `MERGE_HEAD`); - . otherwise, `$GIT_DIR/refs/<name>` if exists; + . otherwise, `refs/<name>` if exists; - . otherwise, `$GIT_DIR/refs/tags/<name>` if exists; + . otherwise, `refs/tags/<name>` if exists; - . otherwise, `$GIT_DIR/refs/heads/<name>` if exists; + . otherwise, `refs/heads/<name>` if exists; - . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists; + . otherwise, `refs/remotes/<name>` if exists; - . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists. + . otherwise, `refs/remotes/<name>/HEAD` if exists. + HEAD names the commit your changes in the working tree is based on. FETCH_HEAD records the branch you fetched from a remote repository @@ -217,6 +222,9 @@ you can change the tip of the branch back to the state before you ran them easily. MERGE_HEAD records the commit(s) you are merging into your branch when you run 'git merge'. ++ +Note that any of the `refs/*` cases above may come either from +the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file. * A ref followed by the suffix '@' with a date specification enclosed in a brace diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt index 8178d92642..deaa7d9654 100644 --- a/Documentation/git-send-pack.txt +++ b/Documentation/git-send-pack.txt @@ -48,8 +48,8 @@ OPTIONS Run verbosely. --thin:: - Spend extra cycles to minimize the number of objects to be sent. - Use it on slower connection. + Send a "thin" pack, which records objects in deltified form based + on objects not included in the pack to reduce network traffic. <host>:: A remote host to house the repository. When this diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index 734336119c..f1499bba88 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git show-branch' [-a|--all] [-r|--remotes] [--topo-order | --date-order] - [--current] [--color | --no-color] [--sparse] + [--current] [--color[=<when>] | --no-color] [--sparse] [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] [--topics] [<rev> | <glob>]... @@ -20,8 +20,8 @@ DESCRIPTION ----------- Shows the commit ancestry graph starting from the commits named -with <rev>s or <globs>s (or all refs under $GIT_DIR/refs/heads -and/or $GIT_DIR/refs/tags) semi-visually. +with <rev>s or <globs>s (or all refs under refs/heads +and/or refs/tags) semi-visually. It cannot show more than 29 branches and commits at a time. @@ -37,8 +37,8 @@ OPTIONS <glob>:: A glob pattern that matches branch or tag names under - $GIT_DIR/refs. For example, if you have many topic - branches under $GIT_DIR/refs/heads/topic, giving + refs/. For example, if you have many topic + branches under refs/heads/topic, giving `topic/*` would show all of them. -r:: @@ -117,13 +117,15 @@ OPTIONS When no explicit <ref> parameter is given, it defaults to the current branch (or `HEAD` if it is detached). ---color:: +--color[=<when>]:: Color the status sign (one of these: `*` `!` `+` `-`) of each commit corresponding to the branch it's in. + The value must be always (the default), never, or auto. --no-color:: Turn off colored output, even when the configuration file gives the default to color output. + Same as `--color=never`. Note that --more, --list, --independent and --merge-base options are mutually exclusive. @@ -176,7 +178,7 @@ EXAMPLE ------- If you keep your primary branches immediately under -`$GIT_DIR/refs/heads`, and topic branches in subdirectories of +`refs/heads`, and topic branches in subdirectories of it, having the following in the configuration file may help: ------------ diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 84e555d81d..473889a660 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -33,7 +33,7 @@ A stash is by default listed as "WIP on 'branchname' ...", but you can give a more descriptive message on the command line when you create one. -The latest stash you created is stored in `$GIT_DIR/refs/stash`; older +The latest stash you created is stored in `refs/stash`; older stashes are found in the reflog of this reference and can be named using the usual reflog syntax (e.g. `stash@\{0}` is the most recently created stash, `stash@\{1}` is the one before it, `stash@\{2.hours.ago}` diff --git a/Documentation/git-var.txt b/Documentation/git-var.txt index bb981822a4..458f3e2755 100644 --- a/Documentation/git-var.txt +++ b/Documentation/git-var.txt @@ -8,7 +8,7 @@ git-var - Show a git logical variable SYNOPSIS -------- -'git var' [ -l | <variable> ] +'git var' ( -l | <variable> ) DESCRIPTION ----------- diff --git a/Documentation/git.txt b/Documentation/git.txt index 01c463101b..35c0c7983d 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,11 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.7.0/git.html[documentation for release 1.7.0] +* link:v1.7.0.2/git.html[documentation for release 1.7.0.2] * release notes for + link:RelNotes-1.7.0.2.txt[1.7.0.2], + link:RelNotes-1.7.0.1.txt[1.7.0.1], link:RelNotes-1.7.0.txt[1.7.0]. * link:v1.6.6.2/git.html[documentation for release 1.6.6.2] @@ -229,7 +231,10 @@ help ...`. -p:: --paginate:: - Pipe all output into 'less' (or if set, $PAGER). + Pipe all output into 'less' (or if set, $PAGER) if standard + output is a terminal. This overrides the `pager.<cmd>` + configuration options (see the "Configuration Mechanism" section + below). --no-pager:: Do not pipe git output into a pager. @@ -401,7 +406,8 @@ people. Here is an example: ------------ Various commands read from the configuration file and adjust -their operation accordingly. +their operation accordingly. See linkgit:git-config[1] for a +list. Identifier Terminology diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index b396a871b3..d892e642ed 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -511,7 +511,8 @@ command to run to merge ancestor's version (`%O`), current version (`%A`) and the other branches' version (`%B`). These three tokens are replaced with the names of temporary files that hold the contents of these versions when the command line is -built. +built. Additionally, %L will be replaced with the conflict marker +size (see below). The merge driver is expected to leave the result of the merge in the file named with `%A` by overwriting it, and exit with zero diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index 3b83dba1a0..37ce9a17fc 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -67,6 +67,7 @@ option can be used to override --squash. Synonyms to --stat and --no-stat; these are deprecated and will be removed in the future. +ifndef::git-pull[] -q:: --quiet:: Operate quietly. @@ -74,6 +75,7 @@ option can be used to override --squash. -v:: --verbose:: Be verbose. +endif::git-pull[] -X <option>:: --strategy-option=<option>:: diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 6e9baf8b38..81c0e6f184 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -225,26 +225,26 @@ endif::git-rev-list[] --all:: - Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the + Pretend as if all the refs in `refs/` are listed on the command line as '<commit>'. --branches[=pattern]:: - Pretend as if all the refs in `$GIT_DIR/refs/heads` are listed + Pretend as if all the refs in `refs/heads` are listed on the command line as '<commit>'. If `pattern` is given, limit branches to ones matching given shell glob. If pattern lacks '?', '*', or '[', '/*' at the end is implied. --tags[=pattern]:: - Pretend as if all the refs in `$GIT_DIR/refs/tags` are listed + Pretend as if all the refs in `refs/tags` are listed on the command line as '<commit>'. If `pattern` is given, limit tags to ones matching given shell glob. If pattern lacks '?', '*', or '[', '/*' at the end is implied. --remotes[=pattern]:: - Pretend as if all the refs in `$GIT_DIR/refs/remotes` are listed + Pretend as if all the refs in `refs/remotes` are listed on the command line as '<commit>'. If `pattern`is given, limit remote tracking branches to ones matching given shell glob. If pattern lacks '?', '*', or '[', '/*' at the end is implied. @@ -259,9 +259,9 @@ endif::git-rev-list[] ifndef::git-rev-list[] --bisect:: - Pretend as if the bad bisection ref `$GIT_DIR/refs/bisect/bad` + Pretend as if the bad bisection ref `refs/bisect/bad` was listed and as if it was followed by `--not` and the good - bisection refs `$GIT_DIR/refs/bisect/good-*` on the command + bisection refs `refs/bisect/good-*` on the command line. endif::git-rev-list[] @@ -561,10 +561,10 @@ Bisection Helpers Limit output to the one commit object which is roughly halfway between included and excluded commits. Note that the bad bisection ref -`$GIT_DIR/refs/bisect/bad` is added to the included commits (if it -exists) and the good bisection refs `$GIT_DIR/refs/bisect/good-*` are +`refs/bisect/bad` is added to the included commits (if it +exists) and the good bisection refs `refs/bisect/good-*` are added to the excluded commits (if they exist). Thus, supposing there -are no refs in `$GIT_DIR/refs/bisect/`, if +are no refs in `refs/bisect/`, if ----------------------------------------------------------------------- $ git rev-list --bisect foo ^bar ^baz @@ -585,7 +585,7 @@ one. --bisect-vars:: This calculates the same as `--bisect`, except that refs in -`$GIT_DIR/refs/bisect/` are not used, and except that this outputs +`refs/bisect/` are not used, and except that this outputs text ready to be eval'ed by the shell. These lines will assign the name of the midpoint revision to the variable `bisect_rev`, and the expected number of commits to be tested after `bisect_rev` is tested @@ -599,7 +599,7 @@ number of commits to be tested if `bisect_rev` turns out to be bad to This outputs all the commit objects between the included and excluded commits, ordered by their distance to the included and excluded -commits. Refs in `$GIT_DIR/refs/bisect/` are not used. The farthest +commits. Refs in `refs/bisect/` are not used. The farthest from them is displayed first. (This is the only one displayed by `--bisect`.) + diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 50f9e9ac17..312e3b2e2b 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -115,6 +115,9 @@ There are some macros to easily define options: `OPT__ABBREV(&int_var)`:: Add `\--abbrev[=<n>]`. +`OPT__COLOR(&int_var, description)`:: + Add `\--color[=<when>]` and `--no-color`. + `OPT__DRY_RUN(&int_var)`:: Add `-n, \--dry-run`. @@ -183,6 +186,15 @@ There are some macros to easily define options: arguments. Short options that happen to be digits take precedence over it. +`OPT_COLOR_FLAG(short, long, &int_var, description)`:: + Introduce an option that takes an optional argument that can + have one of three values: "always", "never", or "auto". If the + argument is not given, it defaults to "always". The `--no-` form + works like `--long=never`; it cannot take an argument. If + "always", set `int_var` to 1; if "never", set `int_var` to 0; if + "auto", set `int_var` to 1 if stdout is a tty or a pager, + 0 otherwise. + The last element of the array must be `OPT_END()`. diff --git a/Documentation/technical/api-run-command.txt b/Documentation/technical/api-run-command.txt index 68bf4cad8b..44876fa703 100644 --- a/Documentation/technical/api-run-command.txt +++ b/Documentation/technical/api-run-command.txt @@ -64,8 +64,8 @@ The functions above do the following: `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. + async` that specifies the details and returns a set of pipe FDs + for communication with the function. See below for details. `finish_async`:: @@ -135,7 +135,7 @@ stderr as follows: .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. + .err: The FD must be writable; it becomes child's stderr. The specified FD is closed by start_command(), even if it fails to run the sub-process! @@ -180,17 +180,47 @@ The caller: 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; +4. processes communicates with proc through .in and .out; +5. closes .in and .out; 6. calls finish_async(). +The members .in, .out are used to provide a set of fd's for +communication between the caller and the callee as follows: + +. Specify 0 to have no file descriptor passed. The callee will + receive -1 in the corresponding argument. + +. Specify < 0 to have a pipe allocated; start_async() replaces + with 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 function's + in argument. + + .out: Returns the readable pipe end from which the caller + reads; the writable end of the pipe becomes the function's + out argument. + + The caller of start_async() must close the returned FDs after it + has completed reading from/writing from them. + +. Specify a file descriptor > 0 to be used by the function: + + .in: The FD must be readable; it becomes the function's in. + .out: The FD must be writable; it becomes the function's out. + + The specified FD is closed by start_async(), even if it fails to + run the function. + The function pointer in .proc has the following signature: - int proc(int fd, void *data); + int proc(int in, int out, 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. +. in, out specifies a set of file descriptors to which the function + must read/write the data that it needs/produces. The function + *must* close these descriptors before it returns. A descriptor + may be -1 if the caller did not configure a descriptor for that + direction. . data is the value that the caller has specified in the .data member of struct async. @@ -205,8 +235,8 @@ 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. + etc.) in a way that the caller notices; in other words, .in and .out + are the only communication channels to the caller. . It must not change the program's state that the caller of the facility also uses. |