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 <shdl@zakalwe.fi> Signed-off-by: Petr Baudis <pasky@suse.cz> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Petr Baudis committed
Jul 16, 2008 at 20:44 UTC
e38953ab00bfb150822d2d92d2dc8e4ce31ef9a4
1 file changed
+22
Documentation/git-submodule.txt
+22
@@ -16,6 +16,28 @@ SYNOPSIS
16
'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...]
17
18
19
+DESCRIPTION
20
+-----------
21
+Submodules are a special kind of tree entries which refer to a particular tree
22
+state in another repository. The tree entry describes
23
+the existence of a submodule with the given name and the exact revision that
24
+should be used, while an entry in `.gitmodules` file gives the location of
25
+the repository.
26
+
27
+When checked out, submodules will maintain their own independent repositories
28
+within their directories; the only link between the submodule and the "parent
29
+project" is the tree entry within the parent project mentioned above.
30
+
31
+This command will manage the tree entries and contents of the gitmodules file
32
+for you, as well as inspecting the status of your submodules and updating them.
33
+When adding a new submodule to the tree, the 'add' subcommand is to be used.
34
+However, when pulling a tree containing submodules, these will not be checked
35
+out by default; the 'init' and 'update' subcommands will maintain submodules
36
+checked out and at appropriate revision in your working tree. You can inspect
37
+the current status of your submodules using the 'submodule' subcommand and get
38
+an overview of changes 'update' would perform using the 'summary' subcommand.
39
+
40
+
41
COMMANDS
42
--------
43
add::