![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
index 76702a0a5aa2b8825096ebf37f76d090a1c2627b..babaa9bc46a404c4610abc4e4c4281b6c5c5ea6c 100644 (file)
'git submodule' [--quiet] init [--] [<path>...]
'git submodule' [--quiet] update [--init] [--] [<path>...]
'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...]
'git submodule' [--quiet] init [--] [<path>...]
'git submodule' [--quiet] update [--init] [--] [<path>...]
'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...]
+'git submodule' [--quiet] foreach <command>
+'git submodule' [--quiet] sync [--] [<path>...]
+
+
+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
COMMANDS
add::
Add the given repository as a submodule at the given path
to the changeset to be committed next to the current
add::
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 termed the "superproject".
+ project: the current project is termed the "superproject".
+
This requires two arguments: <repository> and <path>.
+
+
This requires two arguments: <repository> and <path>.
+
repository. This command is the default command for 'git-submodule'.
init::
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
update::
Update the registered submodules, i.e. clone missing submodules and
in the submodule between the given super project commit and the
index or working tree (switched by --cached) are shown.
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::
OPTIONS
-------
-q::
(the default). This limit only applies to modified submodules. The
size is always limited to 1 for added/deleted/typechanged submodules.
(the default). This limit only applies to modified submodules. The
size is always limited to 1 for added/deleted/typechanged submodules.
-<path>::
- Path to submodule(s). When specified this will restrict the command
+<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).
to only operate on the submodules found at the specified paths.
(This argument is required with add).