<h2>DESCRIPTION</h2>\r
<div class="sectionbody">\r
<p>Runs <tt>git-fetch</tt> with the given parameters, and calls <tt>git-merge</tt>\r
-to merge the retrieved head(s) into the current branch.</p>\r
+to merge the retrieved head(s) into the current branch.\r
+With <tt>--rebase</tt>, calls <tt>git-rebase</tt> instead of <tt>git-merge</tt>.</p>\r
<p>Note that you can use <tt>.</tt> (current directory) as the\r
<repository> to pull from the local repository — this is useful\r
when merging local branches into the current branch.</p>\r
</dl>\r
<dl>\r
<dt>\r
+--rebase\r
+</dt>\r
+<dd>\r
+<p>\r
+ Instead of a merge, perform a rebase after fetching. If\r
+ there is a remote ref for the upstream branch, and this branch\r
+ was rebased since last fetched, the rebase uses that information\r
+ to avoid rebasing non-local changes. To make this the default\r
+ for branch <tt><name></tt>, set configuration <tt>branch.<name>.rebase</tt>\r
+ to <tt>true</tt>.\r
+</p>\r
+<p><strong>NOTE:</strong> This is a potentially _dangerous_ mode of operation.\r
+It rewrites history, which does not bode well when you\r
+published that history already. Do <strong>not</strong> use this option\r
+unless you have read <a href="git-rebase.html">git-rebase(1)</a> carefully.</p>\r
+</dd>\r
+<dt>\r
+--no-rebase\r
+</dt>\r
+<dd>\r
+<p>\r
+ Override earlier --rebase.\r
+</p>\r
+</dd>\r
+<dt>\r
-q, --quiet\r
</dt>\r
<dd>\r
branches.\r
</p>\r
</dd>\r
-<dt>\r
---rebase\r
-</dt>\r
-<dd>\r
-<p>\r
- Instead of a merge, perform a rebase after fetching. If\r
- there is a remote ref for the upstream branch, and this branch\r
- was rebased since last fetched, the rebase uses that information\r
- to avoid rebasing non-local changes.\r
-</p>\r
-<p><strong>NOTE:</strong> This is a potentially _dangerous_ mode of operation.\r
-It rewrites history, which does not bode well when you\r
-published that history already. Do <strong>not</strong> use this option\r
-unless you have read <a href="git-rebase.html">git-rebase(1)</a> carefully.</p>\r
-</dd>\r
-<dt>\r
---no-rebase\r
-</dt>\r
-<dd>\r
-<p>\r
- Override earlier --rebase.\r
-</p>\r
-</dd>\r
</dl>\r
</div>\r
<h2>DEFAULT BEHAVIOUR</h2>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 12-Feb-2008 03:18:05 UTC\r
+Last updated 20-Feb-2008 10:44:09 UTC\r
</div>\r
</div>\r
</body>\r
-----------
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
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
\--no-rebase::
Override earlier \--rebase.
+include::fetch-options.txt[]
+
+include::pull-fetch-param.txt[]
+
+include::urls-remotes.txt[]
+
+include::merge-strategies.txt[]
+
DEFAULT BEHAVIOUR
-----------------
even if it does not result in a fast forward update.</p>\r
<p>Note: If no explicit refspec is found, (that is neither\r
on the command line nor in any Push line of the\r
-corresponding remotes file---see below), then all the\r
-heads that exist both on the local side and on the remote\r
-side are updated.</p>\r
+corresponding remotes file---see below), then "matching" heads are\r
+pushed: for every head that exists on the local side, the remote side is\r
+updated if a head of the same name already exists on the remote side.</p>\r
<p><tt>tag <tag></tt> means the same as <tt>refs/tags/<tag>:refs/tags/<tag></tt>.</p>\r
<p>A parameter <ref> without a colon pushes the <ref> from the source\r
repository to the destination repository under the same name.</p>\r
Pull: refs/heads/<head>:<remote></tt></pre>\r
</div></div>\r
</div>\r
+<h2>OUTPUT</h2>\r
+<div class="sectionbody">\r
+<p>The output of "git push" depends on the transport method used; this\r
+section describes the output when pushing over the git protocol (either\r
+locally or via ssh).</p>\r
+<p>The status of the push is output in tabular form, with each line\r
+representing the status of a single ref. Each line is of the form:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt> <flag> <summary> <from> -> <to> (<reason>)</tt></pre>\r
+</div></div>\r
+<dl>\r
+<dt>\r
+flag\r
+</dt>\r
+<dd>\r
+<p>\r
+ A single character indicating the status of the ref. This is\r
+ blank for a successfully pushed ref, <tt>!</tt> for a ref that was\r
+ rejected or failed to push, and <em>=</em> for a ref that was up to\r
+ date and did not need pushing (note that the status of up to\r
+ date refs is shown only when <tt>git push</tt> is running verbosely).\r
+</p>\r
+</dd>\r
+<dt>\r
+summary\r
+</dt>\r
+<dd>\r
+<p>\r
+ For a successfully pushed ref, the summary shows the old and new\r
+ values of the ref in a form suitable for using as an argument to\r
+ <tt>git log</tt> (this is <tt><old>..<new></tt> in most cases, and\r
+ <tt><old>…<new></tt> for forced non-fast forward updates). For a\r
+ failed update, more details are given for the failure.\r
+ The string <tt>rejected</tt> indicates that git did not try to send the\r
+ ref at all (typically because it is not a fast forward). The\r
+ string <tt>remote rejected</tt> indicates that the remote end refused\r
+ the update; this rejection is typically caused by a hook on the\r
+ remote side. The string <tt>remote failure</tt> indicates that the\r
+ remote end did not report the successful update of the ref\r
+ (perhaps because of a temporary error on the remote side, a\r
+ break in the network connection, or other transient error).\r
+</p>\r
+</dd>\r
+<dt>\r
+from\r
+</dt>\r
+<dd>\r
+<p>\r
+ The name of the local ref being pushed, minus its\r
+ <tt>refs/<type>/</tt> prefix. In the case of deletion, the\r
+ name of the local ref is omitted.\r
+</p>\r
+</dd>\r
+<dt>\r
+to\r
+</dt>\r
+<dd>\r
+<p>\r
+ The name of the remote ref being updated, minus its\r
+ <tt>refs/<type>/</tt> prefix.\r
+</p>\r
+</dd>\r
+<dt>\r
+reason\r
+</dt>\r
+<dd>\r
+<p>\r
+ A human-readable explanation. In the case of successfully pushed\r
+ refs, no explanation is needed. For a failed ref, the reason for\r
+ failure is described.\r
+</p>\r
+</dd>\r
+</dl>\r
+</div>\r
<h2>Examples</h2>\r
<div class="sectionbody">\r
<dl>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 07-Jan-2008 07:50:37 UTC\r
+Last updated 20-Feb-2008 10:44:09 UTC\r
</div>\r
</div>\r
</body>\r
+
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>`.
+
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
--------
</li>\r
<li>\r
<p>\r
+<a href="api-remote.html">Remotes configuration API</a>\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
<a href="api-revision-walking.html">revision walking API</a>\r
</p>\r
</li>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 07-Jan-2008 07:51:30 UTC\r
+Last updated 20-Feb-2008 10:44:10 UTC\r
</div>\r
</div>\r
</body>\r
* link:api-parse-options.html[parse-options API]
* link:api-path-list.html[path-list API]
* link:api-quote.html[quote API]
+* link:api-remote.html[Remotes configuration API]
* link:api-revision-walking.html[revision walking API]
* link:api-run-command.html[run-command API]
* link:api-setup.html[setup API]
--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"\r
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
+<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
+<style type="text/css">\r
+/* Debug borders */\r
+p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {\r
+/*\r
+ border: 1px solid red;\r
+*/\r
+}\r
+\r
+body {\r
+ margin: 1em 5% 1em 5%;\r
+}\r
+\r
+a { color: blue; }\r
+a:visited { color: fuchsia; }\r
+\r
+em {\r
+ font-style: italic;\r
+}\r
+\r
+strong {\r
+ font-weight: bold;\r
+}\r
+\r
+tt {\r
+ color: navy;\r
+}\r
+\r
+h1, h2, h3, h4, h5, h6 {\r
+ color: #527bbd;\r
+ font-family: sans-serif;\r
+ margin-top: 1.2em;\r
+ margin-bottom: 0.5em;\r
+ line-height: 1.3;\r
+}\r
+\r
+h1 {\r
+ border-bottom: 2px solid silver;\r
+}\r
+h2 {\r
+ border-bottom: 2px solid silver;\r
+ padding-top: 0.5em;\r
+}\r
+\r
+div.sectionbody {\r
+ font-family: serif;\r
+ margin-left: 0;\r
+}\r
+\r
+hr {\r
+ border: 1px solid silver;\r
+}\r
+\r
+p {\r
+ margin-top: 0.5em;\r
+ margin-bottom: 0.5em;\r
+}\r
+\r
+pre {\r
+ padding: 0;\r
+ margin: 0;\r
+}\r
+\r
+span#author {\r
+ color: #527bbd;\r
+ font-family: sans-serif;\r
+ font-weight: bold;\r
+ font-size: 1.2em;\r
+}\r
+span#email {\r
+}\r
+span#revision {\r
+ font-family: sans-serif;\r
+}\r
+\r
+div#footer {\r
+ font-family: sans-serif;\r
+ font-size: small;\r
+ border-top: 2px solid silver;\r
+ padding-top: 0.5em;\r
+ margin-top: 4.0em;\r
+}\r
+div#footer-text {\r
+ float: left;\r
+ padding-bottom: 0.5em;\r
+}\r
+div#footer-badges {\r
+ float: right;\r
+ padding-bottom: 0.5em;\r
+}\r
+\r
+div#preamble,\r
+div.tableblock, div.imageblock, div.exampleblock, div.verseblock,\r
+div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,\r
+div.admonitionblock {\r
+ margin-right: 10%;\r
+ margin-top: 1.5em;\r
+ margin-bottom: 1.5em;\r
+}\r
+div.admonitionblock {\r
+ margin-top: 2.5em;\r
+ margin-bottom: 2.5em;\r
+}\r
+\r
+div.content { /* Block element content. */\r
+ padding: 0;\r
+}\r
+\r
+/* Block element titles. */\r
+div.title, caption.title {\r
+ font-family: sans-serif;\r
+ font-weight: bold;\r
+ text-align: left;\r
+ margin-top: 1.0em;\r
+ margin-bottom: 0.5em;\r
+}\r
+div.title + * {\r
+ margin-top: 0;\r
+}\r
+\r
+td div.title:first-child {\r
+ margin-top: 0.0em;\r
+}\r
+div.content div.title:first-child {\r
+ margin-top: 0.0em;\r
+}\r
+div.content + div.title {\r
+ margin-top: 0.0em;\r
+}\r
+\r
+div.sidebarblock > div.content {\r
+ background: #ffffee;\r
+ border: 1px solid silver;\r
+ padding: 0.5em;\r
+}\r
+\r
+div.listingblock > div.content {\r
+ border: 1px solid silver;\r
+ background: #f4f4f4;\r
+ padding: 0.5em;\r
+}\r
+\r
+div.quoteblock > div.content {\r
+ padding-left: 2.0em;\r
+}\r
+div.quoteblock .attribution {\r
+ text-align: right;\r
+}\r
+\r
+div.admonitionblock .icon {\r
+ vertical-align: top;\r
+ font-size: 1.1em;\r
+ font-weight: bold;\r
+ text-decoration: underline;\r
+ color: #527bbd;\r
+ padding-right: 0.5em;\r
+}\r
+div.admonitionblock td.content {\r
+ padding-left: 0.5em;\r
+ border-left: 2px solid silver;\r
+}\r
+\r
+div.exampleblock > div.content {\r
+ border-left: 2px solid silver;\r
+ padding: 0.5em;\r
+}\r
+\r
+div.verseblock div.content {\r
+ white-space: pre;\r
+}\r
+\r
+div.imageblock div.content { padding-left: 0; }\r
+div.imageblock img { border: 1px solid silver; }\r
+span.image img { border-style: none; }\r
+\r
+dl {\r
+ margin-top: 0.8em;\r
+ margin-bottom: 0.8em;\r
+}\r
+dt {\r
+ margin-top: 0.5em;\r
+ margin-bottom: 0;\r
+ font-style: italic;\r
+}\r
+dd > *:first-child {\r
+ margin-top: 0;\r
+}\r
+\r
+ul, ol {\r
+ list-style-position: outside;\r
+}\r
+ol.olist2 {\r
+ list-style-type: lower-alpha;\r
+}\r
+\r
+div.tableblock > table {\r
+ border-color: #527bbd;\r
+ border-width: 3px;\r
+}\r
+thead {\r
+ font-family: sans-serif;\r
+ font-weight: bold;\r
+}\r
+tfoot {\r
+ font-weight: bold;\r
+}\r
+\r
+div.hlist {\r
+ margin-top: 0.8em;\r
+ margin-bottom: 0.8em;\r
+}\r
+td.hlist1 {\r
+ vertical-align: top;\r
+ font-style: italic;\r
+ padding-right: 0.8em;\r
+}\r
+td.hlist2 {\r
+ vertical-align: top;\r
+}\r
+\r
+@media print {\r
+ div#footer-badges { display: none; }\r
+}\r
+/* Workarounds for IE6's broken and incomplete CSS2. */\r
+\r
+div.sidebar-content {\r
+ background: #ffffee;\r
+ border: 1px solid silver;\r
+ padding: 0.5em;\r
+}\r
+div.sidebar-title, div.image-title {\r
+ font-family: sans-serif;\r
+ font-weight: bold;\r
+ margin-top: 0.0em;\r
+ margin-bottom: 0.5em;\r
+}\r
+\r
+div.listingblock div.content {\r
+ border: 1px solid silver;\r
+ background: #f4f4f4;\r
+ padding: 0.5em;\r
+}\r
+\r
+div.quoteblock-content {\r
+ padding-left: 2.0em;\r
+}\r
+\r
+div.exampleblock-content {\r
+ border-left: 2px solid silver;\r
+ padding-left: 0.5em;\r
+}\r
+</style>\r
+<title>Remotes configuration API</title>\r
+</head>\r
+<body>\r
+<div id="header">\r
+<h1>Remotes configuration API</h1>\r
+</div>\r
+<div id="preamble">\r
+<div class="sectionbody">\r
+<p>The API in remote.h gives access to the configuration related to\r
+remotes. It handles all three configuration mechanisms historically\r
+and currently used by git, and presents the information in a uniform\r
+fashion. Note that the code also handles plain URLs without any\r
+configuration, giving them just the default information.</p>\r
+</div>\r
+</div>\r
+<h2>struct remote</h2>\r
+<div class="sectionbody">\r
+<dl>\r
+<dt>\r
+<tt>name</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ The user's nickname for the remote\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>url</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ An array of all of the url_nr URLs configured for the remote\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>push</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ An array of refspecs configured for pushing, with\r
+ push_refspec being the literal strings, and push_refspec_nr\r
+ being the quantity.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>fetch</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ An array of refspecs configured for fetching, with\r
+ fetch_refspec being the literal strings, and fetch_refspec_nr\r
+ being the quantity.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>fetch_tags</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ The setting for whether to fetch tags (as a separate rule from\r
+ the configured refspecs); -1 means never to fetch tags, 0\r
+ means to auto-follow tags based on the default heuristic, 1\r
+ means to always auto-follow tags, and 2 means to fetch all\r
+ tags.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>receivepack</tt>, <tt>uploadpack</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ The configured helper programs to run on the remote side, for\r
+ git-native protocols.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>http_proxy</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ The proxy to use for curl (http, https, ftp, etc.) URLs.\r
+</p>\r
+</dd>\r
+</dl>\r
+<p>struct remotes can be found by name with remote_get(), and iterated\r
+through with for_each_remote(). remote_get(NULL) will return the\r
+default remote, given the current branch and configuration.</p>\r
+</div>\r
+<h2>struct refspec</h2>\r
+<div class="sectionbody">\r
+<p>A struct refspec holds the parsed interpretation of a refspec. If it\r
+will force updates (starts with a <em>+</em>), force is true. If it is a\r
+pattern (sides end with <em>*</em>) pattern is true. src and dest are the two\r
+sides (if a pattern, only the part outside of the wildcards); if there\r
+is only one side, it is src, and dst is NULL; if sides exist but are\r
+empty (i.e., the refspec either starts or ends with <em>:</em>), the\r
+corresponding side is "".</p>\r
+<p>This parsing can be done to an array of strings to give an array of\r
+struct refpsecs with parse_ref_spec().</p>\r
+<p>remote_find_tracking(), given a remote and a struct refspec with\r
+either src or dst filled out, will fill out the other such that the\r
+result is in the "fetch" specification for the remote (note that this\r
+evaluates patterns and returns a single result).</p>\r
+</div>\r
+<h2>struct branch</h2>\r
+<div class="sectionbody">\r
+<p>Note that this may end up moving to branch.h</p>\r
+<p>struct branch holds the configuration for a branch. It can be looked\r
+branch_get(NULL) for HEAD.</p>\r
+<p>It contains:</p>\r
+<dl>\r
+<dt>\r
+<tt>name</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ The short name of the branch.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>refname</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ The full path for the branch ref.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>remote_name</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ The name of the remote listed in the configuration.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>remote</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ The struct remote for that remote.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>merge_name</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ An array of the "merge" lines in the configuration.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>merge</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ An array of the struct refspecs used for the merge lines. That\r
+ is, merge[i]->dst is a local tracking ref which should be\r
+ merged into this branch by default.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>merge_nr</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ The number of merge configurations\r
+</p>\r
+</dd>\r
+</dl>\r
+<p>branch_has_merge_config() returns true if the given branch has merge\r
+configuration given.</p>\r
+</div>\r
+<h2>Other stuff</h2>\r
+<div class="sectionbody">\r
+<p>There is other stuff in remote.h that is related, in general, to the\r
+process of interacting with remotes.</p>\r
+<p>(Daniel Barkalow)</p>\r
+</div>\r
+<div id="footer">\r
+<div id="footer-text">\r
+Last updated 20-Feb-2008 10:44:09 UTC\r
+</div>\r
+</div>\r
+</body>\r
+</html>\r
--- /dev/null
+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)
</div>\r
<div id="preamble">\r
<div class="sectionbody">\r
-<p>Talk about <run-command.h>, and things like:</p>\r
+<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
+which is primarily used to capture the output that the function\r
+produces in the caller in order to process it.</p>\r
+</div>\r
+</div>\r
+<h2>Functions</h2>\r
+<div class="sectionbody">\r
+<dl>\r
+<dt>\r
+<tt>start_command</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Start a sub-process. Takes a pointer to a <tt>struct child_process</tt>\r
+ that specifies the details and returns pipe FDs (if requested).\r
+ See below for details.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>finish_command</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Wait for the completion of a sub-process that was started with\r
+ start_command().\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>run_command</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ A convenience function that encapsulates a sequence of\r
+ start_command() followed by finish_command(). Takes a pointer\r
+ to a <tt>struct child_process</tt> that specifies the details.\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
+</dt>\r
+<dd>\r
+<p>\r
+ Convenience functions that encapsulate a sequence of\r
+ start_command() followed by finish_command(). The argument argv\r
+ specifies the program and its arguments. The argument opt is zero\r
+ or more of the flags <tt>RUN_COMMAND_NO_STDIN</tt>, <tt>RUN_GIT_CMD</tt>, or\r
+ <tt>RUN_COMMAND_STDOUT_TO_STDERR</tt> that correspond to the members\r
+ .no_stdin, .git_cmd, .stdout_to_stderr of <tt>struct child_process</tt>.\r
+ The argument dir corresponds the member .dir. The argument env\r
+ corresponds to the member .env.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>start_async</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Run a function asynchronously. Takes a pointer to a <tt>struct\r
+ async</tt> that specifies the details and returns a pipe FD\r
+ from which the caller reads. See below for details.\r
+</p>\r
+</dd>\r
+<dt>\r
+<tt>finish_async</tt>\r
+</dt>\r
+<dd>\r
+<p>\r
+ Wait for the completeion of an asynchronous function that was\r
+ started with start_async().\r
+</p>\r
+</dd>\r
+</dl>\r
+</div>\r
+<h2>Data structures</h2>\r
+<div class="sectionbody">\r
<ul>\r
<li>\r
<p>\r
-Environment the command runs with (e.g. GIT_DIR);\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
+<li>\r
+<p>\r
+allocates and clears (memset(&chld, <em>0</em>, sizeof(chld));) a\r
+ struct child_process variable;\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+initializes the members;\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+calls start_command();\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+processes the data;\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+closes file descriptors (if necessary; see below);\r
+</p>\r
+</li>\r
+<li>\r
+<p>\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
+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
+<li>\r
+<p>\r
+Specify 0 to request no special redirection. No new file descriptor\r
+ is allocated. The child process simply inherits the channel from the\r
+ parent.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Specify -1 to have a pipe allocated; start_command() replaces -1\r
+ by the pipe FD in the following way:\r
+</p>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><tt>.in: Returns the writable pipe end into which the caller writes;\r
+ the readable end of the pipe becomes the child's stdin.</tt></pre>\r
+</div></div>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><tt>.out, .err: Returns the readable pipe end from which the caller\r
+ reads; the writable end of the pipe end becomes child's\r
+ stdout/stderr.</tt></pre>\r
+</div></div>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><tt>The caller of start_command() must close the so returned FDs\r
+after it has completed reading from/writing to it!</tt></pre>\r
+</div></div>\r
+</li>\r
+<li>\r
+<p>\r
+Specify a file descriptor > 0 to be used by the child:\r
</p>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><tt>.in: The FD must be readable; it becomes child's stdin.\r
+.out: The FD must be writable; it becomes child's stdout.\r
+.err > 0 is not supported.</tt></pre>\r
+</div></div>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><tt>The specified FD is closed by start_command(), even if it fails to\r
+run the sub-process!</tt></pre>\r
+</div></div>\r
</li>\r
<li>\r
<p>\r
-File descriptors and pipes;\r
+Special forms of redirection are available by setting these members\r
+ to 1:\r
</p>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><tt>.no_stdin, .no_stdout, .no_stderr: The respective channel is\r
+ redirected to /dev/null.</tt></pre>\r
+</div></div>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><tt>.stdout_to_stderr: stdout of the child is redirected to the\r
+ parent's stderr (i.e. *not* to what .err or\r
+ .no_stderr specify).</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
<li>\r
<p>\r
-Exit status;\r
+If the string is of the form "VAR=value", i.e. it contains <em>=</em>\r
+ the variable is added to the child process's environment.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+If the string does not contain <em>=</em>, it names an environement\r
+ variable that will be removed from the child process's envionment.\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
+<li>\r
+<p>\r
+<tt>struct async</tt>\r
</p>\r
</li>\r
</ul>\r
-<p>(Hannes, Dscho, Shawn)</p>\r
-</div>\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
+<li>\r
+<p>\r
+allocates and clears (memset(&asy, <em>0</em>, sizeof(asy));) a\r
+ struct async variable;\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+initializes .proc and .data;\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+calls start_async();\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+processes the data by reading from the fd in .out;\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+closes .out;\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+calls finish_async().\r
+</p>\r
+</li>\r
+</ol>\r
+<p>The function pointer in .proc has the following signature:</p>\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
+<li>\r
+<p>\r
+fd specifies a writable file descriptor to which the function must\r
+ write the data that it produces. The function <strong>must</strong> close this\r
+ descriptor before it returns.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+data is the value that the caller has specified in the .data member\r
+ of struct async.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+The return value of the function is 0 on success and non-zero\r
+ on failure. If the function indicates failure, finish_async() will\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
+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
+<li>\r
+<p>\r
+It cannot change the program's state (global variables, environment,\r
+ etc.) in a way that the caller notices; in other words, .out is the\r
+ only communication channel to the caller.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+It must not change the program's state that the caller of the\r
+ facility also uses.\r
+</p>\r
+</li>\r
+</ol>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 07-Jan-2008 07:51:29 UTC\r
+Last updated 20-Feb-2008 10:44:10 UTC\r
</div>\r
</div>\r
</body>\r
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.
projects / git.git / commitdiff