From: Petr Baudis Date: Wed, 16 Jul 2008 18:44:12 +0000 (+0200) Subject: Documentation/git-submodule.txt: Add Description section X-Git-Tag: v1.6.0-rc0~38 X-Git-Url: https://git.tokkee.org/?a=commitdiff_plain;h=e38953ab00bfb150822d2d92d2dc8e4ce31ef9a4;p=git.git Documentation/git-submodule.txt: Add Description section Figuring out how submodules work conceptually is quite a bumpy ride for a newcomer; the user manual helps (if one knows to actually look into it), but the reference documentation should provide good quick intro as well. This patch attempts to do that, with suggestions from Heikki Orsila. Cc: Heikki Orsila Signed-off-by: Petr Baudis Signed-off-by: Junio C Hamano --- diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 76702a0a5..bb4e6fbf5 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -16,6 +16,28 @@ SYNOPSIS 'git submodule' [--quiet] summary [--summary-limit ] [commit] [--] [...] +DESCRIPTION +----------- +Submodules are a special kind of tree entries which refer to a particular tree +state in another repository. The tree entry describes +the existence of a submodule with the given name and the exact revision that +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 +within their directories; the only link between the submodule and the "parent +project" is the tree entry within the parent project mentioned above. + +This command will manage the tree entries and contents of the gitmodules file +for you, as well as inspecting the status of your submodules and updating 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 inspect +the current status of your submodules using the 'submodule' subcommand and get +an overview of changes 'update' would perform using the 'summary' subcommand. + + COMMANDS -------- add::