From: Brandon Williams <bmwill@google.com>
To: Stefan Beller <sbeller@google.com>
Cc: Junio C Hamano <gitster@pobox.com>,
Jonathan Nieder <jrnieder@gmail.com>,
"git@vger.kernel.org" <git@vger.kernel.org>
Subject: Re: [RFC/PATCH] submodules: overhaul documentation
Date: Mon, 19 Jun 2017 11:10:17 -0700 [thread overview]
Message-ID: <20170619181017.GA194323@google.com> (raw)
In-Reply-To: <CAGZ79kZdUARvhO=UwexFGkWQzsYSnyyiXJMX69W9ofhz13zjHQ@mail.gmail.com>
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@pobox.com> 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
next prev parent reply other threads:[~2017-06-19 18:10 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-06-07 18:53 [RFC/PATCH] submodules: overhaul documentation Stefan Beller
2017-06-13 19:29 ` Junio C Hamano
2017-06-13 21:06 ` Stefan Beller
2017-06-19 18:10 ` Brandon Williams [this message]
2017-06-20 21:42 ` Stefan Beller
2017-06-20 18:18 ` Jonathan Tan
2017-06-20 19:15 ` Stefan Beller
2017-06-20 22:56 ` [PATCHv2] " Stefan Beller
2017-06-21 3:45 ` Jonathan Tan
2017-06-21 17:25 ` Stefan Beller
2017-06-22 17:46 ` Brandon Williams
2017-06-22 18:54 ` Stefan Beller
2017-06-22 20:20 ` Junio C Hamano
2017-06-22 20:27 ` Stefan Beller
2017-06-22 21:03 ` Brandon Williams
2017-06-22 21:09 ` Stefan Beller
2017-06-22 21:01 ` [PATCHv3] " Stefan Beller
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20170619181017.GA194323@google.com \
--to=bmwill@google.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=jrnieder@gmail.com \
--cc=sbeller@google.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).