Documentation / git-submodule.txton commit Merge branch 'ap/maint-diff-rename-avoid-overlap' into maint-1.8.1 (8f780ca)
   1git-submodule(1)
   2================
   3
   4NAME
   5----
   6git-submodule - Initialize, update or inspect submodules
   7
   8
   9SYNOPSIS
  10--------
  11[verse]
  12'git submodule' [--quiet] add [-b <branch>] [-f|--force] [--name <name>]
  13              [--reference <repository>] [--] <repository> [<path>]
  14'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...]
  15'git submodule' [--quiet] init [--] [<path>...]
  16'git submodule' [--quiet] update [--init] [-N|--no-fetch] [-f|--force] [--rebase]
  17              [--reference <repository>] [--merge] [--recursive] [--] [<path>...]
  18'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]
  19              [commit] [--] [<path>...]
  20'git submodule' [--quiet] foreach [--recursive] <command>
  21'git submodule' [--quiet] sync [--] [<path>...]
  22
  23
  24DESCRIPTION
  25-----------
  26Submodules allow foreign repositories to be embedded within
  27a dedicated subdirectory of the source tree, always pointed
  28at a particular commit.
  29
  30They are not to be confused with remotes, which are meant mainly
  31for branches of the same project; submodules are meant for
  32different projects you would like to make part of your source tree,
  33while the history of the two projects still stays completely
  34independent and you cannot modify the contents of the submodule
  35from within the main project.
  36If you want to merge the project histories and want to treat the
  37aggregated whole as a single project from then on, you may want to
  38add a remote for the other project and use the 'subtree' merge strategy,
  39instead of treating the other project as a submodule. Directories
  40that come from both projects can be cloned and checked out as a whole
  41if you choose to go that route.
  42
  43Submodules are composed from a so-called `gitlink` tree entry
  44in the main repository that refers to a particular commit object
  45within the inner repository that is completely separate.
  46A record in the `.gitmodules` (see linkgit:gitmodules[5]) file at the
  47root of the source tree assigns a logical name to the submodule and
  48describes the default URL the submodule shall be cloned from.
  49The logical name can be used for overriding this URL within your
  50local repository configuration (see 'submodule init').
  51
  52This command will manage the tree entries and contents of the
  53gitmodules file for you, as well as inspect the status of your
  54submodules and update them.
  55When adding a new submodule to the tree, the 'add' subcommand
  56is to be used.  However, when pulling a tree containing submodules,
  57these will not be checked out by default;
  58the 'init' and 'update' subcommands will maintain submodules
  59checked out and at appropriate revision in your working tree.
  60You can briefly inspect the up-to-date status of your submodules
  61using the 'status' subcommand and get a detailed overview of the
  62difference between the index and checkouts using the 'summary'
  63subcommand.
  64
  65
  66COMMANDS
  67--------
  68add::
  69        Add the given repository as a submodule at the given path
  70        to the changeset to be committed next to the current
  71        project: the current project is termed the "superproject".
  72+
  73This requires at least one argument: <repository>. The optional
  74argument <path> is the relative location for the cloned submodule
  75to exist in the superproject. If <path> is not given, the
  76"humanish" part of the source repository is used ("repo" for
  77"/path/to/repo.git" and "foo" for "host.xz:foo/.git").
  78+
  79<repository> is the URL of the new submodule's origin repository.
  80This may be either an absolute URL, or (if it begins with ./
  81or ../), the location relative to the superproject's origin
  82repository (Please note that to specify a repository 'foo.git'
  83which is located right next to a superproject 'bar.git', you'll
  84have to use '../foo.git' instead of './foo.git' - as one might expect
  85when following the rules for relative URLs - because the evaluation
  86of relative URLs in Git is identical to that of relative directories).
  87If the superproject doesn't have an origin configured
  88the superproject is its own authoritative upstream and the current
  89working directory is used instead.
  90+
  91<path> is the relative location for the cloned submodule to
  92exist in the superproject. If <path> does not exist, then the
  93submodule is created by cloning from the named URL. If <path> does
  94exist and is already a valid git repository, then this is added
  95to the changeset without cloning. This second form is provided
  96to ease creating a new submodule from scratch, and presumes
  97the user will later push the submodule to the given URL.
  98+
  99In either case, the given URL is recorded into .gitmodules for
 100use by subsequent users cloning the superproject. If the URL is
 101given relative to the superproject's repository, the presumption
 102is the superproject and submodule repositories will be kept
 103together in the same relative location, and only the
 104superproject's URL needs to be provided: git-submodule will correctly
 105locate the submodule using the relative URL in .gitmodules.
 106
 107status::
 108        Show the status of the submodules. This will print the SHA-1 of the
 109        currently checked out commit for each submodule, along with the
 110        submodule path and the output of 'git describe' for the
 111        SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not
 112        initialized, `+` if the currently checked out submodule commit
 113        does not match the SHA-1 found in the index of the containing
 114        repository and `U` if the submodule has merge conflicts.
 115+
 116If `--recursive` is specified, this command will recurse into nested
 117submodules, and show their status as well.
 118+
 119If you are only interested in changes of the currently initialized
 120submodules with respect to the commit recorded in the index or the HEAD,
 121linkgit:git-status[1] and linkgit:git-diff[1] will provide that information
 122too (and can also report changes to a submodule's work tree).
 123
 124init::
 125        Initialize the submodules, i.e. register each submodule name
 126        and url found in .gitmodules into .git/config.
 127        It will also copy the value of `submodule.$name.update` into
 128        .git/config.
 129        The key used in .git/config is `submodule.$name.url`.
 130        This command does not alter existing information in .git/config.
 131        You can then customize the submodule clone URLs in .git/config
 132        for your local setup and proceed to `git submodule update`;
 133        you can also just use `git submodule update --init` without
 134        the explicit 'init' step if you do not intend to customize
 135        any submodule locations.
 136
 137update::
 138        Update the registered submodules, i.e. clone missing submodules and
 139        checkout the commit specified in the index of the containing repository.
 140        This will make the submodules HEAD be detached unless `--rebase` or
 141        `--merge` is specified or the key `submodule.$name.update` is set to
 142        `rebase`, `merge` or `none`. `none` can be overridden by specifying
 143        `--checkout`.
 144+
 145If the submodule is not yet initialized, and you just want to use the
 146setting as stored in .gitmodules, you can automatically initialize the
 147submodule with the `--init` option.
 148+
 149If `--recursive` is specified, this command will recurse into the
 150registered submodules, and update any nested submodules within.
 151+
 152If `--force` is specified, the submodule will be checked out (using
 153`git checkout --force` if appropriate), even if the commit specified in the
 154index of the containing repository already matches the commit checked out in
 155the submodule.
 156
 157summary::
 158        Show commit summary between the given commit (defaults to HEAD) and
 159        working tree/index. For a submodule in question, a series of commits
 160        in the submodule between the given super project commit and the
 161        index or working tree (switched by `--cached`) are shown. If the option
 162        `--files` is given, show the series of commits in the submodule between
 163        the index of the super project and the working tree of the submodule
 164        (this option doesn't allow to use the `--cached` option or to provide an
 165        explicit commit).
 166+
 167Using the `--submodule=log` option with linkgit:git-diff[1] will provide that
 168information too.
 169
 170foreach::
 171        Evaluates an arbitrary shell command in each checked out submodule.
 172        The command has access to the variables $name, $path, $sha1 and
 173        $toplevel:
 174        $name is the name of the relevant submodule section in .gitmodules,
 175        $path is the name of the submodule directory relative to the
 176        superproject, $sha1 is the commit as recorded in the superproject,
 177        and $toplevel is the absolute path to the top-level of the superproject.
 178        Any submodules defined in the superproject but not checked out are
 179        ignored by this command. Unless given `--quiet`, foreach prints the name
 180        of each submodule before evaluating the command.
 181        If `--recursive` is given, submodules are traversed recursively (i.e.
 182        the given shell command is evaluated in nested submodules as well).
 183        A non-zero return from the command in any submodule causes
 184        the processing to terminate. This can be overridden by adding '|| :'
 185        to the end of the command.
 186+
 187As an example, +git submodule foreach \'echo $path {backtick}git
 188rev-parse HEAD{backtick}'+ will show the path and currently checked out
 189commit for each submodule.
 190
 191sync::
 192        Synchronizes submodules' remote URL configuration setting
 193        to the value specified in .gitmodules. It will only affect those
 194        submodules which already have a URL entry in .git/config (that is the
 195        case when they are initialized or freshly added). This is useful when
 196        submodule URLs change upstream and you need to update your local
 197        repositories accordingly.
 198+
 199"git submodule sync" synchronizes all submodules while
 200"git submodule sync \-- A" synchronizes submodule "A" only.
 201
 202OPTIONS
 203-------
 204-q::
 205--quiet::
 206        Only print error messages.
 207
 208-b::
 209--branch::
 210        Branch of repository to add as submodule.
 211
 212-f::
 213--force::
 214        This option is only valid for add and update commands.
 215        When running add, allow adding an otherwise ignored submodule path.
 216        When running update, throw away local changes in submodules when
 217        switching to a different commit; and always run a checkout operation
 218        in the submodule, even if the commit listed in the index of the
 219        containing repository matches the commit checked out in the submodule.
 220
 221--cached::
 222        This option is only valid for status and summary commands.  These
 223        commands typically use the commit found in the submodule HEAD, but
 224        with this option, the commit stored in the index is used instead.
 225
 226--files::
 227        This option is only valid for the summary command. This command
 228        compares the commit in the index with that in the submodule HEAD
 229        when this option is used.
 230
 231-n::
 232--summary-limit::
 233        This option is only valid for the summary command.
 234        Limit the summary size (number of commits shown in total).
 235        Giving 0 will disable the summary; a negative number means unlimited
 236        (the default). This limit only applies to modified submodules. The
 237        size is always limited to 1 for added/deleted/typechanged submodules.
 238
 239-N::
 240--no-fetch::
 241        This option is only valid for the update command.
 242        Don't fetch new objects from the remote site.
 243
 244--merge::
 245        This option is only valid for the update command.
 246        Merge the commit recorded in the superproject into the current branch
 247        of the submodule. If this option is given, the submodule's HEAD will
 248        not be detached. If a merge failure prevents this process, you will
 249        have to resolve the resulting conflicts within the submodule with the
 250        usual conflict resolution tools.
 251        If the key `submodule.$name.update` is set to `merge`, this option is
 252        implicit.
 253
 254--rebase::
 255        This option is only valid for the update command.
 256        Rebase the current branch onto the commit recorded in the
 257        superproject. If this option is given, the submodule's HEAD will not
 258        be detached. If a merge failure prevents this process, you will have
 259        to resolve these failures with linkgit:git-rebase[1].
 260        If the key `submodule.$name.update` is set to `rebase`, this option is
 261        implicit.
 262
 263--init::
 264        This option is only valid for the update command.
 265        Initialize all submodules for which "git submodule init" has not been
 266        called so far before updating.
 267
 268--name::
 269        This option is only valid for the add command. It sets the submodule's
 270        name to the given string instead of defaulting to its path. The name
 271        must be valid as a directory name and may not end with a '/'.
 272
 273--reference <repository>::
 274        This option is only valid for add and update commands.  These
 275        commands sometimes need to clone a remote repository. In this case,
 276        this option will be passed to the linkgit:git-clone[1] command.
 277+
 278*NOTE*: Do *not* use this option unless you have read the note
 279for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully.
 280
 281--recursive::
 282        This option is only valid for foreach, update and status commands.
 283        Traverse submodules recursively. The operation is performed not
 284        only in the submodules of the current repo, but also
 285        in any nested submodules inside those submodules (and so on).
 286
 287<path>...::
 288        Paths to submodule(s). When specified this will restrict the command
 289        to only operate on the submodules found at the specified paths.
 290        (This argument is required with add).
 291
 292FILES
 293-----
 294When initializing submodules, a .gitmodules file in the top-level directory
 295of the containing repository is used to find the url of each submodule.
 296This file should be formatted in the same way as `$GIT_DIR/config`. The key
 297to each submodule url is "submodule.$name.url".  See linkgit:gitmodules[5]
 298for details.
 299
 300GIT
 301---
 302Part of the linkgit:git[1] suite