undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge branch 'sb/submodule-doc-intro'

Browse Source 
* sb/submodule-doc-intro:
  submodule doc: reorder introductory paragraphs
This commit is contained in:
Junio C Hamano 2015-06-11 09:29:56 -07:00
commit 7df5c978d5
1 changed files with 22 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
Documentation/git-submodule.txt
View File

@ -25,22 +25,17 @@ SYNOPSIS
DESCRIPTION
-----------
Submodules allow foreign repositories to be embedded within
a dedicated subdirectory of the source tree, always pointed
at a particular commit.
Inspects, updates and manages submodules.
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.
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
@ -51,19 +46,18 @@ 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.
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.
COMMANDS
--------