diff options
Diffstat (limited to 'Documentation/git-submodule.txt')
| -rw-r--r-- | Documentation/git-submodule.txt | 473 |
1 files changed, 0 insertions, 473 deletions
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt deleted file mode 100644 index 87d8e0f0c5..0000000000 --- a/Documentation/git-submodule.txt +++ /dev/null @@ -1,473 +0,0 @@ -git-submodule(1) -================ - -NAME ----- -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>...] -'git submodule' [--quiet] absorbgitdirs [--] [<path>...] - - -DESCRIPTION ------------ -Inspects, updates and manages submodules. - -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>] [--ref-format <format>] [--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 - project: the current project is termed the "superproject". -+ -<repository> is the URL of the new submodule's origin repository. -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 -when following the rules for relative URLs - because the evaluation -of relative URLs in Git is identical to that of relative directories). -+ -The default remote is the remote of the remote-tracking branch -of the current branch. If no such remote-tracking branch exists or -the HEAD is detached, "origin" is assumed to be the default remote. -If the superproject doesn't have a default remote configured -the superproject is its own authoritative upstream and the current -working directory is used instead. -+ -The optional argument <path> is the relative location for the cloned -submodule to exist in the superproject. If <path> is not given, the -canonical part of the source repository is used ("repo" for -"/path/to/repo.git" and "foo" for "host.xz:foo/.git"). If <path> -exists and is already a valid Git repository, then it is staged -for commit without cloning. The <path> is also used as the submodule's -logical name in its configuration entries unless `--name` is used -to specify a logical name. -+ -The given URL is recorded into `.gitmodules` for 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 needs to be provided. -git-submodule will correctly locate the submodule using the relative -URL in `.gitmodules`. -+ -If `--ref-format <format>` is specified, the ref storage format of newly -cloned submodules will be set accordingly. - -status [--cached] [--recursive] [--] [<path>...]:: - Show the status of the submodules. This will print the SHA-1 of the - currently checked out commit for each submodule, along with the - submodule path and the output of 'git describe' for the - SHA-1. Each SHA-1 will possibly be prefixed with `-` if the submodule is - not initialized, `+` if the currently checked out submodule commit - 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. -+ -If you are only interested in changes of the currently initialized -submodules with respect to the commit recorded in the index or the HEAD, -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 [--] [<path>...]:: - Initialize the submodules recorded in the index (which were - added and committed elsewhere) by setting `submodule.$name.url` - in `.git/config`, using the same setting from `.gitmodules` as - a template. If the URL is relative, it will be resolved using - the default remote. If there is no default remote, the current - repository will be assumed to be upstream. -+ -Optional <path> arguments limit which submodules will be initialized. -If no path is specified and submodule.active has been configured, submodules -configured to be active will be initialized, otherwise all submodules are -initialized. -+ -It will also copy the value of `submodule.$name.update`, if present in -the `.gitmodules` file, to `.git/config`, but (1) this command does not -alter existing information in `.git/config`, and (2) `submodule.$name.update` -that is set to a custom command is *not* copied for security reasons. -+ -You can then customize the submodule clone URLs in `.git/config` -for your local setup and proceed to `git submodule update`; -you can also just use `git submodule update --init` without -the explicit 'init' step if you do not intend to customize -any submodule locations. -+ -See the add subcommand for the definition of default remote. - -deinit [-f|--force] (--all|[--] <path>...):: - 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 working tree anymore. -+ -When the command is run without pathspec, it errors out, -instead of deinit-ing everything, to prevent mistakes. -+ -If `--force` is specified, the submodule's working tree will -be removed even if it contains local modifications. -+ -If you really want to remove a submodule from the repository and commit -that use linkgit:git-rm[1] instead. See linkgit:gitsubmodules[7] for removal -options. - -update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter-spec>] [--] [<path>...]:: -+ --- -Update the registered submodules to match what the superproject -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 -the configuration variable. If neither is given, a 'checkout' is performed. -(note: what is in `.gitmodules` file is irrelevant at this point; -see `git submodule init` above for how `.gitmodules` is used). -The 'update' procedures supported both from the command line as well as -through the `submodule.<name>.update` configuration are: - - checkout;; the commit recorded in the superproject will be - checked out in the submodule on a detached HEAD. -+ -If `--force` is specified, the submodule will be checked out (using -`git checkout --force`), even if the commit specified -in the index of the containing repository already matches the commit -checked out in the submodule. - - rebase;; the current branch of the submodule will be rebased - onto the commit recorded in the superproject. - - merge;; the commit recorded in the superproject will be merged - into the current branch in the submodule. - -The following update procedures have additional limitations: - - custom command;; mechanism for running arbitrary commands with the - commit ID as an argument. Specifically, if the - `submodule.<name>.update` configuration variable is set to - `!custom command`, the object name of the commit recorded in the - superproject for the submodule is appended to the `custom command` - string and executed. Note that this mechanism is not supported in - the `.gitmodules` file or on the command line. - - none;; the submodule is not updated. This update procedure is not - allowed on the command line. - -If the submodule is not yet initialized, and you just want to use the -setting as stored in `.gitmodules`, you can automatically initialize the -submodule with the `--init` option. - -If `--recursive` is specified, this command will recurse into the -registered submodules, and update any nested submodules within. - -If `--ref-format <format>` is specified, the ref storage format of newly -cloned submodules will be set accordingly. - -If `--filter <filter-spec>` is specified, the given partial clone filter will be -applied to the submodule. See linkgit:git-rev-list[1] for details on filter -specifications. --- -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 the remote 'HEAD'. - -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 - in the submodule between the given super project commit and the - index or working tree (switched by `--cached`) are shown. If the option - `--files` is given, show the series of commits in the submodule between - the index of the super project and the working tree of the submodule - (this option doesn't allow to use the `--cached` option or to provide an - explicit commit). -+ -Using the `--submodule=log` option with linkgit:git-diff[1] will provide that -information too. - -foreach [--recursive] <command>:: - Evaluates an arbitrary shell command in each checked out submodule. - The command has access to the variables $name, $sm_path, $displaypath, - $sha1 and $toplevel: - $name is the name of the relevant submodule section in `.gitmodules`, - $sm_path is the path of the submodule as recorded in the immediate - superproject, $displaypath contains the relative path from the - current working directory to the submodules root directory, - $sha1 is the commit as recorded in the immediate - superproject, and $toplevel is the absolute path to the top-level - of the immediate superproject. - Note that to avoid conflicts with '$PATH' on Windows, the '$path' - variable is now a deprecated synonym of '$sm_path' variable. - Any submodules defined in the superproject but not checked out are - ignored by this command. Unless given `--quiet`, foreach prints the name - of each submodule before evaluating the command. - If `--recursive` is given, submodules are traversed recursively (i.e. - the given shell command is evaluated in nested submodules as well). - A non-zero return from the command in any submodule causes - the processing to terminate. This can be overridden by adding '|| :' - to the end of the command. -+ -As an example, the command below will show the path and currently -checked out commit for each submodule: -+ --------------- -git submodule foreach 'echo $sm_path `git rev-parse HEAD`' --------------- - -sync [--recursive] [--] [<path>...]:: - Synchronizes submodules' remote URL configuration setting - to the value specified in `.gitmodules`. It will only affect those - submodules which already have a URL entry in .git/config (that is the - case when they are initialized or freshly added). 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. -+ -If `--recursive` is specified, this command will recurse into the -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 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 - superprojects git directory. -+ -A repository that was cloned independently and later added as a submodule or -old setups have the submodules git directory inside the submodule instead of -embedded into the superprojects git directory. -+ -This command is recursive by default. - -OPTIONS -------- --q:: ---quiet:: - Only print error messages. - ---progress:: - This option is only valid for add and update commands. - Progress status is reported on the standard error stream - by default when it is attached to a terminal, unless -q - is specified. This flag forces progress status even if the - standard error stream is not directed to a terminal. - ---all:: - This option is only valid for the deinit command. Unregister all - submodules in the working tree. - --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. If the - option is not specified, it defaults to the remote 'HEAD'. - --f:: ---force:: - 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 working trees will be removed even - if they contain local changes. - When running update (only effective with the checkout procedure), - 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 - containing repository matches the commit checked out in the - submodule. - ---cached:: - This option is only valid for status and summary commands. These - commands typically use the commit found in the submodule HEAD, but - with this option, the commit stored in the index is used instead. - ---files:: - This option is only valid for the summary command. This command - compares the commit in the index with that in the submodule HEAD - when this option is used. - --n:: ---summary-limit:: - This option is only valid for the summary command. - Limit the summary size (number of commits shown in total). - Giving 0 will disable the summary; a negative number means unlimited - (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 the remote `HEAD`, 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`. -+ -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 - a value other than `checkout`. - 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 - of the submodule. If this option is given, the submodule's HEAD will - not be detached. If a merge failure prevents this process, you will - have to resolve the resulting conflicts within the submodule with the - usual conflict resolution tools. - If the key `submodule.$name.update` is set to `merge`, this option is - implicit. - ---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 merge failure prevents this process, you will have - to resolve these failures with linkgit:git-rebase[1]. - If the key `submodule.$name.update` is set to `rebase`, this option is - implicit. - ---init:: - This option is only valid for the update command. - Initialize all submodules for which "git submodule init" has not been - called so far before updating. - ---name:: - This option is only valid for the add command. It sets the submodule's - name to the given string instead of defaulting to its path. The name - must be valid as a directory name and may not end with a '/'. - ---reference <repository>:: - This option is only valid for add and update commands. These - commands sometimes need to clone a remote repository. In this case, - this option will be passed to the linkgit:git-clone[1] command. -+ -*NOTE*: Do *not* use this option unless you have read the note -for linkgit:git-clone[1]'s `--reference`, `--shared`, and `--dissociate` -options carefully. - ---dissociate:: - This option is only valid for add and update commands. These - commands sometimes need to clone a remote repository. In this case, - this option will be passed to the linkgit:git-clone[1] command. -+ -*NOTE*: see the NOTE for the `--reference` option. - ---recursive:: - This option is only valid for foreach, update, status and sync commands. - Traverse submodules recursively. The operation is performed not - 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] - ---[no-]recommend-shallow:: - This option is only valid for the update command. - The initial clone of a submodule will use the recommended - `submodule.<name>.shallow` as provided by the `.gitmodules` file - by default. To ignore the suggestions use `--no-recommend-shallow`. - --j <n>:: ---jobs <n>:: - This option is only valid for the update command. - Clone new submodules in parallel with as many jobs. - Defaults to the `submodule.fetchJobs` option. - ---[no-]single-branch:: - This option is only valid for the update command. - Clone only one branch during update: HEAD or one specified by --branch. - -<path>...:: - Paths to submodule(s). When specified this will restrict the command - to only operate on the submodules found at the specified paths. - (This argument is required with add). - -FILES ------ -When initializing submodules, a `.gitmodules` file in the top-level directory -of the containing repository is used to find the url of each submodule. -This file should be formatted in the same way as `$GIT_DIR/config`. The key -to each submodule url is "submodule.$name.url". See linkgit:gitmodules[5] -for details. - -SEE ALSO --------- -linkgit:gitsubmodules[7], linkgit:gitmodules[5]. - -GIT ---- -Part of the linkgit:git[1] suite |