You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
169 lines
6.6 KiB
169 lines
6.6 KiB
git-submodule(1) |
|
================ |
|
|
|
NAME |
|
---- |
|
git-submodule - Initialize, update or inspect submodules |
|
|
|
|
|
SYNOPSIS |
|
-------- |
|
[verse] |
|
'git submodule' [--quiet] add [-b branch] [--] <repository> <path> |
|
'git submodule' [--quiet] status [--cached] [--] [<path>...] |
|
'git submodule' [--quiet] init [--] [<path>...] |
|
'git submodule' [--quiet] update [--init] [--] [<path>...] |
|
'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...] |
|
|
|
|
|
DESCRIPTION |
|
----------- |
|
Submodules allow foreign repositories to be embedded within |
|
a dedicated subdirectory of the source tree, always pointed |
|
at a particular commit. |
|
|
|
They are not to be confused with remotes, which are meant mainly |
|
for branches of the same project; submodules are meant for |
|
different projects you would like to make part of your source tree, |
|
while the history of the two projects still stays completely |
|
independent and you cannot modify the contents of the submodule |
|
from within the main project. |
|
If you want to merge the project histories and want to treat the |
|
aggregated whole as a single project from then on, you may want to |
|
add a remote for the other project and use the 'subtree' merge strategy, |
|
instead of treating the other project as a submodule. Directories |
|
that come from both projects can be cloned and checked out as a whole |
|
if you choose to go that route. |
|
|
|
Submodules are composed from a so-called `gitlink` tree entry |
|
in the main repository that refers to a particular commit object |
|
within the inner repository that is completely separate. |
|
A record in the `.gitmodules` file at the root of the source |
|
tree assigns a logical name to the submodule and describes |
|
the default URL the submodule shall be cloned from. |
|
The logical name can be used for overriding this URL within your |
|
local repository configuration (see 'submodule init'). |
|
|
|
This command will manage the tree entries and contents of the |
|
gitmodules file for you, as well as inspect the status of your |
|
submodules and update them. |
|
When adding a new submodule to the tree, the 'add' subcommand |
|
is to be used. However, when pulling a tree containing submodules, |
|
these will not be checked out by default; |
|
the 'init' and 'update' subcommands will maintain submodules |
|
checked out and at appropriate revision in your working tree. |
|
You can briefly inspect the up-to-date status of your submodules |
|
using the 'status' subcommand and get a detailed overview of the |
|
difference between the index and checkouts using the 'summary' |
|
subcommand. |
|
|
|
|
|
COMMANDS |
|
-------- |
|
add:: |
|
Add the given repository as a submodule at the given path |
|
to the changeset to be committed next to the current |
|
project: the current project is termed termed the "superproject". |
|
+ |
|
This requires two arguments: <repository> and <path>. |
|
+ |
|
<repository> is the URL of the new submodule's origin repository. |
|
This may be either an absolute URL, or (if it begins with ./ |
|
or ../), the location relative to the superproject's origin |
|
repository. |
|
+ |
|
<path> is the relative location for the cloned submodule to |
|
exist in the superproject. If <path> does not exist, then the |
|
submodule is created by cloning from the named URL. If <path> does |
|
exist and is already a valid git repository, then this is added |
|
to the changeset without cloning. This second form is provided |
|
to ease creating a new submodule from scratch, and presumes |
|
the user will later push the submodule to the given URL. |
|
+ |
|
In either case, the given URL is recorded into .gitmodules for |
|
use by subsequent users cloning the superproject. If the URL is |
|
given relative to the superproject's repository, the presumption |
|
is the superproject and submodule repositories will be kept |
|
together in the same relative location, and only the |
|
superproject's URL need be provided: git-submodule will correctly |
|
locate the submodule using the relative URL in .gitmodules. |
|
|
|
status:: |
|
Show the status of the submodules. This will print the SHA-1 of the |
|
currently checked out commit for each submodule, along with the |
|
submodule path and the output of 'git-describe' for the |
|
SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not |
|
initialized and `+` if the currently checked out submodule commit |
|
does not match the SHA-1 found in the index of the containing |
|
repository. This command is the default command for 'git-submodule'. |
|
|
|
init:: |
|
Initialize the submodules, i.e. register each submodule name |
|
and url found in .gitmodules into .git/config. |
|
The key used in .git/config is `submodule.$name.url`. |
|
This command does not alter existing information in .git/config. |
|
You can then customize the submodule clone URLs in .git/config |
|
for your local setup and proceed to 'git submodule update'; |
|
you can also just use 'git submodule update --init' without |
|
the explicit 'init' step if you do not intend to customize |
|
any submodule locations. |
|
|
|
update:: |
|
Update the registered submodules, i.e. clone missing submodules and |
|
checkout the commit specified in the index of the containing repository. |
|
This will make the submodules HEAD be detached. |
|
+ |
|
If the submodule is not yet initialized, and you just want to use the |
|
setting as stored in .gitmodules, you can automatically initialize the |
|
submodule with the --init option. |
|
|
|
summary:: |
|
Show commit summary between the given commit (defaults to HEAD) and |
|
working tree/index. For a submodule in question, a series of commits |
|
in the submodule between the given super project commit and the |
|
index or working tree (switched by --cached) are shown. |
|
|
|
OPTIONS |
|
------- |
|
-q:: |
|
--quiet:: |
|
Only print error messages. |
|
|
|
-b:: |
|
--branch:: |
|
Branch of repository to add as submodule. |
|
|
|
--cached:: |
|
This option is only valid for status and summary commands. These |
|
commands typically use the commit found in the submodule HEAD, but |
|
with this option, the commit stored in the index is used instead. |
|
|
|
-n:: |
|
--summary-limit:: |
|
This option is only valid for the summary command. |
|
Limit the summary size (number of commits shown in total). |
|
Giving 0 will disable the summary; a negative number means unlimited |
|
(the default). This limit only applies to modified submodules. The |
|
size is always limited to 1 for added/deleted/typechanged submodules. |
|
|
|
<path>:: |
|
Path to submodule(s). When specified this will restrict the command |
|
to only operate on the submodules found at the specified paths. |
|
(This argument is required with add). |
|
|
|
FILES |
|
----- |
|
When initializing submodules, a .gitmodules file in the top-level directory |
|
of the containing repository is used to find the url of each submodule. |
|
This file should be formatted in the same way as `$GIT_DIR/config`. The key |
|
to each submodule url is "submodule.$name.url". See linkgit:gitmodules[5] |
|
for details. |
|
|
|
|
|
AUTHOR |
|
------ |
|
Written by Lars Hjemli <hjemli@gmail.com> |
|
|
|
GIT |
|
--- |
|
Part of the linkgit:git[1] suite
|
|
|