Autogenerated HTML docs for v1.7.5-rc0-131-gfa38c

config.txt

@@ -320,7 +320,7 @@ core.worktree::
 	Set the path to the root of the working tree.
 	This can be overridden by the GIT_WORK_TREE environment
 	variable and the '--work-tree' command line option.
-	The value can an absolute path or relative to the path to
+	The value can be an absolute path or relative to the path to
 	the .git directory, which is either specified by --git-dir
 	or GIT_DIR, or automatically discovered.
 	If --git-dir or GIT_DIR is specified but none of
@@ -897,9 +897,13 @@ diff.wordRegex::
 	characters are *ignorable* whitespace.
 
 fetch.recurseSubmodules::
-	A boolean value which changes the behavior for fetch and pull, the
-	default is to not recursively fetch populated submodules unless
-	configured otherwise.
+	This option can be either set to a boolean value or to 'on-demand'.
+	Setting it to a boolean changes the behavior of fetch and pull to
+	unconditionally recurse into submodules when set to true or to not
+	recurse at all when set to false. When set to 'on-demand' (the default
+	value), fetch and pull will only recurse into a populated submodule
+	when its superproject retrieves a commit that updates the submodule's
+	reference.
 
 fetch.unpackLimit::
 	If the number of objects fetched over the git native
@@ -1823,7 +1827,7 @@ submodule.<name>.update::
 	linkgit:git-submodule[1] and linkgit:gitmodules[5] for details.
 
 submodule.<name>.fetchRecurseSubmodules::
-	This option can be used to enable/disable recursive fetching of this
+	This option can be used to control recursive fetching of this
 	submodule. It can be overridden by using the --[no-]recurse-submodules
 	command line option to "git fetch" and "git pull".
 	This setting will override that from in the linkgit:gitmodules[5]

fetch-options.txt

@@ -65,14 +65,33 @@ ifndef::git-pull[]
 	specified with the remote.<name>.tagopt setting. See
 	linkgit:git-config[1].
 
---[no-]recurse-submodules::
-	This option controls if new commits of all populated submodules should
-	be fetched too (see linkgit:git-config[1] and linkgit:gitmodules[5]).
+--recurse-submodules[=yes|on-demand|no]::
+	This option controls if and under what conditions new commits of
+	populated submodules should be fetched too. It can be used as a
+	boolean option to completely disable recursion when set to 'no' or to
+	unconditionally recurse into all populated submodules when set to
+	'yes', which is the default when this option is used without any
+	value. Use 'on-demand' to only recurse into a populated submodule
+	when the superproject retrieves a commit that updates the submodule's
+	reference to a commit that isn't already in the local submodule
+	clone.
+
+--no-recurse-submodules::
+	Disable recursive fetching of submodules (this has the same effect as
+	using the '--recurse-submodules=no' option).
 
 --submodule-prefix=<path>::
 	Prepend <path> to paths printed in informative messages
 	such as "Fetching submodule foo".  This option is used
 	internally when recursing over submodules.
+
+--recurse-submodules-default=[yes|on-demand]::
+	This option is used internally to temporarily provide a
+	non-negative default value for the --recurse-submodules
+	option.  All other methods of configuring fetch's submodule
+	recursion (such as settings in linkgit:gitmodules[5] and
+	linkgit:git-config[1]) override this option, as does
+	specifying --[no-]recurse-submodules directly.
 endif::git-pull[]
 
 -u::

git-config.html

@@ -1289,7 +1289,7 @@ <h3 id="_variables">Variables</h3><div style="clear:left"></div>
         Set the path to the root of the working tree.
         This can be overridden by the GIT_WORK_TREE environment
         variable and the <em>--work-tree</em> command line option.
-        The value can an absolute path or relative to the path to
+        The value can be an absolute path or relative to the path to
         the .git directory, which is either specified by --git-dir
         or GIT_DIR, or automatically discovered.
         If --git-dir or GIT_DIR is specified but none of
@@ -2284,9 +2284,13 @@ <h3 id="_variables">Variables</h3><div style="clear:left"></div>
 </dt>
 <dd>
 <p>
