]>
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>...] | |
70c7ac22 LH |
17 | |
18 | ||
e38953ab PB |
19 | DESCRIPTION |
20 | ----------- | |
21 | Submodules are a special kind of tree entries which refer to a particular tree | |
22 | state in another repository. The tree entry describes | |
23 | the existence of a submodule with the given name and the exact revision that | |
24 | should be used, while an entry in `.gitmodules` file gives the location of | |
25 | the repository. | |
26 | ||
27 | When checked out, submodules will maintain their own independent repositories | |
28 | within their directories; the only link between the submodule and the "parent | |
29 | project" is the tree entry within the parent project mentioned above. | |
30 | ||
31 | This command will manage the tree entries and contents of the gitmodules file | |
32 | for you, as well as inspecting the status of your submodules and updating them. | |
33 | When adding a new submodule to the tree, the 'add' subcommand is to be used. | |
34 | However, when pulling a tree containing submodules, these will not be checked | |
35 | out by default; the 'init' and 'update' subcommands will maintain submodules | |
36 | checked out and at appropriate revision in your working tree. You can inspect | |
37 | the current status of your submodules using the 'submodule' subcommand and get | |
38 | an overview of changes 'update' would perform using the 'summary' subcommand. | |
39 | ||
40 | ||
70c7ac22 LH |
41 | COMMANDS |
42 | -------- | |
ecda0723 SV |
43 | add:: |
44 | Add the given repository as a submodule at the given path | |
ec05df35 ML |
45 | to the changeset to be committed next to the current |
46 | project: the current project is termed termed the "superproject". | |
47 | + | |
48 | This requires two arguments: <repository> and <path>. | |
49 | + | |
50 | <repository> is the URL of the new submodule's origin repository. | |
51 | This may be either an absolute URL, or (if it begins with ./ | |
52 | or ../), the location relative to the superproject's origin | |
53 | repository. | |
54 | + | |
55 | <path> is the relative location for the cloned submodule to | |
56 | exist in the superproject. If <path> does not exist, then the | |
57 | submodule is created by cloning from the named URL. If <path> does | |
58 | exist and is already a valid git repository, then this is added | |
59 | to the changeset without cloning. This second form is provided | |
60 | to ease creating a new submodule from scratch, and presumes | |
61 | the user will later push the submodule to the given URL. | |
62 | + | |
63 | In either case, the given URL is recorded into .gitmodules for | |
64 | use by subsequent users cloning the superproject. If the URL is | |
65 | given relative to the superproject's repository, the presumption | |
66 | is the superproject and submodule repositories will be kept | |
67 | together in the same relative location, and only the | |
68 | superproject's URL need be provided: git-submodule will correctly | |
69 | locate the submodule using the relative URL in .gitmodules. | |
ecda0723 | 70 | |
70c7ac22 LH |
71 | status:: |
72 | Show the status of the submodules. This will print the SHA-1 of the | |
73 | currently checked out commit for each submodule, along with the | |
ba020ef5 | 74 | submodule path and the output of 'git-describe' for the |
70c7ac22 LH |
75 | SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not |
76 | initialized and `+` if the currently checked out submodule commit | |
77 | does not match the SHA-1 found in the index of the containing | |
ba020ef5 | 78 | repository. This command is the default command for 'git-submodule'. |
70c7ac22 LH |
79 | |
80 | init:: | |
211b7f19 | 81 | Initialize the submodules, i.e. register in .git/config each submodule |
813a0bd8 LH |
82 | name and url found in .gitmodules. The key used in .git/config is |
83 | `submodule.$name.url`. This command does not alter existing information | |
211b7f19 | 84 | in .git/config. |
70c7ac22 LH |
85 | |
86 | update:: | |
211b7f19 LH |
87 | Update the registered submodules, i.e. clone missing submodules and |
88 | checkout the commit specified in the index of the containing repository. | |
89 | This will make the submodules HEAD be detached. | |
be4d2c83 JS |
90 | + |
91 | If the submodule is not yet initialized, and you just want to use the | |
92 | setting as stored in .gitmodules, you can automatically initialize the | |
93 | submodule with the --init option. | |
70c7ac22 | 94 | |
925e7f62 PY |
95 | summary:: |
96 | Show commit summary between the given commit (defaults to HEAD) and | |
97 | working tree/index. For a submodule in question, a series of commits | |
98 | in the submodule between the given super project commit and the | |
99 | index or working tree (switched by --cached) are shown. | |
70c7ac22 LH |
100 | |
101 | OPTIONS | |
102 | ------- | |
3240240f SB |
103 | -q:: |
104 | --quiet:: | |
70c7ac22 LH |
105 | Only print error messages. |
106 | ||
3240240f SB |
107 | -b:: |
108 | --branch:: | |
ecda0723 SV |
109 | Branch of repository to add as submodule. |
110 | ||
70c7ac22 | 111 | --cached:: |
925e7f62 PY |
112 | This option is only valid for status and summary commands. These |
113 | commands typically use the commit found in the submodule HEAD, but | |
114 | with this option, the commit stored in the index is used instead. | |
115 | ||
3240240f SB |
116 | -n:: |
117 | --summary-limit:: | |
925e7f62 PY |
118 | This option is only valid for the summary command. |
119 | Limit the summary size (number of commits shown in total). | |
51836e9e | 120 | Giving 0 will disable the summary; a negative number means unlimited |
925e7f62 PY |
121 | (the default). This limit only applies to modified submodules. The |
122 | size is always limited to 1 for added/deleted/typechanged submodules. | |
70c7ac22 LH |
123 | |
124 | <path>:: | |
125 | Path to submodule(s). When specified this will restrict the command | |
126 | to only operate on the submodules found at the specified paths. | |
ec05df35 | 127 | (This argument is required with add). |
70c7ac22 LH |
128 | |
129 | FILES | |
130 | ----- | |
211b7f19 | 131 | When initializing submodules, a .gitmodules file in the top-level directory |
70c7ac22 | 132 | of the containing repository is used to find the url of each submodule. |
c4585701 | 133 | This file should be formatted in the same way as `$GIT_DIR/config`. The key |
5162e697 | 134 | to each submodule url is "submodule.$name.url". See linkgit:gitmodules[5] |
6fbe42c7 | 135 | for details. |
70c7ac22 LH |
136 | |
137 | ||
138 | AUTHOR | |
139 | ------ | |
140 | Written by Lars Hjemli <hjemli@gmail.com> | |
141 | ||
142 | GIT | |
143 | --- | |
9e1f0a85 | 144 | Part of the linkgit:git[1] suite |