[git/git.git] / Documentation / git-submodule.txt
1 git-submodule(1)
2 ================
5 ----
6 git-submodule - Initialize, update or inspect submodules
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>...]
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.
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'.
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.
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.
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.
80 -------
81 -q::
82 --quiet::
83 Only print error messages.
85 -b::
86 --branch::
87 Branch of repository to add as submodule.
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.
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.
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).
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.
117 ------
118 Written by Lars Hjemli <hjemli@gmail.com>
120 GIT
121 ---
122 Part of the linkgit:git[1] suite