git@vger.kernel.org mailing list mirror (one of many)
 help / Atom feed
From: Stefan Beller <sbeller@google.com>
To: Jonathan Tan <jonathantanmy@google.com>
Cc: Git mailing list <git@vger.kernel.org>, Brandon Williams <bmwill@google.com>, Jonathan Nieder <jrnieder@gmail.com>, Junio C Hamano <gitster@pobox.com>
Subject: Re: [PATCHv2] submodules: overhaul documentation
Date: Wed, 21 Jun 2017 10:25:06 -0700
Message-ID: <CAGZ79kYbjYyFk5-z+68iUqM=U8dgnDEzReS9aTshXb97Co+RqQ@mail.gmail.com> (raw)
In-Reply-To: <CAGf8dg+f-RzcT15zofB9xbgEE6nTK+T7awjOHY+KEx7KZ-cPXg@mail.gmail.com>

On Tue, Jun 20, 2017 at 8:45 PM, Jonathan Tan <jonathantanmy@google.com> wrote:
> Thanks, this looks like a good explanation. Some more nits, but
> overall I feel like I understand this and have learned something from
> it.
>
> On Tue, Jun 20, 2017 at 3:56 PM, Stefan Beller <sbeller@google.com> wrote:
>> +A submodule is another Git repository tracked inside a repository.
>> +The tracked repository has its own history, which does not
>> +interfere with the history of the current repository.
>> +
>> +It consists of a tracking subdirectory in the working directory,
>> +a 'gitlink' in the working tree and an entry in the `.gitmodules`
>
> Probably should be `gitlink` (the special quotes), and (optional)
> s/`gitlink`/`gitlink` object/ because it might not be apparent that
> gitlink is a type of object.
>
>> +file (see linkgit:gitmodules[5]) at the root of the source tree.
>
> After reading below, maybe we should mention the Git directory in
> $GIT_DIR/modules/<submodule name> as part of what a submodule consists
> of too.

I implemented the rest of the suggestions, but this one leaves my head
scratching.
It's not as if we don't know what a submodule is already. Our glossary says:

    submodule
           A repository that holds the history of a separate project inside
           another repository (the latter of which is called superproject).

So by that definition the gitlink and the entry in .gitmodules are just
metadata by the superproject and the actual submodule is the
repository consisting of its working tree (inside the superprojects
working tree)
as well as its git directory preferably inside the superprojects git dir.

This definition however is broken IMHO, as when there is proper meta data
(gitlink + .gitmodules entry), you can have an "uninitialized" submodule,
which has neither a working tree nor a git dir at the time.

The wording above holds true for un-{initialized,populated} submodules
as well, as the tracking directory is empty and the git dir doesn't exist.

So I think I'll resend without that change.

Thanks,
Stefan

  reply index

Thread overview: 17+ messages in thread (expand / mbox.gz / Atom feed / [top])
2017-06-07 18:53 [RFC/PATCH] " Stefan Beller
2017-06-13 19:29 ` Junio C Hamano
2017-06-13 21:06   ` Stefan Beller
2017-06-19 18:10     ` Brandon Williams
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 [this message]
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 publically 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 to all the recipients using the --to, --cc,
  and --in-reply-to switches of git-send-email(1):

  git send-email \
    --in-reply-to='CAGZ79kYbjYyFk5-z+68iUqM=U8dgnDEzReS9aTshXb97Co+RqQ@mail.gmail.com' \
    --to=sbeller@google.com \
    --cc=bmwill@google.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=jonathantanmy@google.com \
    --cc=jrnieder@gmail.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

git@vger.kernel.org mailing list mirror (one of many)

Archives are clonable:
	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.org/gmane.comp.version-control.git

 note: .onion URLs require Tor: https://www.torproject.org/
       or Tor2web: https://www.tor2web.org/

AGPL code for this site: git clone https://public-inbox.org/ public-inbox