Merge branch 'aj/fix-read-tree-from-scratch'

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

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 15b34d3760820655c76da3d3b8508db81c8e8dae..bb7d159179a4f97c8641a50ba4425271c62566d8 100644 (file)
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -9,11 +9,13 @@ git-submodule - Initialize, update or inspect submodules
 SYNOPSIS
 --------
 [verse]
-'git submodule' [--quiet] add [-b branch] [--] <repository> <path>
+'git submodule' [--quiet] add [-b branch]
+             [--reference <repository>] [--] <repository> <path>
 'git submodule' [--quiet] status [--cached] [--] [<path>...]
 'git submodule' [--quiet] init [--] [<path>...]
-'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--] [<path>...]
-'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...]
+'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase]
+             [--reference <repository>] [--merge] [--] [<path>...]
+'git submodule' [--quiet] summary [--cached|--files] [--summary-limit <n>] [commit] [--] [<path>...]
 'git submodule' [--quiet] foreach <command>
 'git submodule' [--quiet] sync [--] [<path>...]
 
@@ -113,7 +115,9 @@ init::
 update::
        Update the registered submodules, i.e. clone missing submodules and
        checkout the commit specified in the index of the containing repository.
-       This will make the submodules HEAD be detached.
+       This will make the submodules HEAD be detached unless '--rebase' or
+       '--merge' is specified or the key `submodule.$name.update` is set to
+       `rebase` or `merge`.
 +
 If the submodule is not yet initialized, and you just want to use the
 setting as stored in .gitmodules, you can automatically initialize the
@@ -123,7 +127,11 @@ summary::
        Show commit summary between the given commit (defaults to HEAD) and
        working tree/index. For a submodule in question, a series of commits
        in the submodule between the given super project commit and the
-       index or working tree (switched by --cached) are shown.
+       index or working tree (switched by --cached) are shown. If the option
+       --files is given, show the series of commits in the submodule between
+       the index of the super project and the working tree of the submodule
+       (this option doesn't allow to use the --cached option or to provide an
+       explicit commit).
 
 foreach::
        Evaluates an arbitrary shell command in each checked out submodule.
@@ -165,6 +173,11 @@ OPTIONS
        commands typically use the commit found in the submodule HEAD, but
        with this option, the commit stored in the index is used instead.
 
+--files::
+       This option is only valid for the summary command. This command
+       compares the commit in the index with that in the submodule HEAD
+       when this option is used.
+
 -n::
 --summary-limit::
        This option is only valid for the summary command.
@@ -178,6 +191,33 @@ OPTIONS
        This option is only valid for the update command.
        Don't fetch new objects from the remote site.
 
+--merge::
+       This option is only valid for the update command.
+       Merge the commit recorded in the superproject into the current branch
+       of the submodule. If this option is given, the submodule's HEAD will
+       not be detached. If a merge failure prevents this process, you will
+       have to resolve the resulting conflicts within the submodule with the
+       usual conflict resolution tools.
+       If the key `submodule.$name.update` is set to `merge`, this option is
+       implicit.
+
+--rebase::
+       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
+       to resolve these failures with linkgit:git-rebase[1].
+       If the key `submodule.$name.update` is set to `rebase`, this option is
+       implicit.
+
+--reference <repository>::
+       This option is only valid for add and update commands.  These
+       commands sometimes need to clone a remote repository. In this case,
+       this option will be passed to the linkgit:git-clone[1] command.
++
+*NOTE*: Do *not* use this option unless you have read the note
+for linkgit:git-clone[1]'s --reference and --shared options carefully.
+
 <path>...::
        Paths to submodule(s). When specified this will restrict the command
        to only operate on the submodules found at the specified paths.