Merge branch 'jl/clone-recurse-sm-synonym'

[git.git] / Documentation / git-submodule.txt

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 5ccdd18c89381e81fc616facb22bd7fee6faf964..1ed331c599d4b492b0dec112332bb83db5506d74 100644 (file)
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -9,8 +9,8 @@ git-submodule - Initialize, update or inspect submodules
 SYNOPSIS
 --------
 [verse]
-'git submodule' [--quiet] add [-b branch]
-             [--reference <repository>] [--] <repository> <path>
+'git submodule' [--quiet] add [-b branch] [-f|--force]
+             [--reference <repository>] [--] <repository> [<path>]
 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...]
 'git submodule' [--quiet] init [--] [<path>...]
 'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase]
@@ -69,7 +69,11 @@ add::
        to the changeset to be committed next to the current
        project: the current project is termed the "superproject".
 +
-This requires two arguments: <repository> and <path>.
+This requires at least one argument: <repository>. The optional
+argument <path> is the relative location for the cloned submodule
+to exist in the superproject. If <path> is not given, the
+"humanish" part of the source repository is used ("repo" for
+"/path/to/repo.git" and "foo" for "host.xz:foo/.git").
 +
 <repository> is the URL of the new submodule's origin repository.
 This may be either an absolute URL, or (if it begins with ./
@@ -95,11 +99,11 @@ locate the submodule using the relative URL in .gitmodules.
 status::
        Show the status of the submodules. This will print the SHA-1 of the
        currently checked out commit for each submodule, along with the
-       submodule path and the output of 'git-describe' for 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
        does not match the SHA-1 found in the index of the containing
-       repository. This command is the default command for 'git-submodule'.
+       repository. 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.
@@ -110,8 +114,8 @@ init::
        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
+       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.
 
@@ -141,10 +145,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.
@@ -177,6 +183,11 @@ OPTIONS
 --branch::
        Branch of repository to add as submodule.
 
+-f::
+--force::
+       This option is only valid for the add command.
+       Allow adding an otherwise ignored submodule path.
+
 --cached::
        This option is only valid for status and summary commands.  These
        commands typically use the commit found in the submodule HEAD, but
@@ -214,7 +225,7 @@ OPTIONS
        This option is only valid for the update command.
        Rebase the current branch onto the commit recorded in the
        superproject. If this option is given, the submodule's HEAD will not
-       be detached. If a a merge failure prevents this process, you will have
+       be detached. If a merge failure prevents this process, you will have
        to resolve these failures with linkgit:git-rebase[1].
        If the key `submodule.$name.update` is set to `rebase`, this option is
        implicit.