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|update] [--] [<path>...]
  15
  16
  17 COMMANDS
  18 --------
  19 add::
  20         Add the given repository as a submodule at the given path
  21         to the changeset to be committed next.  If path is a valid
  22         repository within the project, it is added as is. Otherwise,
  23         repository is cloned at the specified path. path is added to the
  24         changeset and registered in .gitmodules.   If no path is
  25         specified, the path is deduced from the repository specification.
  26         If the repository url begins with ./ or ../, it is stored as
  27         given but resolved as a relative path from the main project's
  28         url when cloning.
  29
  30 status::
  31         Show the status of the submodules. This will print the SHA-1 of the
  32         currently checked out commit for each submodule, along with the
  33         submodule path and the output of linkgit:git-describe[1] for the
  34         SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not
  35         initialized and `+` if the currently checked out submodule commit
  36         does not match the SHA-1 found in the index of the containing
  37         repository. This command is the default command for git-submodule.
  38
  39 init::
  40         Initialize the submodules, i.e. register in .git/config each submodule
  41         name and url found in .gitmodules. The key used in .git/config is
  42         `submodule.$name.url`. This command does not alter existing information
  43         in .git/config.
  44
  45 update::
  46         Update the registered submodules, i.e. clone missing submodules and
  47         checkout the commit specified in the index of the containing repository.
  48         This will make the submodules HEAD be detached.
  49
  50
  51 OPTIONS
  52 -------
  53 -q, --quiet::
  54         Only print error messages.
  55
  56 -b, --branch::
  57         Branch of repository to add as submodule.
  58
  59 --cached::
  60         Display the SHA-1 stored in the index, not the SHA-1 of the currently
  61         checked out submodule commit. This option is only valid for the
  62         status command.
  63
  64 <path>::
  65         Path to submodule(s). When specified this will restrict the command
  66         to only operate on the submodules found at the specified paths.
  67
  68 FILES
  69 -----
  70 When initializing submodules, a .gitmodules file in the top-level directory
  71 of the containing repository is used to find the url of each submodule.
  72 This file should be formatted in the same way as `$GIT_DIR/config`. The key
  73 to each submodule url is "submodule.$name.url".  See linkgit:gitmodules[5]
  74 for details.
  75
  76
  77 AUTHOR
  78 ------
  79 Written by Lars Hjemli <hjemli@gmail.com>
  80
  81 GIT
  82 ---
  83 Part of the linkgit:git[7] suite