mirrors/git
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

submodule doc: reorder introductory paragraphs

Browse Source 
It's better to start the man page with a description of what
submodules actually are, instead of saying what they are not.

Reorder the paragraphs such that

 - the first short paragraph introduces the submodule concept,
 - the second paragraph highlights the usage of the submodule command,
 - the third paragraph giving background information, and finally
 - the fourth paragraph discusing alternatives such as subtrees and
   remotes, which we don't want to be confused with.

This ordering deepens the knowledge on submodules with each paragraph.
First the basic questions like "How/what" will be answered, while the
underlying concepts will be taught at a later time.

Making sure it is not confused with subtrees and remotes is not really
enhancing knowledge of submodules itself, but rather painting the big
picture of git concepts, so you could also argue to have it as the second
paragraph. Personally I think this may confuse readers, specially
newcomers though.

Additionally to reordering the paragraphs, they have been slightly
reworded.

Signed-off-by: Stefan Beller <sbeller@google.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Stefan Beller
2015-05-27 12:48:01 -07:00
committed by Junio C Hamano
parent 3d4a3ffe64
commit ec48a76306
1 changed files with 22 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
Documentation/git-submodule.txt
View File

@ -25,22 +25,17 @@ SYNOPSIS
DESCRIPTION DESCRIPTION
----------- -----------
Submodules allow foreign repositories to be embedded within Inspects, updates and manages submodules.
a dedicated subdirectory of the source tree, always pointed
at a particular commit.
They are not to be confused with remotes, which are meant mainly A submodule allows you to keep another Git repository in a subdirectory
for branches of the same project; submodules are meant for of your repository. The other repository has its own history, which does not
different projects you would like to make part of your source tree, interfere with the history of the current repository. This can be used to
while the history of the two projects still stays completely have external dependencies such as third party libraries for example.
independent and you cannot modify the contents of the submodule
from within the main project. When cloning or pulling a repository containing submodules however,
If you want to merge the project histories and want to treat the these will not be checked out by default; the 'init' and 'update'
aggregated whole as a single project from then on, you may want to subcommands will maintain submodules checked out and at
add a remote for the other project and use the 'subtree' merge strategy, appropriate revision in your working tree.
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.
Submodules are composed from a so-called `gitlink` tree entry Submodules are composed from a so-called `gitlink` tree entry
in the main repository that refers to a particular commit object in the main repository that refers to a particular commit object
@ -51,19 +46,18 @@ describes the default URL the submodule shall be cloned from.
The logical name can be used for overriding this URL within your The logical name can be used for overriding this URL within your
local repository configuration (see 'submodule init'). local repository configuration (see 'submodule init').
This command will manage the tree entries and contents of the Submodules are not to be confused with remotes, which are other
gitmodules file for you, as well as inspect the status of your repositories of the same project; submodules are meant for
submodules and update them. different projects you would like to make part of your source tree,
When adding a new submodule to the tree, the 'add' subcommand while the history of the two projects still stays completely
is to be used. However, when pulling a tree containing submodules, independent and you cannot modify the contents of the submodule
these will not be checked out by default; from within the main project.
the 'init' and 'update' subcommands will maintain submodules If you want to merge the project histories and want to treat the
checked out and at appropriate revision in your working tree. aggregated whole as a single project from then on, you may want to
You can briefly inspect the up-to-date status of your submodules add a remote for the other project and use the 'subtree' merge strategy,
using the 'status' subcommand and get a detailed overview of the instead of treating the other project as a submodule. Directories
difference between the index and checkouts using the 'summary' that come from both projects can be cloned and checked out as a whole
subcommand. if you choose to go that route.
COMMANDS COMMANDS
-------- --------