diff options
Diffstat (limited to 'Documentation/git-submodule.txt')
| -rw-r--r-- | Documentation/git-submodule.txt | 92 |
1 files changed, 79 insertions, 13 deletions
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 77e45d1060..a15d92d09b 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] [--checkout|--rebase|--merge] [--reference <repository>] + [--depth <depth>] [--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,46 @@ 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 the commit specified in the index of the containing + repository. The update mode defaults to `checkout`, but can be + configured with the `submodule.<name>.update` setting or the + `--rebase`, `--merge`, or `--checkout` options. ++ +For updates that clone missing submodules, checkout-mode updates will +create submodules with detached HEADs; all other modes will create +submodules with a local branch named after `submodule.<path>.branch`. ++ +For updates that do not clone missing submodules, the submodule's HEAD +is only touched when the remote reference does not match the +submodule's HEAD (for none-mode updates, the submodule is never +touched). The remote reference is usually the gitlinked commit from +the superproject's tree, but with `--remote` it is the upstream +subproject's `submodule.<name>.branch`. This remote reference is +integrated with the submodule's HEAD using the specified update mode. +For checkout-mode updates, that will result in a detached HEAD. For +rebase- and merge-mode updates, the commit referenced by the +submodule's HEAD may change, but the symbolic reference will remain +unchanged (i.e. checked-out branches will still be checked-out +branches, and detached HEADs will still be detached HEADs). If none +of the builtin modes fit your needs, set `submodule.<name>.update` to +`!command` to configure a custom integration command. `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 +252,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 +282,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 @@ -258,12 +299,31 @@ 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`. ++ +Use this option to integrate changes from the upstream subproject with +your submodule's current HEAD. Alternatively, you can run `git pull` +from the submodule, which is equivalent except for the remote branch +name: `update --remote` uses the default upstream repository and +`submodule.<name>.branch`, while `git pull` uses the submodule's +`branch.<name>.merge`. Prefer `submodule.<name>.branch` if you want +to distribute the default upstream branch with the superproject and +`branch.<name>.merge` if you want a more native feel while working in +the submodule itself. -N:: --no-fetch:: This option is only valid for the update command. Don't fetch new objects from the remote site. +--checkout:: + This option is only valid for the update command. + Checkout the commit recorded in the superproject on a detached HEAD + in the submodule. This is the default behavior, the main use of + this option is to override `submodule.$name.update` when set to + `merge`, `rebase` or `none`. + If the key `submodule.$name.update` is either not explicitly set or + set to `checkout`, this option is implicit. + --merge:: This option is only valid for the update command. Merge the commit recorded in the superproject into the current branch @@ -307,6 +367,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. |