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 to the current
  24         project: the current project is termed termed the "superproject".
  25 +
  26 This requires two arguments: <repository> and <path>.
  27 +
  28 <repository> is the URL of the new submodule's origin repository.
  29 This may be either an absolute URL, or (if it begins with ./
  30 or ../), the location relative to the superproject's origin
  31 repository.
  32 +
  33 <path> is the relative location for the cloned submodule to
  34 exist in the superproject. If <path> does not exist, then the
  35 submodule is created by cloning from the named URL. If <path> does
  36 exist and is already a valid git repository, then this is added
  37 to the changeset without cloning. This second form is provided
  38 to ease creating a new submodule from scratch, and presumes
  39 the user will later push the submodule to the given URL.
  40 +
  41 In either case, the given URL is recorded into .gitmodules for
  42 use by subsequent users cloning the superproject. If the URL is
  43 given relative to the superproject's repository, the presumption
  44 is the superproject and submodule repositories will be kept
  45 together in the same relative location, and only the
  46 superproject's URL need be provided: git-submodule will correctly
  47 locate the submodule using the relative URL in .gitmodules.
  48
  49 status::
  50         Show the status of the submodules. This will print the SHA-1 of the
  51         currently checked out commit for each submodule, along with the
  52         submodule path and the output of 'git-describe' for the
  53         SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not
  54         initialized and `+` if the currently checked out submodule commit
  55         does not match the SHA-1 found in the index of the containing
  56         repository. This command is the default command for 'git-submodule'.
  57
  58 init::
  59         Initialize the submodules, i.e. register in .git/config each submodule
  60         name and url found in .gitmodules. The key used in .git/config is
  61         `submodule.$name.url`. This command does not alter existing information
  62         in .git/config.
  63
  64 update::
  65         Update the registered submodules, i.e. clone missing submodules and
  66         checkout the commit specified in the index of the containing repository.
  67         This will make the submodules HEAD be detached.
  68 +
  69 If the submodule is not yet initialized, and you just want to use the
  70 setting as stored in .gitmodules, you can automatically initialize the
  71 submodule with the --init option.
  72
  73 summary::
  74         Show commit summary between the given commit (defaults to HEAD) and
  75         working tree/index. For a submodule in question, a series of commits
  76         in the submodule between the given super project commit and the
  77         index or working tree (switched by --cached) are shown.
  78
  79 OPTIONS
  80 -------
  81 -q::
  82 --quiet::
  83         Only print error messages.
  84
  85 -b::
  86 --branch::
  87         Branch of repository to add as submodule.
  88
  89 --cached::
  90         This option is only valid for status and summary commands.  These
  91         commands typically use the commit found in the submodule HEAD, but
  92         with this option, the commit stored in the index is used instead.
  93
  94 -n::
  95 --summary-limit::
  96         This option is only valid for the summary command.
  97         Limit the summary size (number of commits shown in total).
  98         Giving 0 will disable the summary; a negative number means unlimited
  99         (the default). This limit only applies to modified submodules. The
 100         size is always limited to 1 for added/deleted/typechanged submodules.
 101
 102 <path>::
 103         Path to submodule(s). When specified this will restrict the command
 104         to only operate on the submodules found at the specified paths.
 105         (This argument is required with add).
 106
 107 FILES
 108 -----
 109 When initializing submodules, a .gitmodules file in the top-level directory
 110 of the containing repository is used to find the url of each submodule.
 111 This file should be formatted in the same way as `$GIT_DIR/config`. The key
 112 to each submodule url is "submodule.$name.url".  See linkgit:gitmodules[5]
 113 for details.
 114
 115
 116 AUTHOR
 117 ------
 118 Written by Lars Hjemli <hjemli@gmail.com>
 119
 120 GIT
 121 ---
 122 Part of the linkgit:git[1] suite