Stefan Beller <sbeller@xxxxxxxxxx> writes: > 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. Sounds good. > diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt > index 2c25916..6c38c0d 100644 > --- a/Documentation/git-submodule.txt > +++ b/Documentation/git-submodule.txt > @@ -25,35 +25,12 @@ SYNOPSIS > > DESCRIPTION > ----------- > -Submodules allow foreign repositories to be embedded within > -a dedicated subdirectory of the source tree, always pointed > -at a particular commit. > +Submodules allow other repositories to be embedded within > +a dedicated subdirectory of the source tree pointing > +at a particular commit in the other repository. Not a new problem, but I can misread this as if it requires the top-level superproject to have one single dedicated directory D to house all the foreign projects under it, D/project1, D/project2, ... > -This command will manage the tree entries and contents of the > -gitmodules file for you, as well as inspect the status of your > -submodules and update them. > +This command will manage the submodules for you, as well as > +inspect the status of your submodules and update them. Not a new problem, but does the command really "manage them for you"? I view it more like "You can use this command to manage, inspect and update the submodules". -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html