git add <pathspec>... defaults to "-A"
[gitweb.git] / Documentation / git-submodule.txt
index 349378448c5099cadf2bd6a5f5deca57fe03b4ca..74d5bdc59d58f743bc6f5cb5f7f9ee24d384d5c8 100644 (file)
@@ -13,8 +13,10 @@ SYNOPSIS
              [--reference <repository>] [--] <repository> [<path>]
 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...]
 'git submodule' [--quiet] init [--] [<path>...]
-'git submodule' [--quiet] update [--init] [-N|--no-fetch] [-f|--force] [--rebase]
-             [--reference <repository>] [--merge] [--recursive] [--] [<path>...]
+'git submodule' [--quiet] deinit [-f|--force] [--] <path>...
+'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]
+             [-f|--force] [--rebase] [--reference <repository>]
+             [--merge] [--recursive] [--] [<path>...]
 'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]
              [commit] [--] [<path>...]
 'git submodule' [--quiet] foreach [--recursive] <command>
@@ -91,7 +93,7 @@ working directory is used instead.
 <path> is the relative location for the cloned submodule to
 exist in the superproject. If <path> does not exist, then the
 submodule is created by cloning from the named URL. If <path> does
-exist and is already a valid git repository, then this is added
+exist and is already a valid Git repository, then this is added
 to the changeset without cloning. This second form is provided
 to ease creating a new submodule from scratch, and presumes
 the user will later push the submodule to the given URL.
@@ -134,6 +136,19 @@ init::
        the explicit 'init' step if you do not intend to customize
        any submodule locations.
 
+deinit::
+       Unregister the given submodules, i.e. remove the whole
+       `submodule.$name` section from .git/config together with their work
+       tree. Further calls to `git submodule update`, `git submodule foreach`
+       and `git submodule sync` will skip any unregistered submodules until
+       they are initialized again, so use this command if you don't want to
+       have a local checkout of the submodule in your work tree anymore. If
+       you really want to remove a submodule from the repository and commit
+       that use linkgit:git-rm[1] instead.
++
+If `--force` is specified, the submodule's work tree will be removed even if
+it contains local modifications.
+
 update::
        Update the registered submodules, i.e. clone missing submodules and
        checkout the commit specified in the index of the containing repository.
@@ -208,11 +223,15 @@ OPTIONS
 -b::
 --branch::
        Branch of repository to add as submodule.
+       The name of the branch is recorded as `submodule.<path>.branch` in
+       `.gitmodules` for `update --remote`.
 
 -f::
 --force::
-       This option is only valid for add and update commands.
+       This option is only valid for add, deinit and update commands.
        When running add, allow adding an otherwise ignored submodule path.
+       When running deinit the submodule work trees will be removed even if
+       they contain local changes.
        When running update, throw away local changes in submodules when
        switching to a different commit; and always run a checkout operation
        in the submodule, even if the commit listed in the index of the
@@ -236,6 +255,27 @@ OPTIONS
        (the default). This limit only applies to modified submodules. The
        size is always limited to 1 for added/deleted/typechanged submodules.
 
+--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
+       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
+       either `.gitmodules` or `.git/config` (with `.git/config` taking
+       precedence).
++
+This works for any of the supported update procedures (`--checkout`,
+`--rebase`, etc.).  The only change is the source of the target SHA-1.
+For example, `submodule update --remote --merge` will merge upstream
+submodule changes into the submodules, while `submodule update
+--merge` will merge superproject gitlink changes into the submodules.
++
+In order to ensure a current tracking branch state, `update --remote`
+fetches the submodule's remote repository before calculating the
+SHA-1.  If you don't want to fetch, you should use `submodule update
+--remote --no-fetch`.
+
 -N::
 --no-fetch::
        This option is only valid for the update command.