mirror of
https://github.com/git/git.git
synced 2024-09-22 21:52:17 +02:00
Documentation/git-submodule.txt: Further clarify the description
This patch rewrites the general description yet again, first clarifying the high-level concept, mentioning the difference to remotes and using the subtree merge strategy, then getting to the details about tree entries and .gitmodules file. The patch also makes few smallar grammar fixups within the rest of the description and clarifies how does 'init' relate to 'update --init'. Cc: Heikki Orsila <shdl@zakalwe.fi> Signed-off-by: Petr Baudis <pasky@suse.cz> Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
parent
c09df8a74e
commit
c47f10246a
@ -18,24 +18,44 @@ SYNOPSIS
|
|||||||
|
|
||||||
DESCRIPTION
|
DESCRIPTION
|
||||||
-----------
|
-----------
|
||||||
Submodules are a special kind of tree entries which refer to a particular tree
|
Submodules allow foreign repositories to be embedded within
|
||||||
state in another repository. The tree entry describes
|
a dedicated subdirectory of the source tree, always pointed
|
||||||
the existence of a submodule with the given name and the exact revision that
|
at a particular commit.
|
||||||
should be used, while an entry in `.gitmodules` file gives the location of
|
|
||||||
the repository.
|
|
||||||
|
|
||||||
When checked out, submodules will maintain their own independent repositories
|
They are not to be confused with remotes, which are meant mainly
|
||||||
within their directories; the only link between the submodule and the "parent
|
for branches of the same project; submodules are meant for
|
||||||
project" is the tree entry within the parent project mentioned above.
|
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.
|
||||||
|
|
||||||
This command will manage the tree entries and contents of the gitmodules file
|
Submodules are composed from a so-called `gitlink` tree entry
|
||||||
for you, as well as inspecting the status of your submodules and updating them.
|
in the main repository that refers to a particular commit object
|
||||||
When adding a new submodule to the tree, the 'add' subcommand is to be used.
|
within the inner repository that is completely separate.
|
||||||
However, when pulling a tree containing submodules, these will not be checked
|
A record in the `.gitmodules` file at the root of the source
|
||||||
out by default; the 'init' and 'update' subcommands will maintain submodules
|
tree assigns a logical name to the submodule and describes
|
||||||
checked out and at appropriate revision in your working tree. You can inspect
|
the default URL the submodule shall be cloned from.
|
||||||
the current status of your submodules using the 'submodule' subcommand and get
|
The logical name can be used for overriding this URL within your
|
||||||
an overview of changes 'update' would perform using the 'summary' subcommand.
|
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
|
COMMANDS
|
||||||
@ -78,10 +98,15 @@ status::
|
|||||||
repository. This command is the default command for 'git-submodule'.
|
repository. This command is the default command for 'git-submodule'.
|
||||||
|
|
||||||
init::
|
init::
|
||||||
Initialize the submodules, i.e. register in .git/config each submodule
|
Initialize the submodules, i.e. register each submodule name
|
||||||
name and url found in .gitmodules. The key used in .git/config is
|
and url found in .gitmodules into .git/config.
|
||||||
`submodule.$name.url`. This command does not alter existing information
|
The key used in .git/config is `submodule.$name.url`.
|
||||||
in .git/config.
|
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::
|
||||||
Update the registered submodules, i.e. clone missing submodules and
|
Update the registered submodules, i.e. clone missing submodules and
|
||||||
|
Loading…
Reference in New Issue
Block a user