Documentation/git-submodule.txt

   1 git-submodule(1)
   2 ================
   3
   4 NAME
   5 ----
   6 git-submodule - Initialize, update or inspect submodules
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'git submodule' [--quiet] add [-b branch] [--] <repository> [<path>]
  13 'git submodule' [--quiet] status [--cached] [--] [<path>...]
  14 'git submodule' [--quiet] init [--] [<path>...]
  15 'git submodule' [--quiet] update [--init] [--] [<path>...]
  16 'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...]
  17
  18
  19 COMMANDS
  20 --------
  21 add::
  22         Add the given repository as a submodule at the given path
  23         to the changeset to be committed next.  If path is a valid
  24         repository within the project, it is added as is. Otherwise,
  25         repository is cloned at the specified path. path is added to the
  26         changeset and registered in .gitmodules.   If no path is
  27         specified, the path is deduced from the repository specification.
  28         If the repository url begins with ./ or ../, it is stored as
  29         given but resolved as a relative path from the main project's
  30         url when cloning.
  31
  32 status::
  33         Show the status of the submodules. This will print the SHA-1 of the
  34         currently checked out commit for each submodule, along with the
  35         submodule path and the output of 'git-describe' for the
  36         SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not
  37         initialized and `+` if the currently checked out submodule commit
  38         does not match the SHA-1 found in the index of the containing
  39         repository. This command is the default command for 'git-submodule'.
  40
  41 init::
  42         Initialize the submodules, i.e. register in .git/config each submodule
  43         name and url found in .gitmodules. The key used in .git/config is
  44         `submodule.$name.url`. This command does not alter existing information
  45         in .git/config.
  46
  47 update::
  48         Update the registered submodules, i.e. clone missing submodules and
  49         checkout the commit specified in the index of the containing repository.
  50         This will make the submodules HEAD be detached.
  51 +
  52 If the submodule is not yet initialized, and you just want to use the
  53 setting as stored in .gitmodules, you can automatically initialize the
  54 submodule with the --init option.
  55
  56 summary::
  57         Show commit summary between the given commit (defaults to HEAD) and
  58         working tree/index. For a submodule in question, a series of commits
  59         in the submodule between the given super project commit and the
  60         index or working tree (switched by --cached) are shown.
  61
  62 OPTIONS
  63 -------
  64 -q::
  65 --quiet::
  66         Only print error messages.
  67
  68 -b::
  69 --branch::
  70         Branch of repository to add as submodule.
  71
  72 --cached::
  73         This option is only valid for status and summary commands.  These
  74         commands typically use the commit found in the submodule HEAD, but
  75         with this option, the commit stored in the index is used instead.
  76
  77 -n::
  78 --summary-limit::
  79         This option is only valid for the summary command.
  80         Limit the summary size (number of commits shown in total).
  81         Giving 0 will disable the summary; a negative number means unlimited
  82         (the default). This limit only applies to modified submodules. The
  83         size is always limited to 1 for added/deleted/typechanged submodules.
  84
  85 <path>::
  86         Path to submodule(s). When specified this will restrict the command
  87         to only operate on the submodules found at the specified paths.
  88
  89 FILES
  90 -----
  91 When initializing submodules, a .gitmodules file in the top-level directory
  92 of the containing repository is used to find the url of each submodule.
  93 This file should be formatted in the same way as `$GIT_DIR/config`. The key
  94 to each submodule url is "submodule.$name.url".  See linkgit:gitmodules[5]
  95 for details.
  96
  97
  98 AUTHOR
  99 ------
 100 Written by Lars Hjemli <hjemli@gmail.com>
 101
 102 GIT
 103 ---
 104 Part of the linkgit:git[1] suite