]>
Commit | Line | Data |
---|---|---|
70c7ac22 LH |
1 | git-submodule(1) |
2 | ================ | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-submodule - Initialize, update or inspect submodules | |
7 | ||
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
b2493649 | 11 | [verse] |
ec05df35 | 12 | 'git submodule' [--quiet] add [-b branch] [--] <repository> <path> |
b1889c36 JN |
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>...] | |
19a31f9c | 17 | 'git submodule' [--quiet] foreach <command> |
70c7ac22 LH |
18 | |
19 | ||
e38953ab PB |
20 | DESCRIPTION |
21 | ----------- | |
c47f1024 PB |
22 | Submodules allow foreign repositories to be embedded within |
23 | a dedicated subdirectory of the source tree, always pointed | |
24 | at a particular commit. | |
25 | ||
26 | They are not to be confused with remotes, which are meant mainly | |
27 | for branches of the same project; submodules are meant for | |
28 | different projects you would like to make part of your source tree, | |
29 | while the history of the two projects still stays completely | |
30 | independent and you cannot modify the contents of the submodule | |
31 | from within the main project. | |
32 | If you want to merge the project histories and want to treat the | |
33 | aggregated whole as a single project from then on, you may want to | |
34 | add a remote for the other project and use the 'subtree' merge strategy, | |
35 | instead of treating the other project as a submodule. Directories | |
36 | that come from both projects can be cloned and checked out as a whole | |
37 | if you choose to go that route. | |
38 | ||
39 | Submodules are composed from a so-called `gitlink` tree entry | |
40 | in the main repository that refers to a particular commit object | |
41 | within the inner repository that is completely separate. | |
42 | A record in the `.gitmodules` file at the root of the source | |
43 | tree assigns a logical name to the submodule and describes | |
44 | the default URL the submodule shall be cloned from. | |
45 | The logical name can be used for overriding this URL within your | |
46 | local repository configuration (see 'submodule init'). | |
47 | ||
48 | This command will manage the tree entries and contents of the | |
49 | gitmodules file for you, as well as inspect the status of your | |
50 | submodules and update them. | |
51 | When adding a new submodule to the tree, the 'add' subcommand | |
52 | is to be used. However, when pulling a tree containing submodules, | |
53 | these will not be checked out by default; | |
54 | the 'init' and 'update' subcommands will maintain submodules | |
55 | checked out and at appropriate revision in your working tree. | |
56 | You can briefly inspect the up-to-date status of your submodules | |
57 | using the 'status' subcommand and get a detailed overview of the | |
58 | difference between the index and checkouts using the 'summary' | |
59 | subcommand. | |
e38953ab PB |
60 | |
61 | ||
70c7ac22 LH |
62 | COMMANDS |
63 | -------- | |
ecda0723 SV |
64 | add:: |
65 | Add the given repository as a submodule at the given path | |
ec05df35 | 66 | to the changeset to be committed next to the current |
77ef80a8 | 67 | project: the current project is termed the "superproject". |
ec05df35 ML |
68 | + |
69 | This requires two arguments: <repository> and <path>. | |
70 | + | |
71 | <repository> is the URL of the new submodule's origin repository. | |
72 | This may be either an absolute URL, or (if it begins with ./ | |
73 | or ../), the location relative to the superproject's origin | |
74 | repository. | |
75 | + | |
76 | <path> is the relative location for the cloned submodule to | |
77 | exist in the superproject. If <path> does not exist, then the | |
78 | submodule is created by cloning from the named URL. If <path> does | |
79 | exist and is already a valid git repository, then this is added | |
80 | to the changeset without cloning. This second form is provided | |
81 | to ease creating a new submodule from scratch, and presumes | |
82 | the user will later push the submodule to the given URL. | |
83 | + | |
84 | In either case, the given URL is recorded into .gitmodules for | |
85 | use by subsequent users cloning the superproject. If the URL is | |
86 | given relative to the superproject's repository, the presumption | |
87 | is the superproject and submodule repositories will be kept | |
88 | together in the same relative location, and only the | |
89 | superproject's URL need be provided: git-submodule will correctly | |
90 | locate the submodule using the relative URL in .gitmodules. | |
ecda0723 | 91 | |
70c7ac22 LH |
92 | status:: |
93 | Show the status of the submodules. This will print the SHA-1 of the | |
94 | currently checked out commit for each submodule, along with the | |
ba020ef5 | 95 | submodule path and the output of 'git-describe' for the |
70c7ac22 LH |
96 | SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not |
97 | initialized and `+` if the currently checked out submodule commit | |
98 | does not match the SHA-1 found in the index of the containing | |
ba020ef5 | 99 | repository. This command is the default command for 'git-submodule'. |
70c7ac22 LH |
100 | |
101 | init:: | |
c47f1024 PB |
102 | Initialize the submodules, i.e. register each submodule name |
103 | and url found in .gitmodules into .git/config. | |
104 | The key used in .git/config is `submodule.$name.url`. | |
105 | This command does not alter existing information in .git/config. | |
106 | You can then customize the submodule clone URLs in .git/config | |
107 | for your local setup and proceed to 'git submodule update'; | |
108 | you can also just use 'git submodule update --init' without | |
109 | the explicit 'init' step if you do not intend to customize | |
110 | any submodule locations. | |
70c7ac22 LH |
111 | |
112 | update:: | |
211b7f19 LH |
113 | Update the registered submodules, i.e. clone missing submodules and |
114 | checkout the commit specified in the index of the containing repository. | |
115 | This will make the submodules HEAD be detached. | |
be4d2c83 JS |
116 | + |
117 | If the submodule is not yet initialized, and you just want to use the | |
118 | setting as stored in .gitmodules, you can automatically initialize the | |
119 | submodule with the --init option. | |
70c7ac22 | 120 | |
925e7f62 PY |
121 | summary:: |
122 | Show commit summary between the given commit (defaults to HEAD) and | |
123 | working tree/index. For a submodule in question, a series of commits | |
124 | in the submodule between the given super project commit and the | |
125 | index or working tree (switched by --cached) are shown. | |
70c7ac22 | 126 | |
19a31f9c ML |
127 | foreach:: |
128 | Evaluates an arbitrary shell command in each checked out submodule. | |
129 | The command has access to the variables $path and $sha1: | |
130 | $path is the name of the submodule directory relative to the | |
131 | superproject, and $sha1 is the commit as recorded in the superproject. | |
132 | Any submodules defined in the superproject but not checked out are | |
133 | ignored by this command. Unless given --quiet, foreach prints the name | |
134 | of each submodule before evaluating the command. | |
135 | A non-zero return from the command in any submodule causes | |
136 | the processing to terminate. This can be overridden by adding '|| :' | |
137 | to the end of the command. | |
138 | + | |
139 | As an example, "git submodule foreach 'echo $path `git rev-parse HEAD`' will | |
140 | show the path and currently checked out commit for each submodule. | |
141 | ||
142 | ||
70c7ac22 LH |
143 | OPTIONS |
144 | ------- | |
3240240f SB |
145 | -q:: |
146 | --quiet:: | |
70c7ac22 LH |
147 | Only print error messages. |
148 | ||
3240240f SB |
149 | -b:: |
150 | --branch:: | |
ecda0723 SV |
151 | Branch of repository to add as submodule. |
152 | ||
70c7ac22 | 153 | --cached:: |
925e7f62 PY |
154 | This option is only valid for status and summary commands. These |
155 | commands typically use the commit found in the submodule HEAD, but | |
156 | with this option, the commit stored in the index is used instead. | |
157 | ||
3240240f SB |
158 | -n:: |
159 | --summary-limit:: | |
925e7f62 PY |
160 | This option is only valid for the summary command. |
161 | Limit the summary size (number of commits shown in total). | |
51836e9e | 162 | Giving 0 will disable the summary; a negative number means unlimited |
925e7f62 PY |
163 | (the default). This limit only applies to modified submodules. The |
164 | size is always limited to 1 for added/deleted/typechanged submodules. | |
70c7ac22 | 165 | |
f448e24e AMS |
166 | <path>...:: |
167 | Paths to submodule(s). When specified this will restrict the command | |
70c7ac22 | 168 | to only operate on the submodules found at the specified paths. |
ec05df35 | 169 | (This argument is required with add). |
70c7ac22 LH |
170 | |
171 | FILES | |
172 | ----- | |
211b7f19 | 173 | When initializing submodules, a .gitmodules file in the top-level directory |
70c7ac22 | 174 | of the containing repository is used to find the url of each submodule. |
c4585701 | 175 | This file should be formatted in the same way as `$GIT_DIR/config`. The key |
5162e697 | 176 | to each submodule url is "submodule.$name.url". See linkgit:gitmodules[5] |
6fbe42c7 | 177 | for details. |
70c7ac22 LH |
178 | |
179 | ||
180 | AUTHOR | |
181 | ------ | |
182 | Written by Lars Hjemli <hjemli@gmail.com> | |
183 | ||
184 | GIT | |
185 | --- | |
9e1f0a85 | 186 | Part of the linkgit:git[1] suite |