Merge branch 'maint-1.5.6' into maint-1.6.0
[gitweb.git] / Documentation / git-submodule.txt
index e818e6e7895a94af0b05f04d2c8ecdae64583efd..e6652a7de1b44679cf97c35220018f1ff3fbada2 100644 (file)
@@ -9,60 +9,147 @@ git-submodule - Initialize, update or inspect submodules
 SYNOPSIS
 --------
 [verse]
-'git-submodule' [--quiet] add [-b branch] [--] <repository> [<path>]
-'git-submodule' [--quiet] status [--cached] [--] [<path>...]
-'git-submodule' [--quiet] [init|update] [--] [<path>...]
+'git submodule' [--quiet] add [-b branch] [--] <repository> <path>
+'git submodule' [--quiet] status [--cached] [--] [<path>...]
+'git submodule' [--quiet] init [--] [<path>...]
+'git submodule' [--quiet] update [--init] [--] [<path>...]
+'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<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
 --------
 add::
        Add the given repository as a submodule at the given path
-       to the changeset to be committed next.  In particular, the
-       repository is cloned at the specified path, 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: <repository> and <path>.
++
+<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 origin
+repository.
++
+<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
+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
        checkout the commit specified in the index of the containing repository.
        This will make the submodules HEAD be detached.
++
+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.
 
+summary::
+       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.
 
 OPTIONS
 -------
--q, --quiet::
+-q::
+--quiet::
        Only print error messages.
 
--b, --branch::
+-b::
+--branch::
        Branch of repository to add as submodule.
 
 --cached::
-       Display the SHA-1 stored in the index, not the SHA-1 of the currently
-       checked out submodule commit. This option is only valid for the
-       status command.
-
-<path>::
-       Path to submodule(s). When specified this will restrict the command
+       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.
+
+-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.
+
+<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
 -----
@@ -79,4 +166,4 @@ Written by Lars Hjemli <hjemli@gmail.com>
 
 GIT
 ---
-Part of the linkgit:git[7] suite
+Part of the linkgit:git[1] suite