Re: [PATCH] submodule documentation: Reorder introductory paragraphs
- From
Junio C Hamano <gitster@pobox.com>
- Date
- May 21, 2015, 17:24 UTC
- Message-ID
- <xmqqoaldkfmy.fsf@gitster.dls.corp.google.com>
- In-Reply-To
- <1432163517-22785-1-git-send-email-sbeller@google.com>
Stefan Beller <sbeller@google.com> writes:
Show 10 quoted lines
> 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.
Show 14 quoted lines
> 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, ...
Show 5 quoted lines
> -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".