]>
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] |
c4a95c9f SP |
12 | 'git-submodule' [--quiet] add [-b branch] [--] <repository> [<path>] |
13 | 'git-submodule' [--quiet] status [--cached] [--] [<path>...] | |
be4d2c83 JS |
14 | 'git-submodule' [--quiet] init [--] [<path>...] |
15 | 'git-submodule' [--quiet] update [--init] [--] [<path>...] | |
925e7f62 | 16 | 'git-submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...] |
70c7ac22 LH |
17 | |
18 | ||
19 | COMMANDS | |
20 | -------- | |
ecda0723 SV |
21 | add:: |
22 | Add the given repository as a submodule at the given path | |
d4264ca3 ML |
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 | |
ecda0723 SV |
26 | changeset and registered in .gitmodules. If no path is |
27 | specified, the path is deduced from the repository specification. | |
f31a522a ML |
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. | |
ecda0723 | 31 | |
70c7ac22 LH |
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 | |
5162e697 | 35 | submodule path and the output of linkgit:git-describe[1] for the |
70c7ac22 LH |
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:: | |
211b7f19 | 42 | Initialize the submodules, i.e. register in .git/config each submodule |
813a0bd8 LH |
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 | |
211b7f19 | 45 | in .git/config. |
70c7ac22 LH |
46 | |
47 | update:: | |
211b7f19 LH |
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. | |
be4d2c83 JS |
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. | |
70c7ac22 | 55 | |
925e7f62 PY |
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. | |
70c7ac22 LH |
61 | |
62 | OPTIONS | |
63 | ------- | |
3240240f SB |
64 | -q:: |
65 | --quiet:: | |
70c7ac22 LH |
66 | Only print error messages. |
67 | ||
3240240f SB |
68 | -b:: |
69 | --branch:: | |
ecda0723 SV |
70 | Branch of repository to add as submodule. |
71 | ||
70c7ac22 | 72 | --cached:: |
925e7f62 PY |
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 | ||
3240240f SB |
77 | -n:: |
78 | --summary-limit:: | |
925e7f62 PY |
79 | This option is only valid for the summary command. |
80 | Limit the summary size (number of commits shown in total). | |
51836e9e | 81 | Giving 0 will disable the summary; a negative number means unlimited |
925e7f62 PY |
82 | (the default). This limit only applies to modified submodules. The |
83 | size is always limited to 1 for added/deleted/typechanged submodules. | |
70c7ac22 LH |
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 | ----- | |
211b7f19 | 91 | When initializing submodules, a .gitmodules file in the top-level directory |
70c7ac22 | 92 | of the containing repository is used to find the url of each submodule. |
c4585701 | 93 | This file should be formatted in the same way as `$GIT_DIR/config`. The key |
5162e697 | 94 | to each submodule url is "submodule.$name.url". See linkgit:gitmodules[5] |
6fbe42c7 | 95 | for details. |
70c7ac22 LH |
96 | |
97 | ||
98 | AUTHOR | |
99 | ------ | |
100 | Written by Lars Hjemli <hjemli@gmail.com> | |
101 | ||
102 | GIT | |
103 | --- | |
9e1f0a85 | 104 | Part of the linkgit:git[1] suite |