git-submodule: add support for --rebase.
[gitweb.git] / Documentation / git-submodule.txt
index abbd5b72de5a993819dff3e3e8fe8aa9516b956b..0286409744937bac5b4bed5af775f9b9834ea126 100644 (file)
@@ -12,9 +12,10 @@ SYNOPSIS
 'git submodule' [--quiet] add [-b branch] [--] <repository> <path>
 'git submodule' [--quiet] status [--cached] [--] [<path>...]
 'git submodule' [--quiet] init [--] [<path>...]
-'git submodule' [--quiet] update [--init] [--] [<path>...]
+'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase] [--] [<path>...]
 'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...]
 'git submodule' [--quiet] foreach <command>
+'git submodule' [--quiet] sync [--] [<path>...]
 
 
 DESCRIPTION
@@ -86,7 +87,7 @@ use by subsequent users cloning the superproject. If the URL is
 given relative to the superproject's repository, the presumption
 is the superproject and submodule repositories will be kept
 together in the same relative location, and only the
-superproject's URL need be provided: git-submodule will correctly
+superproject's URL needs to be provided: git-submodule will correctly
 locate the submodule using the relative URL in .gitmodules.
 
 status::
@@ -112,7 +113,8 @@ 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' is
+       specified or the key `submodule.$name.rebase` is set to `true`.
 +
 If the submodule is not yet initialized, and you just want to use the
 setting as stored in .gitmodules, you can automatically initialize the
@@ -139,6 +141,14 @@ foreach::
 As an example, "git submodule foreach 'echo $path `git rev-parse HEAD`' will
 show the path and currently checked out commit for each submodule.
 
+sync::
+       Synchronizes submodules' remote URL configuration setting
+       to the value specified in .gitmodules.  This is useful when
+       submodule URLs change upstream and you need to update your local
+       repositories accordingly.
++
+"git submodule sync" synchronizes all submodules while
+"git submodule sync -- A" synchronizes submodule "A" only.
 
 OPTIONS
 -------
@@ -163,6 +173,20 @@ OPTIONS
        (the default). This limit only applies to modified submodules. The
        size is always limited to 1 for added/deleted/typechanged submodules.
 
+-N::
+--no-fetch::
+       This option is only valid for the update command.
+       Don't fetch new objects from the remote site.
+
+--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.rebase` is set to `true`, this option is
+       implicit.
+
 <path>...::
        Paths to submodule(s). When specified this will restrict the command
        to only operate on the submodules found at the specified paths.