@matheusbsbs / matheus-bagliano / commits / c47f10246a
Fork 0

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>

Petr Baudis committed Jul 18, 2008 at 15:40 UTC c47f10246ac6413ac6902bd70e45492174fac873
1 file changed +47 -22
Documentation/git-submodule.txt
+47 -22
@@ -18,24 +18,44 @@ SYNOPSIS
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.
21 +Submodules allow foreign repositories to be embedded within
22 +a dedicated subdirectory of the source tree, always pointed
23 +at a particular commit.
24 +
25 +They are not to be confused with remotes, which are meant mainly
26 +for branches of the same project; submodules are meant for
27 +different projects you would like to make part of your source tree,
28 +while the history of the two projects still stays completely
29 +independent and you cannot modify the contents of the submodule
30 +from within the main project.
31 +If you want to merge the project histories and want to treat the
32 +aggregated whole as a single project from then on, you may want to
33 +add a remote for the other project and use the 'subtree' merge strategy,
34 +instead of treating the other project as a submodule. Directories
35 +that come from both projects can be cloned and checked out as a whole
36 +if you choose to go that route.
37 +
38 +Submodules are composed from a so-called `gitlink` tree entry
39 +in the main repository that refers to a particular commit object
40 +within the inner repository that is completely separate.
41 +A record in the `.gitmodules` file at the root of the source
42 +tree assigns a logical name to the submodule and describes
43 +the default URL the submodule shall be cloned from.
44 +The logical name can be used for overriding this URL within your
45 +local repository configuration (see 'submodule init').
46 +
47 +This command will manage the tree entries and contents of the
48 +gitmodules file for you, as well as inspect the status of your
49 +submodules and update them.
50 +When adding a new submodule to the tree, the 'add' subcommand
51 +is to be used. However, when pulling a tree containing submodules,
52 +these will not be checked out by default;
53 +the 'init' and 'update' subcommands will maintain submodules
54 +checked out and at appropriate revision in your working tree.
55 +You can briefly inspect the up-to-date status of your submodules
56 +using the 'status' subcommand and get a detailed overview of the
57 +difference between the index and checkouts using the 'summary'
58 +subcommand.
59
60
61 COMMANDS
@@ -78,10 +98,15 @@ status::
98 repository. This command is the default command for 'git-submodule'.
99
100 init::
81 - Initialize the submodules, i.e. register in .git/config each submodule
82 - name and url found in .gitmodules. The key used in .git/config is
83 - `submodule.$name.url`. This command does not alter existing information
84 - in .git/config.
101 + Initialize the submodules, i.e. register each submodule name
102 + and url found in .gitmodules into .git/config.
103 + The key used in .git/config is `submodule.$name.url`.
104 + This command does not alter existing information in .git/config.
105 + You can then customize the submodule clone URLs in .git/config
106 + for your local setup and proceed to 'git submodule update';
107 + you can also just use 'git submodule update --init' without
108 + the explicit 'init' step if you do not intend to customize
109 + any submodule locations.
110
111 update::
112 Update the registered submodules, i.e. clone missing submodules and