Merge branch 'jc/submodule-sync-no-auto-vivify' into maint

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 2502531a3dfd0cee67f6d1d9fc1db1d69cf20e30..2b31d5f1f2c63cdd9286eed8090ce27724e5d0bf 100644 (file)
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -9,7 +9,7 @@ git-submodule - Initialize, update or inspect submodules
 SYNOPSIS
 --------
 [verse]
-'git submodule' [--quiet] add [-b branch]
+'git submodule' [--quiet] add [-b branch] [-f|--force]
              [--reference <repository>] [--] <repository> [<path>]
 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...]
 'git submodule' [--quiet] init [--] [<path>...]
@@ -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.
@@ -145,10 +146,12 @@ summary::
 
 foreach::
        Evaluates an arbitrary shell command in each checked out submodule.
-       The command has access to the variables $name, $path and $sha1:
+       The command has access to the variables $name, $path, $sha1 and
+       $toplevel:
        $name is the name of the relevant submodule section in .gitmodules,
        $path is the name of the submodule directory relative to the
-       superproject, and $sha1 is the commit as recorded in the superproject.
+       superproject, $sha1 is the commit as recorded in the superproject,
+       and $toplevel is the absolute path to the top-level of the superproject.
        Any submodules defined in the superproject but not checked out are
        ignored by this command. Unless given --quiet, foreach prints the name
        of each submodule before evaluating the command.
@@ -164,7 +167,9 @@ commit for each submodule.
 
 sync::
        Synchronizes submodules' remote URL configuration setting
-       to the value specified in .gitmodules.  This is useful when
+       to the value specified in .gitmodules. It will only affect those
+       submodules which already have an url entry in .git/config (that is the
+       case when they are initialized or freshly added). This is useful when
        submodule URLs change upstream and you need to update your local
        repositories accordingly.
 +
@@ -181,6 +186,13 @@ OPTIONS
 --branch::
        Branch of repository to add as submodule.
 
+-f::
+--force::
+       This option is only valid for add and update commands.
+       When running add, allow adding an otherwise ignored submodule path.
+       When running update, throw away local changes in submodules when
+       switching to a different commit.
+
 --cached::
        This option is only valid for status and summary commands.  These
        commands typically use the commit found in the submodule HEAD, but
@@ -250,11 +262,6 @@ This file should be formatted in the same way as `$GIT_DIR/config`. The key
 to each submodule url is "submodule.$name.url".  See linkgit:gitmodules[5]
 for details.
 
-
-AUTHOR
-------
-Written by Lars Hjemli <hjemli@gmail.com>
-
 GIT
 ---
 Part of the linkgit:git[1] suite