X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fgit-submodule.txt;h=2f207fbbda04c176cedd5a88c88f74e2ac97cf2e;hb=bd9efbf35424c9436f62768e47f5819c9b5bcf9e;hp=441ae1483bf57aca849c0470c6e19e963c9ebf19;hpb=438d2991eaa17549df67929cd4558d65840c37d7;p=git.git diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 441ae1483..2f207fbbd 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -9,40 +9,106 @@ git-submodule - Initialize, update or inspect submodules SYNOPSIS -------- [verse] -'git-submodule' [--quiet] add [-b branch] [--] [] -'git-submodule' [--quiet] status [--cached] [--] [...] -'git-submodule' [--quiet] init [--] [...] -'git-submodule' [--quiet] update [--init] [--] [...] -'git-submodule' [--quiet] summary [--summary-limit ] [commit] [--] [...] +'git submodule' [--quiet] add [-b branch] [--] +'git submodule' [--quiet] status [--cached] [--] [...] +'git submodule' [--quiet] init [--] [...] +'git submodule' [--quiet] update [--init] [--] [...] +'git submodule' [--quiet] summary [--summary-limit ] [commit] [--] [...] +'git submodule' [--quiet] foreach +'git submodule' [--quiet] sync [--] [...] + + +DESCRIPTION +----------- +Submodules allow foreign repositories to be embedded within +a dedicated subdirectory of the source tree, always pointed +at a particular commit. + +They are not to be confused with remotes, which are meant mainly +for branches of the same project; submodules are meant for +different projects you would like to make part of your source tree, +while the history of the two projects still stays completely +independent and you cannot modify the contents of the submodule +from within the main project. +If you want to merge the project histories and want to treat the +aggregated whole as a single project from then on, you may want to +add a remote for the other project and use the 'subtree' merge strategy, +instead of treating the other project as a submodule. Directories +that come from both projects can be cloned and checked out as a whole +if you choose to go that route. + +Submodules are composed from a so-called `gitlink` tree entry +in the main repository that refers to a particular commit object +within the inner repository that is completely separate. +A record in the `.gitmodules` file at the root of the source +tree assigns a logical name to the submodule and describes +the default URL the submodule shall be cloned from. +The logical name can be used for overriding this URL within your +local repository configuration (see 'submodule init'). + +This command will manage the tree entries and contents of the +gitmodules file for you, as well as inspect the status of your +submodules and update them. +When adding a new submodule to the tree, the 'add' subcommand +is to be used. However, when pulling a tree containing submodules, +these will not be checked out by default; +the 'init' and 'update' subcommands will maintain submodules +checked out and at appropriate revision in your working tree. +You can briefly inspect the up-to-date status of your submodules +using the 'status' subcommand and get a detailed overview of the +difference between the index and checkouts using the 'summary' +subcommand. COMMANDS -------- add:: Add the given repository as a submodule at the given path - to the changeset to be committed next. If path is a valid - repository within the project, it is added as is. Otherwise, - repository is cloned at the specified path. path is added to the - changeset and registered in .gitmodules. If no path is - specified, the path is deduced from the repository specification. - If the repository url begins with ./ or ../, it is stored as - given but resolved as a relative path from the main project's - url when cloning. + to the changeset to be committed next to the current + project: the current project is termed the "superproject". ++ +This requires two arguments: and . ++ + 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 origin +repository. ++ + is the relative location for the cloned submodule to +exist in the superproject. If does not exist, then the +submodule is created by cloning from the named URL. If does +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. ++ +In either case, 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. status:: 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 linkgit:git-describe[1] for the + submodule path and the output of 'git-describe' for the SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not initialized and `+` if the currently checked out submodule commit does not match the SHA-1 found in the index of the containing - repository. This command is the default command for git-submodule. + repository. This command is the default command for 'git-submodule'. init:: - Initialize the submodules, i.e. register in .git/config each submodule - name and url found in .gitmodules. The key used in .git/config is - `submodule.$name.url`. This command does not alter existing information - in .git/config. + Initialize the submodules, i.e. register each submodule name + and url found in .gitmodules into .git/config. + The key used in .git/config is `submodule.$name.url`. + This command does not alter existing information in .git/config. + 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. update:: Update the registered submodules, i.e. clone missing submodules and @@ -59,6 +125,30 @@ summary:: in the submodule between the given super project commit and the index or working tree (switched by --cached) are shown. +foreach:: + Evaluates an arbitrary shell command in each checked out submodule. + The command has access to the variables $path and $sha1: + $path is the name of the submodule directory relative to the + superproject, and $sha1 is the commit as recorded in the superproject. + 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. + 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, "git submodule foreach 'echo $path `git rev-parse HEAD`' will +show the path and currently checked out commit for each submodule. + +sync:: + Synchronizes submodules' remote URL configuration setting + to the value specified in .gitmodules. 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. + OPTIONS ------- -q:: @@ -82,9 +172,10 @@ OPTIONS (the default). This limit only applies to modified submodules. The size is always limited to 1 for added/deleted/typechanged submodules. -:: - Path to submodule(s). When specified this will restrict the command +...:: + 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 -----