docs: mention when increasing http.postBuffer is valuable

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

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index ba3c4df550acfeb04a0a6b753a778816f031492c..5232407f68331618e5c509b91aef30ce6c6dbecd 100644 (file)
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -9,11 +9,14 @@ git-submodule - Initialize, update or inspect submodules
 SYNOPSIS
 --------
 [verse]
+'git submodule' [--quiet] [--cached]
 'git submodule' [--quiet] add [<options>] [--] <repository> [<path>]
 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...]
 'git submodule' [--quiet] init [--] [<path>...]
 'git submodule' [--quiet] deinit [-f|--force] (--all|[--] <path>...)
 'git submodule' [--quiet] update [<options>] [--] [<path>...]
+'git submodule' [--quiet] set-branch [<options>] [--] <path>
+'git submodule' [--quiet] set-url [--] <path> <newurl>
 'git submodule' [--quiet] summary [<options>] [--] [<path>...]
 'git submodule' [--quiet] foreach [--recursive] <command>
 'git submodule' [--quiet] sync [--recursive] [--] [<path>...]
@@ -28,6 +31,9 @@ For more information about submodules, see linkgit:gitsubmodules[7].
 
 COMMANDS
 --------
+With no arguments, shows the status of existing submodules.  Several
+subcommands are available to perform operations on the submodules.
+
 add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]::
        Add the given repository as a submodule at the given path
        to the changeset to be committed next to the current
@@ -38,7 +44,7 @@ This may be either an absolute URL, or (if it begins with ./
 or ../), the location relative to the superproject's default remote
 repository (Please note that to specify a repository 'foo.git'
 which is located right next to a superproject 'bar.git', you'll
-have to use '../foo.git' instead of './foo.git' - as one might expect
+have to use `../foo.git` instead of `./foo.git` - as one might expect
 when following the rules for relative URLs - because the evaluation
 of relative URLs in Git is identical to that of relative directories).
 +
@@ -75,6 +81,9 @@ status [--cached] [--recursive] [--] [<path>...]::
        does not match the SHA-1 found in the index of the containing
        repository and `U` if the submodule has merge conflicts.
 +
+If `--cached` is specified, this command will instead print the SHA-1
+recorded in the superproject for each submodule.
++
 If `--recursive` is specified, this command will recurse into nested
 submodules, and show their status as well.
 +
@@ -128,7 +137,8 @@ update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--forc
 +
 --
 Update the registered submodules to match what the superproject
-expects by cloning missing submodules and updating the working tree of
+expects by cloning missing submodules, fetching missing commits
+in submodules and updating the working tree of
 the submodules. The "updating" can be done in several ways depending
 on command line options and the value of `submodule.<name>.update`
 configuration variable. The command line option takes precedence over
@@ -168,6 +178,18 @@ submodule with the `--init` option.
 If `--recursive` is specified, this command will recurse into the
 registered submodules, and update any nested submodules within.
 --
+set-branch (-b|--branch) <branch> [--] <path>::
+set-branch (-d|--default) [--] <path>::
+       Sets the default remote tracking branch for the submodule. The
+       `--branch` option allows the remote branch to be specified. The
+       `--default` option removes the submodule.<name>.branch configuration
+       key, which causes the tracking branch to default to 'master'.
+
+set-url [--] <path> <newurl>::
+       Sets the URL of the specified submodule to <newurl>. Then, it will
+       automatically synchronize the submodule's new remote URL
+       configuration.
+
 summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]::
        Show commit summary between the given commit (defaults to HEAD) and
        working tree/index. For a submodule in question, a series of commits
@@ -226,7 +248,7 @@ registered submodules, and sync any nested submodules within.
 
 absorbgitdirs::
        If a git directory of a submodule is inside the submodule,
-       move the git directory of the submodule into its superprojects
+       move the git directory of the submodule into its superproject's
        `$GIT_DIR/modules` path and then connect the git directory and
        its working directory by setting the `core.worktree` and adding
        a .git file pointing to the git directory embedded in the
@@ -255,13 +277,14 @@ OPTIONS
        This option is only valid for the deinit command. Unregister all
        submodules in the working tree.
 
--b::
---branch::
+-b <branch>::
+--branch <branch>::
        Branch of repository to add as submodule.
        The name of the branch is recorded as `submodule.<name>.branch` in
        `.gitmodules` for `update --remote`.  A special value of `.` is used to
        indicate that the name of the branch in the submodule should be the
-       same name as the current branch in the current repository.
+       same name as the current branch in the current repository.  If the
+       option is not specified, it defaults to 'master'.
 
 -f::
 --force::