On 06/13, Stefan Beller wrote: > Adding two native speakers as we start word smithing. > > On Tue, Jun 13, 2017 at 12:29 PM, Junio C Hamano <gitster@xxxxxxxxx> wrote: > > >> + > >> +A submodule is another Git repository tracked in a subdirectory of your > >> +repository. The tracked repository has its own history, which does not > >> +interfere with the history of the current repository. > > > > "tracked in a subdirectory" sounds as if your top-level superproject > > has a dedicated submodules/ directory and in it there live a bunch > > of submodules. Which obviously is not what you meant. If phrased > > "tracked as a subdirectory", I think the sentence makes sense. > > Given this explanation "as a" also sounds wrong[1], maybe we need to > separate (1) where it is put/mounted and (2) the fact that is tracked, > i.e. the superproject has an idea of what should be there at a given > revision. (I shortly thought about /s/as a/using/ in the above, but): > > A submodule is another Git repository at an arbitrary place inside > the working tree, and also tracked. The tracked repository has its > own history, which does not interfere with the history of the current > repository. I would probably change the first sentence to: A submodule is another Git repository tracked at an arbitrary place inside the working tree. > > [1] http://www.thesaurus.com/browse/as > > > > > While "which does not interfere" may be technically correct, I am > > not sure what the value of saying that is. > > I think we can drop it here. When writing I wanted to separate it from > subtrees, but this is the wrong place for that. > > > > >> +Submodules are composed from a so-called `gitlink` tree entry > >> +in the main repository that refers to a particular commit object > >> +within the inner repository. > > > > Correct, but it may be unclear to the readers why we do so. Perhaps > > > > ... and this way, the tree of each commit in the main repository > > "knows" which commit from the submodule's history is "tied" to it. > > > > or something like that? > > sounds good to me. > > > > >> +Additionally to the gitlink entry the `.gitmodules` file (see > >> +linkgit:gitmodules[5]) at the root of the source tree contains > >> +information needed for submodules. > > > > Is that really true? Each submodule do not *need* what is in > > .gitmodules; the top-level superproject needs to learn about > > its submodules from the contents of that file, though. > > Ha! The ediled words in my mind were: > > ... information needed for submodules [to work in the superproject]. > > But maybe we need to reword that as > > Additionally to the gitlink entry the `.gitmodules` file (see > linkgit:gitmodules[5]) at the root of the source tree contains > information on how to handle submodules. This sounds slightly awkward. Maybe: In addition to the gitlink entry, the `.gitmodules` file (see linkgit:gitmodules[5]) at the root of the source tree contains information on how to handle submodules. -- Brandon Williams