-        A boolean value which changes the behavior for fetch and pull, the
-        default is to not recursively fetch populated submodules unless
-        configured otherwise.
+        This option can be either set to a boolean value or to <em>on-demand</em>.
+        Setting it to a boolean changes the behavior of fetch and pull to
+        unconditionally recurse into submodules when set to true or to not
+        recurse at all when set to false. When set to <em>on-demand</em> (the default
+        value), fetch and pull will only recurse into a populated submodule
+        when its superproject retrieves a commit that updates the submodule&#8217;s
+        reference.
 </p>
 </dd>
 <dt class="hdlist1">
@@ -4147,7 +4151,7 @@ <h3 id="_variables">Variables</h3><div style="clear:left"></div>
 </dt>
 <dd>
 <p>
-        This option can be used to enable/disable recursive fetching of this
+        This option can be used to control recursive fetching of this
         submodule. It can be overridden by using the --[no-]recurse-submodules
         command line option to "git fetch" and "git pull".
         This setting will override that from in the <a href="gitmodules.html">gitmodules(5)</a>

git-fetch.html

@@ -561,12 +561,28 @@ <h2 id="_options">OPTIONS</h2>
 </p>
 </dd>
 <dt class="hdlist1">
---[no-]recurse-submodules
+--recurse-submodules[=yes|on-demand|no]
 </dt>
 <dd>
 <p>
-        This option controls if new commits of all populated submodules should
-        be fetched too (see <a href="git-config.html">git-config(1)</a> and <a href="gitmodules.html">gitmodules(5)</a>).
+        This option controls if and under what conditions new commits of
+        populated submodules should be fetched too. It can be used as a
+        boolean option to completely disable recursion when set to <em>no</em> or to
+        unconditionally recurse into all populated submodules when set to
+        <em>yes</em>, which is the default when this option is used without any
+        value. Use <em>on-demand</em> to only recurse into a populated submodule
+        when the superproject retrieves a commit that updates the submodule&#8217;s
+        reference to a commit that isn&#8217;t already in the local submodule
+        clone.
+</p>
+</dd>
+<dt class="hdlist1">
+--no-recurse-submodules
+</dt>
+<dd>
+<p>
+        Disable recursive fetching of submodules (this has the same effect as
+        using the <em>--recurse-submodules=no</em> option).
 </p>
 </dd>
 <dt class="hdlist1">
@@ -580,6 +596,19 @@ <h2 id="_options">OPTIONS</h2>
 </p>
 </dd>
 <dt class="hdlist1">
+--recurse-submodules-default=[yes|on-demand]
+</dt>
+<dd>
+<p>
+        This option is used internally to temporarily provide a
+        non-negative default value for the --recurse-submodules
+        option.  All other methods of configuring fetch&#8217;s submodule
+        recursion (such as settings in <a href="gitmodules.html">gitmodules(5)</a> and
+        <a href="git-config.html">git-config(1)</a>) override this option, as does
+        specifying --[no-]recurse-submodules directly.
+</p>
+</dd>
+<dt class="hdlist1">
 -u
 </dt>
 <dt class="hdlist1">
@@ -994,6 +1023,15 @@ <h2 id="_examples">EXAMPLES</h2>
 </li>
 </ul></div>
 </div>
+<h2 id="_bugs">BUGS</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Using --recurse-submodules can only fetch new commits in already checked
+out submodules right now. When e.g. upstream added a new submodule in the
+just fetched commits of the superproject the submodule itself can not be
+fetched, making it impossible to check out that submodule later without
+having to do a fetch again. This is expected to be fixed in a future git
+version.</p></div>
+</div>
 <h2 id="_see_also">SEE ALSO</h2>
 <div class="sectionbody">
 <div class="paragraph"><p><a href="git-pull.html">git-pull(1)</a></p></div>
@@ -1004,7 +1042,7 @@ <h2 id="_git">GIT</h2>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2011-03-15 23:30:13 UTC
+Last updated 2011-04-05 00:20:31 UTC
 </div>
 </div>
 </body>

git-fetch.txt

