path: root/Documentation/git-submodule.txt
diff options
authorJunio C Hamano <>2017-07-12 22:18:21 (GMT)
committerJunio C Hamano <>2017-07-12 22:18:21 (GMT)
commitb5fe65fe93db1931501027a322ecb6a9f17f56e7 (patch)
tree4ccc45514c16fb411822a0754efb9fdba98e59a7 /Documentation/git-submodule.txt
parent117ddefdb4dfd9b40ae60967a7327754d8ce7a87 (diff)
parentd48034551a3b1cb2dc60ff1c30a2d5acad20b6a1 (diff)
Merge branch 'sb/submodule-doc'
Doc update. * sb/submodule-doc: submodules: overhaul documentation
Diffstat (limited to 'Documentation/git-submodule.txt')
1 files changed, 10 insertions, 34 deletions
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index b9a56d4..ff61200 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -24,37 +24,7 @@ DESCRIPTION
Inspects, updates and manages submodules.
-A submodule allows you to keep another Git repository in a subdirectory
-of your repository. The other repository has its own history, which does not
-interfere with the history of the current repository. This can be used to
-have external dependencies such as third party libraries for example.
-When cloning or pulling a repository containing submodules however,
-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.
-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` (see linkgit:gitmodules[5]) 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').
-Submodules are not to be confused with remotes, which are other
-repositories 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.
+For more information about submodules, see linkgit:gitsubmodules[7].
@@ -142,15 +112,17 @@ deinit [-f|--force] (--all|[--] <path>...)::
tree. Further calls to `git submodule update`, `git submodule foreach`
and `git submodule sync` will skip any unregistered submodules until
they are initialized again, so use this command if you don't want to
- have a local checkout of the submodule in your working tree anymore. If
- you really want to remove a submodule from the repository and commit
- that use linkgit:git-rm[1] instead.
+ have a local checkout of the submodule in your working tree anymore.
When the command is run without pathspec, it errors out,
instead of deinit-ing everything, to prevent mistakes.
If `--force` is specified, the submodule's working tree will
be removed even if it contains local modifications.
+If you really want to remove a submodule from the repository and commit
+that use linkgit:git-rm[1] instead. See linkgit:gitsubmodules[7] for removal
update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--] [<path>...]::
@@ -428,6 +400,10 @@ 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.
+linkgit:gitsubmodules[7], linkgit:gitmodules[5].
Part of the linkgit:git[1] suite