diff options
Diffstat (limited to 'Documentation/git-submodule.txt')
| -rw-r--r-- | Documentation/git-submodule.txt | 47 |
1 files changed, 38 insertions, 9 deletions
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index b1996f1a63..bfef8a0c62 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -10,11 +10,13 @@ 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] update [--init] [--remote] [-N|--no-fetch] [--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>] [--depth <depth>] + [--merge] [--recursive] [--] [<path>...] 'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...] 'git submodule' [--quiet] foreach [--recursive] <command> @@ -75,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 ./ @@ -91,7 +95,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. @@ -122,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`. @@ -134,13 +140,28 @@ 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. 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 @@ -213,8 +234,10 @@ OPTIONS -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 @@ -241,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 @@ -307,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. |