Merge branch 'bs/stdio-undef-before-redef'
[gitweb.git] / Documentation / git-submodule.txt
index 74d5bdc59d58f743bc6f5cb5f7f9ee24d384d5c8..bfef8a0c62a56865cfe2335841efcb4535642287 100644 (file)
@@ -10,12 +10,12 @@ SYNOPSIS
 --------
 [verse]
 'git submodule' [--quiet] add [-b <branch>] [-f|--force] [--name <name>]
-             [--reference <repository>] [--] <repository> [<path>]
+             [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]
 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...]
 'git submodule' [--quiet] init [--] [<path>...]
 'git submodule' [--quiet] deinit [-f|--force] [--] <path>...
 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]
-             [-f|--force] [--rebase] [--reference <repository>]
+             [-f|--force] [--rebase] [--reference <repository>] [--depth <depth>]
              [--merge] [--recursive] [--] [<path>...]
 'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]
              [commit] [--] [<path>...]
@@ -77,6 +77,8 @@ 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").
+The <path> is also used as the submodule's logical name in its
+configuration entries unless `--name` is used to specify a logical name.
 +
 <repository> is the URL of the new submodule's origin repository.
 This may be either an absolute URL, or (if it begins with ./
@@ -124,8 +126,10 @@ linkgit:git-status[1] and linkgit:git-diff[1] will provide that information
 too (and can also report changes to a submodule's work tree).
 
 init::
-       Initialize the submodules, i.e. register each submodule name
-       and url found in .gitmodules into .git/config.
+       Initialize the submodules recorded in the index (which were
+       added and committed elsewhere) by copying submodule
+       names and urls from .gitmodules to .git/config.
+       Optional <path> arguments limit which submodules will be initialized.
        It will also copy the value of `submodule.$name.update` into
        .git/config.
        The key used in .git/config is `submodule.$name.url`.
@@ -155,7 +159,9 @@ update::
        This will make the submodules HEAD be detached unless `--rebase` or
        `--merge` is specified or the key `submodule.$name.update` is set to
        `rebase`, `merge` or `none`. `none` can be overridden by specifying
-       `--checkout`.
+       `--checkout`. Setting the key `submodule.$name.update` to `!command`
+       will cause `command` to be run. `command` can be any arbitrary shell
+       command that takes a single argument, namely the sha1 to update to.
 +
 If the submodule is not yet initialized, and you just want to use the
 setting as stored in .gitmodules, you can automatically initialize the
@@ -258,7 +264,7 @@ OPTIONS
 --remote::
        This option is only valid for the update command.  Instead of using
        the superproject's recorded SHA-1 to update the submodule, use the
-       status of the submodule's remote tracking branch.  The remote used
+       status of the submodule's remote-tracking branch.  The remote used
        is branch's remote (`branch.<name>.remote`), defaulting to `origin`.
        The remote branch used defaults to `master`, but the branch name may
        be overridden by setting the `submodule.<name>.branch` option in
@@ -324,6 +330,12 @@ for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully.
        only in the submodules of the current repo, but also
        in any nested submodules inside those submodules (and so on).
 
+--depth::
+       This option is valid for add and update commands. Create a 'shallow'
+       clone with a history truncated to the specified number of revisions.
+       See linkgit:git-clone[1]
+
+
 <path>...::
        Paths to submodule(s). When specified this will restrict the command
        to only operate on the submodules found at the specified paths.