git@vger.kernel.org mailing list mirror (one of many)
 help / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: Stefan Beller <sbeller@google.com>
Cc: git@vger.kernel.org, jonathantanmy@google.com
Subject: Re: [PATCHv3] submodules: overhaul documentation
Date: Wed, 21 Jun 2017 12:19:01 -0700
Message-ID: <xmqqinjpp2sa.fsf@gitster.mtv.corp.google.com> (raw)
In-Reply-To: <20170621173756.4444-1-sbeller@google.com>

Stefan Beller <sbeller@google.com> writes:

> +DESCRIPTION
> +-----------
> +
> +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.

As a naive reader, I have/got no idea what it means to "interfere
(or not to interfere) with the history of the current repository."

> +It consists of a tracking subdirectory in the working directory,

Is a "tracking subdirectory" something special than an ordinary
subdirectory?  How does a naive reader who experiments with Git
tell between a tracking and an ordinary subdirectory?

Or did you mean just "a subdirectory" (which is used to house its
working tree)?  s/in the working directory/& of the superproject/ or
something like that may be needed to disambiguate between the two.

> +a `gitlink` object in the working tree and an entry in the

I am not sure how you two are defining "gitlink object" here, even
after reading the previous discussion.  You two are not referring to
an 'object' in the Git object database sense.  If you are referring
to the entry with mode 160000 that points at a commit object in the
index of the superproject, that is not "in the working tree" but in
the index.

> +`.gitmodules` file (see linkgit:gitmodules[5]) at the root of
> +the source tree and its git.

Again, as you are describing a submodule and superproject combo, you
need to clarify whose "root" you are referring to.  I guess this is
at the root of superproject's working tree?  I have no idea what you
wanted to say with "and its git".

I seriously doubt the value of introducing a random new word
"tracking subdirectory" without defining what it is in the glossary.
The word "tracking" is already overused and with loaded meaning in
Git, so even if we need a new word that differenciates a subdirectory
used for the submodule from other subdirectories superproject has,
we should find a different word (but I do not think we need such a
new word---just saying "submodule directory" should be enough).

> +The tracking subdirectory appears in the main repository's working
> +tree at the point where the submodules gitlink is tracked in the
> +tree.  It is empty when the submodule is not populated, otherwise
> +it contains the content of the submodule repository.

Hmph, "the content of" is probably a too dignified word to use
here.  A naive reader (like me) would think that "a copy of the
submodule repository" would appear at that subdirectory in the
superproject once the submodule is populated.

> +The main repository is often referred to as superproject.
> +
> +The gitlink contains the object name of a particular commit
> +of the submodule.
> +
> +The `.gitmodules` file establishes a relationship between the
> +path, which is where the gitlink is in the tree, and the logical
> +name, which is used for the location of the submodules git
> +directory. The `.gitmodules` file has the same syntax as the
> +$GIT_DIR/config file and the mapping of path to name
> +is done via setting `submodule.<name>.path = <path>`.

This is mapping of name to path, though ;-)


  reply index

Thread overview: 3+ messages in thread (expand / mbox.gz / Atom feed / [top])
2017-06-21 17:37 Stefan Beller
2017-06-21 19:19 ` Junio C Hamano [this message]
     [not found] <20170620225650.7573-1-sbeller@google.com>
2017-06-22 21:01 ` 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=xmqqinjpp2sa.fsf@gitster.mtv.corp.google.com \
    --to=gitster@pobox.com \
    --cc=git@vger.kernel.org \
    --cc=jonathantanmy@google.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

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