@@ -76,6 +76,15 @@ The `pu` branch will be updated even if it is does not fast-forward,
 because it is prefixed with a plus sign; `tmp` will not be.
 
 
+BUGS
+----
+Using --recurse-submodules can only fetch new commits in already checked
+out submodules right now. When e.g. upstream added a new submodule in the
+just fetched commits of the superproject the submodule itself can not be
+fetched, making it impossible to check out that submodule later without
+having to do a fetch again. This is expected to be fixed in a future git
+version.
+
 SEE ALSO
 --------
 linkgit:git-pull[1]

git-log.html

@@ -797,8 +797,8 @@ <h3 id="_commit_limiting">Commit Limiting</h3><div style="clear:left"></div>
 </p>
 <div class="paragraph"><p>For example, if you have two branches, <tt>A</tt> and <tt>B</tt>, a usual way
 to list all commits on only one side of them is with
-<tt>--left-right</tt>, like the example above in the description of
-that option.  It however shows the commits that were cherry-picked
+<tt>--left-right</tt> (see the example below in the description of
+the <tt>--left-right</tt> option).  It however shows the commits that were cherry-picked
 from the other branch (for example, "3rd on b" may be cherry-picked
 from branch A).  With this option, such pairs of commits are
 excluded from the output.</p></div>

git-pull.html

@@ -494,7 +494,7 @@ <h2 id="_options">OPTIONS</h2>
 </p>
 </dd>
 <dt class="hdlist1">
---[no-]recurse-submodules
+--[no-]recurse-submodules[=yes|on-demand|no]
 </dt>
 <dd>
 <p>
@@ -1421,6 +1421,15 @@ <h2 id="_examples">EXAMPLES</h2>
 <div class="paragraph"><p>If you tried a pull which resulted in a complex conflicts and
 would want to start over, you can recover with <em>git reset</em>.</p></div>
 </div>
+<h2 id="_bugs">BUGS</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Using --recurse-submodules can only fetch new commits in already checked
+out submodules right now. When e.g. upstream added a new submodule in the
+just fetched commits of the superproject the submodule itself can not be
+fetched, making it impossible to check out that submodule later without
+having to do a fetch again. This is expected to be fixed in a future git
+version.</p></div>
+</div>
 <h2 id="_see_also">SEE ALSO</h2>
 <div class="sectionbody">
 <div class="paragraph"><p><a href="git-fetch.html">git-fetch(1)</a>, <a href="git-merge.html">git-merge(1)</a>, <a href="git-config.html">git-config(1)</a></p></div>
@@ -1431,7 +1440,7 @@ <h2 id="_git">GIT</h2>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2011-03-15 23:30:14 UTC
+Last updated 2011-04-05 00:20:31 UTC
 </div>
 </div>
 </body>

git-pull.txt

@@ -84,7 +84,7 @@ must be given before the options meant for 'git fetch'.
 --verbose::
 	Pass --verbose to git-fetch and git-merge.
 
---[no-]recurse-submodules::
+--[no-]recurse-submodules[=yes|on-demand|no]::
 	This option controls if new commits of all populated submodules should
 	be fetched too (see linkgit:git-config[1] and linkgit:gitmodules[5]).
 	That might be necessary to get the data needed for merging submodule
@@ -220,6 +220,15 @@ If you tried a pull which resulted in a complex conflicts and
 would want to start over, you can recover with 'git reset'.
 
 
+BUGS
+----
+Using --recurse-submodules can only fetch new commits in already checked
+out submodules right now. When e.g. upstream added a new submodule in the
+just fetched commits of the superproject the submodule itself can not be
+fetched, making it impossible to check out that submodule later without
+having to do a fetch again. This is expected to be fixed in a future git
+version.
+
 SEE ALSO
 --------
 linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-config[1]

git-rev-list.html

@@ -797,8 +797,8 @@ <h3 id="_commit_limiting">Commit Limiting</h3><div style="clear:left"></div>
 </p>
 <div class="paragraph"><p>For example, if you have two branches, <tt>A</tt> and <tt>B</tt>, a usual way
 to list all commits on only one side of them is with
