Merge branch 'af/maint-install-no-handlink'
[gitweb.git] / Documentation / git-submodule.txt
index 76702a0a5aa2b8825096ebf37f76d090a1c2627b..abbd5b72de5a993819dff3e3e8fe8aa9516b956b 100644 (file)
@@ -14,6 +14,49 @@ SYNOPSIS
 '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>
+
+
+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
@@ -21,7 +64,7 @@ COMMANDS
 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>.
 +
@@ -56,10 +99,15 @@ status::
        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
@@ -76,6 +124,22 @@ 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.
+
+
 OPTIONS
 -------
 -q::
@@ -99,8 +163,8 @@ OPTIONS
        (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).