[PATCHv2] Documentation/git-submodule.txt: Add Description section
- From
Petr Baudis <pasky@suse.cz>
- Date
- Jul 16, 2008, 18:44 UTC
- Message-ID
- <20080716184248.6524.38463.stgit@localhost>
- In-Reply-To
- <20080715183705.GD4379@zakalwe.fi>
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 <shdl@zakalwe.fi> Signed-off-by: Petr Baudis <pasky@suse.cz> ---
I have adjusted the description a bit; however, I believe mentioning remotes in the description would only raise the danger of confusion - I emphasized the level of separation, though.
Documentation/git-submodule.txt | 22 ++++++++++++++++++++++ 1 files changed, 22 insertions(+), 0 deletions(-)
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 76702a0..87c4ece 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -16,6 +16,28 @@ SYNOPSIS 'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...] +DESCRIPTION +----------- +Submodules are a special kind of tree entries which refer to a particular tree +in another repository (living at a given URL). The tree entry describes +the existence of a submodule with the given name and the exact revision that +should be used, while the location of the repository is described in the +`/.gitmodules` file. + +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::