-<tt>--left-right</tt>, like the example above in the description of
-that option.  It however shows the commits that were cherry-picked
+<tt>--left-right</tt> (see the example below in the description of
+the <tt>--left-right</tt> option).  It however shows the commits that were cherry-picked
 from the other branch (for example, "3rd on b" may be cherry-picked
 from branch A).  With this option, such pairs of commits are
 excluded from the output.</p></div>

git-submodule.html

@@ -510,9 +510,10 @@ <h2 id="_commands">COMMANDS</h2>
         currently checked out commit for each submodule, along with the
         submodule path and the output of <em>git describe</em> for the
         SHA-1. Each SHA-1 will be prefixed with <tt>-</tt> if the submodule is not
-        initialized and <tt>+</tt> if the currently checked out submodule commit
+        initialized, <tt>+</tt> if the currently checked out submodule commit
         does not match the SHA-1 found in the index of the containing
-        repository. This command is the default command for <em>git submodule</em>.
+        repository and <tt>U</tt> if the submodule has merge conflicts.
+        This command is the default command for <em>git submodule</em>.
 </p>
 <div class="paragraph"><p>If <em>--recursive</em> is specified, this command will recurse into nested
 submodules, and show their status as well.</p></div>
@@ -767,7 +768,7 @@ <h2 id="_git">GIT</h2>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2011-03-15 23:30:14 UTC
+Last updated 2011-04-05 00:20:31 UTC
 </div>
 </div>
 </body>

git-submodule.txt

@@ -101,9 +101,10 @@ status::
 	currently checked out commit for each submodule, along with the
 	submodule path and the output of 'git describe' for the
 	SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not
-	initialized and `+` if the currently checked out submodule commit
+	initialized, `+` if the currently checked out submodule commit
 	does not match the SHA-1 found in the index of the containing
-	repository. This command is the default command for 'git submodule'.
+	repository and `U` if the submodule has merge conflicts.
+	This command is the default command for 'git submodule'.
 +
 If '--recursive' is specified, this command will recurse into nested
 submodules, and show their status as well.

gitmodules.html

@@ -468,12 +468,12 @@ <h2 id="_description">DESCRIPTION</h2>
 </dt>
 <dd>
 <p>
-        This option can be used to enable/disable recursive fetching of this
+        This option can be used to control recursive fetching of this
         submodule. If this option is also present in the submodules entry in
         .git/config of the superproject, the setting there will override the
         one found in .gitmodules.
         Both settings can be overridden on the command line by using the
-        "--[no-]recurse-submodules" option to "git fetch" and "git pull"..
+        "--[no-]recurse-submodules" option to "git fetch" and "git pull".
 </p>
 </dd>
 <dt class="hdlist1">
@@ -527,7 +527,7 @@ <h2 id="_git">GIT</h2>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2011-03-15 23:30:15 UTC
+Last updated 2011-04-05 00:20:31 UTC
 </div>
 </div>
 </body>

gitmodules.txt

@@ -45,12 +45,12 @@ submodule.<name>.update::
 	the '--merge' or '--rebase' options.
 
 submodule.<name>.fetchRecurseSubmodules::
-	This option can be used to enable/disable recursive fetching of this
+	This option can be used to control recursive fetching of this
 	submodule. If this option is also present in the submodules entry in
 	.git/config of the superproject, the setting there will override the
 	one found in .gitmodules.
 	Both settings can be overridden on the command line by using the
-	"--[no-]recurse-submodules" option to "git fetch" and "git pull"..
+	"--[no-]recurse-submodules" option to "git fetch" and "git pull".
 
 submodule.<name>.ignore::
 	Defines under what circumstances "git status" and the diff family show

rev-list-options.txt

@@ -179,8 +179,8 @@ endif::git-rev-list[]
 +
 For example, if you have two branches, `A` and `B`, a usual way
 to list all commits on only one side of them is with
-`--left-right`, like the example above in the description of
-that option.  It however shows the commits that were cherry-picked
+`--left-right` (see the example below in the description of
+the `--left-right` option).  It however shows the commits that were cherry-picked
 from the other branch (for example, "3rd on b" may be cherry-picked
 from branch A).  With this option, such pairs of commits are
 excluded from the output.