be huge by saying "no common commits", but this was an unnecessary
noise; it is already known by the user anyway.
+* "git-http-fetch" would have segfaulted when pack idx file retrieved
+ from the other side was corrupt.
+
+* "git-index-pack" used too much memory when dealing with a deep delta chain.
+
* "git-mailinfo" (hence "git-am") did not correctly handle in-body [PATCH]
line to override the commit title taken from the mail Subject header.
* "git-rebase -i -p" lost parents that are not involved in the history
being rewritten.
-Contains other various documentation fixes.
+* "git-rm" lost track of where the index file was when GIT_DIR was
+ specified as a relative path.
---
-exec >/var/tmp/1
-echo O=$(git describe maint)
-O=v1.5.6.3-21-gebcce31
-git shortlog --no-merges $O..maint
+* "git-rev-list --quiet" was not quiet as advertised.
+
+Contains other various documentation fixes.
By default, packfiles created with this version uses delta-base-offset
encoding introduced in v1.4.4. Pack idx files are using version 2 that
allows larger packs and added robustness thanks to its CRC checking,
-introduced in v1.5.2.
+introduced in v1.5.2 and v1.4.4.5. If you want to keep your repositories
+backwards compatible past these versions, set repack.useDeltaBaseOffset
+to false or pack.indexVersion to 1, respectively.
GIT_CONFIG, which was only documented as affecting "git config", but
actually affected all git commands, now only affects "git config".
* git-archive can be told to omit certain paths from its output using
export-ignore attributes.
+* git-archive uses the zlib default compression level when creating
+ zip archive.
+
* With -v option, git-branch describes the remote tracking statistics
similar to the way git-checkout reports by how many commits your branch
is ahead/behind.
* git-clone can clone from a remote whose URL would be rewritten by
configuration stored in $HOME/.gitconfig now.
+* git-cvsserver learned to respond to "cvs co -c".
+
* git-diff --check now checks leftover merge conflict markers.
* When remote side used to have branch 'foo' and git-fetch finds that now
* fast-export learned to export and import marks file; this can be used to
interface with fast-import incrementally.
+* fast-import and fast-export learned to export and import gitlinks.
+
* git-rebase records the original tip of branch in ORIG_HEAD before it is
rewound.
---
exec >/var/tmp/1
-O=v1.5.6.3-436-g1f8dc67
+O=v1.5.6.4-432-g6796399
echo O=$(git describe refs/heads/master)
git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint
<tt>120000</tt>: A symlink, the content of the file will be the link target.\r
</p>\r
</li>\r
+<li>\r
+<p>\r
+<tt>160000</tt>: A gitlink, SHA-1 of the object refers to a commit in\r
+ another repository. Git links can only be specified by SHA or through\r
+ a commit mark. They are used to implement submodules.\r
+</p>\r
+</li>\r
</ul></div>\r
<div class="para"><p>In both formats <tt><path></tt> is the complete path of the file to be added\r
(if not already existing) or modified (if already existing).</p></div>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 2008-07-06 05:16:45 UTC\r
+Last updated 2008-07-20 01:23:33 UTC\r
</div>\r
</div>\r
</body>\r
what you want.
* `100755` or `755`: A normal, but executable, file.
* `120000`: A symlink, the content of the file will be the link target.
+* `160000`: A gitlink, SHA-1 of the object refers to a commit in
+ another repository. Git links can only be specified by SHA or through
+ a commit mark. They are used to implement submodules.
In both formats `<path>` is the complete path of the file to be added
(if not already existing) or modified (if already existing).
<div class="sectionbody">\r
<div class="para"><p>A merge is always between the current <tt>HEAD</tt> and one or more\r
commits (usually, branch head or tag), and the index file must\r
-exactly match the\r
-tree of <tt>HEAD</tt> commit (i.e. the contents of the last commit) when\r
-it happens. In other words, <tt>git diff --cached HEAD</tt> must\r
-report no changes.</p></div>\r
-<div class="admonitionblock">\r
-<table><tr>\r
-<td class="icon">\r
-<div class="title">Note</div>\r
-</td>\r
-<td class="content">This is a bit of a lie. In certain special cases, your index is\r
-allowed to be different from the tree of the <tt>HEAD</tt> commit. The most\r
-notable case is when your <tt>HEAD</tt> commit is already ahead of what\r
-is being merged, in which case your index can have arbitrary\r
-differences from your <tt>HEAD</tt> commit. Also, your index entries\r
-may have differences from your <tt>HEAD</tt> commit that match\r
-the result of a trivial merge (e.g. you received the same patch\r
-from an external source to produce the same result as what you are\r
-merging). For example, if a path did not exist in the common\r
-ancestor and your head commit but exists in the tree you are\r
-merging into your repository, and if you already happen to have\r
-that path exactly in your index, the merge does not have to\r
-fail.</td>\r
-</tr></table>\r
-</div>\r
-<div class="para"><p>Otherwise, merge will refuse to do any harm to your repository\r
-(that is, it may fetch the objects from remote, and it may even\r
-update the local branch used to keep track of the remote branch\r
-with <tt>git pull remote rbranch:lbranch</tt>, but your working tree,\r
-<tt>.git/HEAD</tt> pointer and index file are left intact). In addition,\r
-merge always sets <tt>.git/ORIG_HEAD</tt> to the original state of HEAD so\r
-a problematic merge can be removed by using <tt>git reset ORIG_HEAD</tt>.</p></div>\r
-<div class="para"><p>You may have local modifications in the working tree files. In\r
-other words, <em>git-diff</em> is allowed to report changes.\r
-However, the merge uses your working tree as the working area,\r
-and in order to prevent the merge operation from losing such\r
-changes, it makes sure that they do not interfere with the\r
-merge. Those complex tables in read-tree documentation define\r
-what it means for a path to "interfere with the merge". And if\r
-your local modifications interfere with the merge, again, it\r
-stops before touching anything.</p></div>\r
-<div class="para"><p>So in the above two "failed merge" case, you do not have to\r
-worry about loss of data --- you simply were not ready to do\r
-a merge, so no merge happened at all. You may want to finish\r
-whatever you were in the middle of doing, and retry the same\r
-pull after you are done and ready.</p></div>\r
-<div class="para"><p>When things cleanly merge, these things happen:</p></div>\r
+match the tree of <tt>HEAD</tt> commit (i.e. the contents of the last commit)\r
+when it starts out. In other words, <tt>git diff --cached HEAD</tt> must\r
+report no changes. (One exception is when the changed index\r
+entries are already in the same state that would result from\r
+the merge anyway.)</p></div>\r
+<div class="para"><p>Three kinds of merge can happen:</p></div>\r
+<div class="ilist"><ul>\r
+<li>\r
+<p>\r
+The merged commit is already contained in <tt>HEAD</tt>. This is the\r
+ simplest case, called "Already up-to-date."\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>HEAD</tt> is already contained in the merged commit. This is the\r
+ most common case especially when involved through <em>git pull</em>:\r
+ you are tracking an upstream repository, committed no local\r
+ changes and now you want to update to a newer upstream revision.\r
+ Your <tt>HEAD</tt> (and the index) is updated to at point the merged\r
+ commit, without creating an extra merge commit. This is\r
+ called "Fast-forward".\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Both the merged commit and <tt>HEAD</tt> are independent and must be\r
+ tied together by a merge commit that has them both as its parents.\r
+ The rest of this section describes this "True merge" case.\r
+</p>\r
+</li>\r
+</ul></div>\r
+<div class="para"><p>The chosen merge strategy merges the two commits into a single\r
+new source tree.\r
+When things cleanly merge, these things happen:</p></div>\r
<div class="olist"><ol>\r
<li>\r
<p>\r
<p>\r
Decide not to merge. The only clean-up you need are to reset\r
the index file to the <tt>HEAD</tt> commit to reverse 2. and to clean\r
- up working tree changes made by 2. and 3.; <em>git-reset</em> can\r
+ up working tree changes made by 2. and 3.; <em>git-reset --hard</em> can\r
be used for this.\r
</p>\r
</li>\r
<li>\r
<p>\r
Resolve the conflicts. <tt>git diff</tt> would report only the\r
- conflicting paths because of the above 2. and 3. Edit the\r
- working tree files into a desirable shape, <em>git-add</em> or <em>git-rm</em>\r
+ conflicting paths because of the above 2. and 3.\r
+ Edit the working tree files into a desirable shape\r
+ (<em>git mergetool</em> can ease this task), <em>git-add</em> or <em>git-rm</em>\r
them, to make the index file contain what the merge result\r
should be, and run <em>git-commit</em> to commit the result.\r
</p>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 2008-07-15 15:48:34 UTC\r
+Last updated 2008-07-20 01:23:33 UTC\r
</div>\r
</div>\r
</body>\r
A merge is always between the current `HEAD` and one or more
commits (usually, branch head or tag), and the index file must
-exactly match the
-tree of `HEAD` commit (i.e. the contents of the last commit) when
-it happens. In other words, `git diff --cached HEAD` must
-report no changes.
-
-[NOTE]
-This is a bit of a lie. In certain special cases, your index is
-allowed to be different from the tree of the `HEAD` commit. The most
-notable case is when your `HEAD` commit is already ahead of what
-is being merged, in which case your index can have arbitrary
-differences from your `HEAD` commit. Also, your index entries
-may have differences from your `HEAD` commit that match
-the result of a trivial merge (e.g. you received the same patch
-from an external source to produce the same result as what you are
-merging). For example, if a path did not exist in the common
-ancestor and your head commit but exists in the tree you are
-merging into your repository, and if you already happen to have
-that path exactly in your index, the merge does not have to
-fail.
-
-Otherwise, merge will refuse to do any harm to your repository
-(that is, it may fetch the objects from remote, and it may even
-update the local branch used to keep track of the remote branch
-with `git pull remote rbranch:lbranch`, but your working tree,
-`.git/HEAD` pointer and index file are left intact). In addition,
-merge always sets `.git/ORIG_HEAD` to the original state of HEAD so
-a problematic merge can be removed by using `git reset ORIG_HEAD`.
-
-You may have local modifications in the working tree files. In
-other words, 'git-diff' is allowed to report changes.
-However, the merge uses your working tree as the working area,
-and in order to prevent the merge operation from losing such
-changes, it makes sure that they do not interfere with the
-merge. Those complex tables in read-tree documentation define
-what it means for a path to "interfere with the merge". And if
-your local modifications interfere with the merge, again, it
-stops before touching anything.
-
-So in the above two "failed merge" case, you do not have to
-worry about loss of data --- you simply were not ready to do
-a merge, so no merge happened at all. You may want to finish
-whatever you were in the middle of doing, and retry the same
-pull after you are done and ready.
-
+match the tree of `HEAD` commit (i.e. the contents of the last commit)
+when it starts out. In other words, `git diff --cached HEAD` must
+report no changes. (One exception is when the changed index
+entries are already in the same state that would result from
+the merge anyway.)
+
+Three kinds of merge can happen:
+
+* The merged commit is already contained in `HEAD`. This is the
+ simplest case, called "Already up-to-date."
+
+* `HEAD` is already contained in the merged commit. This is the
+ most common case especially when involved through 'git pull':
+ you are tracking an upstream repository, committed no local
+ changes and now you want to update to a newer upstream revision.
+ Your `HEAD` (and the index) is updated to at point the merged
+ commit, without creating an extra merge commit. This is
+ called "Fast-forward".
+
+* Both the merged commit and `HEAD` are independent and must be
+ tied together by a merge commit that has them both as its parents.
+ The rest of this section describes this "True merge" case.
+
+The chosen merge strategy merges the two commits into a single
+new source tree.
When things cleanly merge, these things happen:
1. The results are updated both in the index file and in your
* Decide not to merge. The only clean-up you need are to reset
the index file to the `HEAD` commit to reverse 2. and to clean
- up working tree changes made by 2. and 3.; 'git-reset' can
+ up working tree changes made by 2. and 3.; 'git-reset --hard' can
be used for this.
* Resolve the conflicts. `git diff` would report only the
- conflicting paths because of the above 2. and 3. Edit the
- working tree files into a desirable shape, 'git-add' or 'git-rm'
+ conflicting paths because of the above 2. and 3.
+ Edit the working tree files into a desirable shape
+ ('git mergetool' can ease this task), 'git-add' or 'git-rm'
them, to make the index file contain what the merge result
should be, and run 'git-commit' to commit the result.
</div>\r
<h2 id="_description">DESCRIPTION</h2>\r
<div class="sectionbody">\r
-<div class="para"><p>Submodules are a special kind of tree entries which refer to a particular tree\r
-state in another repository. The tree entry describes\r
-the existence of a submodule with the given name and the exact revision that\r
-should be used, while an entry in <tt>.gitmodules</tt> file gives the location of\r
-the repository.</p></div>\r
-<div class="para"><p>When checked out, submodules will maintain their own independent repositories\r
-within their directories; the only link between the submodule and the "parent\r
-project" is the tree entry within the parent project mentioned above.</p></div>\r
-<div class="para"><p>This command will manage the tree entries and contents of the gitmodules file\r
-for you, as well as inspecting the status of your submodules and updating them.\r
-When adding a new submodule to the tree, the <em>add</em> subcommand is to be used.\r
-However, when pulling a tree containing submodules, these will not be checked\r
-out by default; the <em>init</em> and <em>update</em> subcommands will maintain submodules\r
-checked out and at appropriate revision in your working tree. You can inspect\r
-the current status of your submodules using the <em>submodule</em> subcommand and get\r
-an overview of changes <em>update</em> would perform using the <em>summary</em> subcommand.</p></div>\r
+<div class="para"><p>Submodules allow foreign repositories to be embedded within\r
+a dedicated subdirectory of the source tree, always pointed\r
+at a particular commit.</p></div>\r
+<div class="para"><p>They are not to be confused with remotes, which are meant mainly\r
+for branches of the same project; submodules are meant for\r
+different projects you would like to make part of your source tree,\r
+while the history of the two projects still stays completely\r
+independent and you cannot modify the contents of the submodule\r
+from within the main project.\r
+If you want to merge the project histories and want to treat the\r
+aggregated whole as a single project from then on, you may want to\r
+add a remote for the other project and use the <em>subtree</em> merge strategy,\r
+instead of treating the other project as a submodule. Directories\r
+that come from both projects can be cloned and checked out as a whole\r
+if you choose to go that route.</p></div>\r
+<div class="para"><p>Submodules are composed from a so-called <tt>gitlink</tt> tree entry\r
+in the main repository that refers to a particular commit object\r
+within the inner repository that is completely separate.\r
+A record in the <tt>.gitmodules</tt> file at the root of the source\r
+tree assigns a logical name to the submodule and describes\r
+the default URL the submodule shall be cloned from.\r
+The logical name can be used for overriding this URL within your\r
+local repository configuration (see <em>submodule init</em>).</p></div>\r
+<div class="para"><p>This command will manage the tree entries and contents of the\r
+gitmodules file for you, as well as inspect the status of your\r
+submodules and update them.\r
+When adding a new submodule to the tree, the <em>add</em> subcommand\r
+is to be used. However, when pulling a tree containing submodules,\r
+these will not be checked out by default;\r
+the <em>init</em> and <em>update</em> subcommands will maintain submodules\r
+checked out and at appropriate revision in your working tree.\r
+You can briefly inspect the up-to-date status of your submodules\r
+using the <em>status</em> subcommand and get a detailed overview of the\r
+difference between the index and checkouts using the <em>summary</em>\r
+subcommand.</p></div>\r
</div>\r
<h2 id="_commands">COMMANDS</h2>\r
<div class="sectionbody">\r
</dt>\r
<dd>\r
<p>\r
- Initialize the submodules, i.e. register in .git/config each submodule\r
- name and url found in .gitmodules. The key used in .git/config is\r
- <tt>submodule.$name.url</tt>. This command does not alter existing information\r
- in .git/config.\r
+ Initialize the submodules, i.e. register each submodule name\r
+ and url found in .gitmodules into .git/config.\r
+ The key used in .git/config is <tt>submodule.$name.url</tt>.\r
+ This command does not alter existing information in .git/config.\r
+ You can then customize the submodule clone URLs in .git/config\r
+ for your local setup and proceed to <em>git submodule update</em>;\r
+ you can also just use <em>git submodule update --init</em> without\r
+ the explicit <em>init</em> step if you do not intend to customize\r
+ any submodule locations.\r
</p>\r
</dd>\r
<dt>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 2008-07-17 08:08:29 UTC\r
+Last updated 2008-07-20 01:23:35 UTC\r
</div>\r
</div>\r
</body>\r
DESCRIPTION
-----------
-Submodules are a special kind of tree entries which refer to a particular tree
-state in another repository. The tree entry describes
-the existence of a submodule with the given name and the exact revision that
-should be used, while an entry in `.gitmodules` file gives the location of
-the repository.
-
-When checked out, submodules will maintain their own independent repositories
-within their directories; the only link between the submodule and the "parent
-project" is the tree entry within the parent project mentioned above.
-
-This command will manage the tree entries and contents of the gitmodules file
-for you, as well as inspecting the status of your submodules and updating them.
-When adding a new submodule to the tree, the 'add' subcommand is to be used.
-However, when pulling a tree containing submodules, these will not be checked
-out by default; the 'init' and 'update' subcommands will maintain submodules
-checked out and at appropriate revision in your working tree. You can inspect
-the current status of your submodules using the 'submodule' subcommand and get
-an overview of changes 'update' would perform using the 'summary' subcommand.
+Submodules allow foreign repositories to be embedded within
+a dedicated subdirectory of the source tree, always pointed
+at a particular commit.
+
+They are not to be confused with remotes, which are meant mainly
+for branches of the same project; submodules are meant for
+different projects you would like to make part of your source tree,
+while the history of the two projects still stays completely
+independent and you cannot modify the contents of the submodule
+from within the main project.
+If you want to merge the project histories and want to treat the
+aggregated whole as a single project from then on, you may want to
+add a remote for the other project and use the 'subtree' merge strategy,
+instead of treating the other project as a submodule. Directories
+that come from both projects can be cloned and checked out as a whole
+if you choose to go that route.
+
+Submodules are composed from a so-called `gitlink` tree entry
+in the main repository that refers to a particular commit object
+within the inner repository that is completely separate.
+A record in the `.gitmodules` file at the root of the source
+tree assigns a logical name to the submodule and describes
+the default URL the submodule shall be cloned from.
+The logical name can be used for overriding this URL within your
+local repository configuration (see 'submodule init').
+
+This command will manage the tree entries and contents of the
+gitmodules file for you, as well as inspect the status of your
+submodules and update them.
+When adding a new submodule to the tree, the 'add' subcommand
+is to be used. However, when pulling a tree containing submodules,
+these will not be checked out by default;
+the 'init' and 'update' subcommands will maintain submodules
+checked out and at appropriate revision in your working tree.
+You can briefly inspect the up-to-date status of your submodules
+using the 'status' subcommand and get a detailed overview of the
+difference between the index and checkouts using the 'summary'
+subcommand.
COMMANDS
repository. This command is the default command for 'git-submodule'.
init::
- Initialize the submodules, i.e. register in .git/config each submodule
- name and url found in .gitmodules. The key used in .git/config is
- `submodule.$name.url`. This command does not alter existing information
- in .git/config.
+ Initialize the submodules, i.e. register each submodule name
+ and url found in .gitmodules into .git/config.
+ The key used in .git/config is `submodule.$name.url`.
+ This command does not alter existing information in .git/config.
+ You can then customize the submodule clone URLs in .git/config
+ for your local setup and proceed to 'git submodule update';
+ you can also just use 'git submodule update --init' without
+ the explicit 'init' step if you do not intend to customize
+ any submodule locations.
update::
Update the registered submodules, i.e. clone missing submodules and
filesystem that has very slow lstat(2) system call\r
(e.g. cifs).\r
</p>\r
+<div class="para"><p>This option can be also used as a coarse file-level mechanism\r
+to ignore uncommitted changes in tracked files (akin to what\r
+<tt>.gitignore</tt> does for untracked files).\r
+You should remember that an explicit <em>git add</em> operation will\r
+still cause the file to be refreshed from the working tree.\r
+Git will fail (gracefully) in case it needs to modify this file\r
+in the index e.g. when merging in a commit;\r
+thus, in case the assumed-untracked file is changed upstream,\r
+you will need to handle the situation manually.</p></div>\r
</dd>\r
<dt>\r
-g\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 2008-07-06 05:17:06 UTC\r
+Last updated 2008-07-20 01:23:35 UTC\r
</div>\r
</div>\r
</body>\r
sometimes helpful when working with a big project on a
filesystem that has very slow lstat(2) system call
(e.g. cifs).
++
+This option can be also used as a coarse file-level mechanism
+to ignore uncommitted changes in tracked files (akin to what
+`.gitignore` does for untracked files).
+You should remember that an explicit 'git add' operation will
+still cause the file to be refreshed from the working tree.
+Git will fail (gracefully) in case it needs to modify this file
+in the index e.g. when merging in a commit;
+thus, in case the assumed-untracked file is changed upstream,
+you will need to handle the situation manually.
-g::
--again::
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 2008-07-14 03:12:31 UTC\r
+Last updated 2008-07-20 01:23:36 UTC\r
</div>\r
</div>\r
</body>\r
branch of the `git.git` repository.
Documentation for older releases are available here:
-* link:v1.5.6.3/git.html[documentation for release 1.5.6.3]
+* link:v1.5.6.4/git.html[documentation for release 1.5.6.4]
* release notes for
- link:RelNotes-1.5.6.3.txt[1.5.6.3].
- link:RelNotes-1.5.6.2.txt[1.5.6.2].
- link:RelNotes-1.5.6.1.txt[1.5.6.1].
+ link:RelNotes-1.5.6.4.txt[1.5.6.4],
+ link:RelNotes-1.5.6.3.txt[1.5.6.3],
+ link:RelNotes-1.5.6.2.txt[1.5.6.2],
+ link:RelNotes-1.5.6.1.txt[1.5.6.1],
link:RelNotes-1.5.6.txt[1.5.6].
* link:v1.5.5.4/git.html[documentation for release 1.5.5.4]
<h2 id="_description">DESCRIPTION</h2>\r
<div class="sectionbody">\r
<div class="para"><p>A <tt>gitignore</tt> file specifies intentionally untracked files that\r
-git should ignore. Each line in a <tt>gitignore</tt> file specifies a\r
-pattern.</p></div>\r
-<div class="para"><p>When deciding whether to ignore a path, git normally checks\r
+git should ignore.\r
+Note that all the <tt>gitignore</tt> files really concern only files\r
+that are not already tracked by git;\r
+in order to ignore uncommitted changes in already tracked files,\r
+please refer to the <em>git update-index --assume-unchanged</em>\r
+documentation.</p></div>\r
+<div class="para"><p>Each line in a <tt>gitignore</tt> file specifies a pattern.\r
+When deciding whether to ignore a path, git normally checks\r
<tt>gitignore</tt> patterns from multiple sources, with the following\r
order of precedence, from highest to lowest (within one level of\r
precedence, the last matching pattern decides the outcome):</p></div>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 2008-07-06 05:17:10 UTC\r
+Last updated 2008-07-20 01:23:36 UTC\r
</div>\r
</div>\r
</body>\r
-----------
A `gitignore` file specifies intentionally untracked files that
-git should ignore. Each line in a `gitignore` file specifies a
-pattern.
-
+git should ignore.
+Note that all the `gitignore` files really concern only files
+that are not already tracked by git;
+in order to ignore uncommitted changes in already tracked files,
+please refer to the 'git update-index --assume-unchanged'
+documentation.
+
+Each line in a `gitignore` file specifies a pattern.
When deciding whether to ignore a path, git normally checks
`gitignore` patterns from multiple sources, with the following
order of precedence, from highest to lowest (within one level of
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\r
<head>\r
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />\r
-<meta name="generator" content="AsciiDoc 7.0.2" />\r
+<meta name="generator" content="AsciiDoc 8.2.5" />\r
<style type="text/css">\r
/* Debug borders */\r
p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {\r
margin: 1em 5% 1em 5%;\r
}\r
\r
-a { color: blue; }\r
-a:visited { color: fuchsia; }\r
+a {\r
+ color: blue;\r
+ text-decoration: underline;\r
+}\r
+a:visited {\r
+ color: fuchsia;\r
+}\r
\r
em {\r
font-style: italic;\r
line-height: 1.3;\r
}\r
\r
-h1 {\r
+h1, h2, h3 {\r
border-bottom: 2px solid silver;\r
}\r
h2 {\r
- border-bottom: 2px solid silver;\r
padding-top: 0.5em;\r
}\r
+h3 {\r
+ float: left;\r
+}\r
+h3 + * {\r
+ clear: left;\r
+}\r
\r
div.sectionbody {\r
font-family: serif;\r
color: #527bbd;\r
font-family: sans-serif;\r
font-weight: bold;\r
- font-size: 1.2em;\r
+ font-size: 1.1em;\r
}\r
span#email {\r
}\r
padding: 0.5em;\r
}\r
\r
+div.listingblock {\r
+ margin-right: 0%;\r
+}\r
div.listingblock > div.content {\r
border: 1px solid silver;\r
background: #f4f4f4;\r
div.quoteblock > div.content {\r
padding-left: 2.0em;\r
}\r
-div.quoteblock .attribution {\r
+\r
+div.attribution {\r
text-align: right;\r
}\r
+div.verseblock + div.attribution {\r
+ text-align: left;\r
+}\r
\r
div.admonitionblock .icon {\r
vertical-align: top;\r
ul, ol {\r
list-style-position: outside;\r
}\r
-ol.olist2 {\r
+div.olist2 ol {\r
list-style-type: lower-alpha;\r
}\r
\r
div.tableblock > table {\r
- border-color: #527bbd;\r
- border-width: 3px;\r
+ border: 3px solid #527bbd;\r
}\r
thead {\r
font-family: sans-serif;\r
margin-top: 0.8em;\r
margin-bottom: 0.8em;\r
}\r
+div.hlist td {\r
+ padding-bottom: 5px;\r
+}\r
td.hlist1 {\r
vertical-align: top;\r
font-style: italic;\r
@media print {\r
div#footer-badges { display: none; }\r
}\r
+\r
+div#toctitle {\r
+ color: #527bbd;\r
+ font-family: sans-serif;\r
+ font-size: 1.1em;\r
+ font-weight: bold;\r
+ margin-top: 1.0em;\r
+ margin-bottom: 0.1em;\r
+}\r
+\r
+div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {\r
+ margin-top: 0;\r
+ margin-bottom: 0;\r
+}\r
+div.toclevel2 {\r
+ margin-left: 2em;\r
+ font-size: 0.9em;\r
+}\r
+div.toclevel3 {\r
+ margin-left: 4em;\r
+ font-size: 0.9em;\r
+}\r
+div.toclevel4 {\r
+ margin-left: 6em;\r
+ font-size: 0.9em;\r
+}\r
/* Workarounds for IE6's broken and incomplete CSS2. */\r
\r
div.sidebar-content {\r
border-left: 2px solid silver;\r
padding-left: 0.5em;\r
}\r
+\r
+/* IE6 sets dynamically generated links as visited. */\r
+div#toc a:visited { color: blue; }\r
</style>\r
<title>run-command API</title>\r
</head>\r
</div>\r
<div id="preamble">\r
<div class="sectionbody">\r
-<p>The run-command API offers a versatile tool to run sub-processes with\r
+<div class="para"><p>The run-command API offers a versatile tool to run sub-processes with\r
redirected input and output as well as with a modified environment\r
-and an alternate current directory.</p>\r
-<p>A similar API offers the capability to run a function asynchronously,\r
+and an alternate current directory.</p></div>\r
+<div class="para"><p>A similar API offers the capability to run a function asynchronously,\r
which is primarily used to capture the output that the function\r
-produces in the caller in order to process it.</p>\r
+produces in the caller in order to process it.</p></div>\r
</div>\r
</div>\r
-<h2>Functions</h2>\r
+<h2 id="_functions">Functions</h2>\r
<div class="sectionbody">\r
-<dl>\r
+<div class="vlist"><dl>\r
<dt>\r
<tt>start_command</tt>\r
</dt>\r
</p>\r
</dd>\r
<dt>\r
-<tt>run_command_v_opt</tt>, <tt>run_command_v_opt_dir</tt>, <tt>run_command_v_opt_cd_env</tt>\r
+<tt>run_command_v_opt</tt>, <tt>run_command_v_opt_cd</tt>, <tt>run_command_v_opt_cd_env</tt>\r
</dt>\r
<dd>\r
<p>\r
started with start_async().\r
</p>\r
</dd>\r
-</dl>\r
+</dl></div>\r
</div>\r
-<h2>Data structures</h2>\r
+<h2 id="_data_structures">Data structures</h2>\r
<div class="sectionbody">\r
-<ul>\r
+<div class="ilist"><ul>\r
<li>\r
<p>\r
<tt>struct child_process</tt>\r
</p>\r
</li>\r
-</ul>\r
-<p>This describes the arguments, redirections, and environment of a\r
-command to run in a sub-process.</p>\r
-<p>The caller:</p>\r
-<ol>\r
+</ul></div>\r
+<div class="para"><p>This describes the arguments, redirections, and environment of a\r
+command to run in a sub-process.</p></div>\r
+<div class="para"><p>The caller:</p></div>\r
+<div class="olist"><ol>\r
<li>\r
<p>\r
allocates and clears (memset(&chld, 0, sizeof(chld));) a\r
calls finish_command().\r
</p>\r
</li>\r
-</ol>\r
-<p>The .argv member is set up as an array of string pointers (NULL\r
+</ol></div>\r
+<div class="para"><p>The .argv member is set up as an array of string pointers (NULL\r
terminated), of which .argv[0] is the program name to run (usually\r
without a path). If the command to run is a git command, set argv[0] to\r
-the command name without the <em>git-</em> prefix and set .git_cmd = 1.</p>\r
-<p>The members .in, .out, .err are used to redirect stdin, stdout,\r
-stderr as follows:</p>\r
-<ol>\r
+the command name without the <em>git-</em> prefix and set .git_cmd = 1.</p></div>\r
+<div class="para"><p>The members .in, .out, .err are used to redirect stdin, stdout,\r
+stderr as follows:</p></div>\r
+<div class="olist"><ol>\r
<li>\r
<p>\r
Specify 0 to request no special redirection. No new file descriptor\r
redirected.</tt></pre>\r
</div></div>\r
</li>\r
-</ol>\r
-<p>To modify the environment of the sub-process, specify an array of\r
-string pointers (NULL terminated) in .env:</p>\r
-<ol>\r
+</ol></div>\r
+<div class="para"><p>To modify the environment of the sub-process, specify an array of\r
+string pointers (NULL terminated) in .env:</p></div>\r
+<div class="olist"><ol>\r
<li>\r
<p>\r
If the string is of the form "VAR=value", i.e. it contains <em>=</em>\r
variable that will be removed from the child process's environment.\r
</p>\r
</li>\r
-</ol>\r
-<p>To specify a new initial working directory for the sub-process,\r
-specify it in the .dir member.</p>\r
-<ul>\r
+</ol></div>\r
+<div class="para"><p>To specify a new initial working directory for the sub-process,\r
+specify it in the .dir member.</p></div>\r
+<div class="ilist"><ul>\r
<li>\r
<p>\r
<tt>struct async</tt>\r
</p>\r
</li>\r
-</ul>\r
-<p>This describes a function to run asynchronously, whose purpose is\r
-to produce output that the caller reads.</p>\r
-<p>The caller:</p>\r
-<ol>\r
+</ul></div>\r
+<div class="para"><p>This describes a function to run asynchronously, whose purpose is\r
+to produce output that the caller reads.</p></div>\r
+<div class="para"><p>The caller:</p></div>\r
+<div class="olist"><ol>\r
<li>\r
<p>\r
allocates and clears (memset(&asy, 0, sizeof(asy));) a\r
calls finish_async().\r
</p>\r
</li>\r
-</ol>\r
-<p>The function pointer in .proc has the following signature:</p>\r
+</ol></div>\r
+<div class="para"><p>The function pointer in .proc has the following signature:</p></div>\r
<div class="literalblock">\r
<div class="content">\r
<pre><tt>int proc(int fd, void *data);</tt></pre>\r
</div></div>\r
-<ol>\r
+<div class="olist"><ol>\r
<li>\r
<p>\r
fd specifies a writable file descriptor to which the function must\r
report failure as well.\r
</p>\r
</li>\r
-</ol>\r
-<p>There are serious restrictions on what the asynchronous function can do\r
+</ol></div>\r
+<div class="para"><p>There are serious restrictions on what the asynchronous function can do\r
because this facility is implemented by a pipe to a forked process on\r
-UNIX, but by a thread in the same address space on Windows:</p>\r
-<ol>\r
+UNIX, but by a thread in the same address space on Windows:</p></div>\r
+<div class="olist"><ol>\r
<li>\r
<p>\r
It cannot change the program's state (global variables, environment,\r
facility also uses.\r
</p>\r
</li>\r
-</ol>\r
+</ol></div>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 02-Jul-2008 03:02:22 UTC\r
+Last updated 2008-07-20 01:23:36 UTC\r
</div>\r
</div>\r
</body>\r
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`::
+`run_command_v_opt`, `run_command_v_opt_cd`, `run_command_v_opt_cd_env`::
Convenience functions that encapsulate a sequence of
start_command() followed by finish_command(). The argument argv
projects / git.git / commitdiff