Re: [PATCH] Clarify role of init command in git-submodules documentation

From: martin f krafft <madduck@madduck.net>
Date: Aug 21, 2007, 18:02 UTC
Message-ID: <20070821180218.GA14739@piper.oerlikon.madduck.net>
In-Reply-To: <7vd4xhsybm.fsf@gitster.siamese.dyndns.org>

also sprach Junio C Hamano <gitster@pobox.com> [2007.08.20.2314 +0200]:

Show 8 quoted lines

> > As per the discussion in this thread:
> >
> >   http://marc.info/?t=118721709500008&r=1&w=2
> 
> I'd rather see you summarize the conclusion of the thread here.
> Having the URL as additional supporting reference is fine, but
> when one reviews the "git log" output, one is not necessarily
> online.

This is a good point, and I completely agree with you. In this very case, however, I *consciously* decided against a summary simply because I was hoping to capture the essence in the patch to the documentation itself. Anyway, I shall keep your suggestion in mind. Thanks for being so patient with me.

And while I still have your attention *grin*: I assume this is the correct way of going about this: keep sending updated patches to the same thread until it's accepted?

In this case, I'll just send the text before preparing the next patch; once we agree on it, I'll send a patch. That should make it easier on everyone.

> Is it "a user _has_ to"?  Or "a user can use 'git submodule
> init' to prepare?"

[...]

> I've read Sven's description on two files.  My suspicion is that
> instead of saying there are two files involved, it may be easier
> to understand if we tell the story like this:

Based your and Sven's suggestions, I sat down and thought for a bit, then came up with this, which I like very much:

  FILES

  A repository with submodules is identified by a .gitmodules file
  in the repository's top level (see gitlink:gitmodules[5]). This
  file specifies for each submodule its name, the url of the
  submodule's repository, as well as the location of the submodule
  within the (super)project's repository. As the .gitmodules file
  contains information shared by all users of the repository, it is
  typically tracked.

  Users who clone the project's repository need to initialize each
  submodule before they can work with it. By initializing
  a submodule, the submodule's url is copied from the .gitmodules
  file to the (local) configuration in $GIT_DIR/config. The command
  `git-submodule init` can be used for this, or the information
  manually transferred. The key to each submodule's url in
  $GIT_DIR/config is "submodule.$name.url".

  Once a submodule's url is defined in $GIT_DIR/config, the
  submodule can be cloned (from this url) into the local repository
  with `git-submodule update` at the location specified in the
  .gitmodules file.

  By pulling the submodule urls out of $GIT_DIR/config,
  git-submodule allows contributors to use different urls (e.g. via
  ssh for those with an account) and also makes submodule urls
  independent of the currently checked out revision of the
  superproject.

In the process of writing this, I also added a bit to other parts of the manpage:

  - added reference to FILES section next to .gitmodules file
    mention in description of add command, and a link to git-clone:

      ... and registered in the .gitmodules file (see section
      FILES). If no path is specified, the path is deduced from the
      repository specification (just like gitlink:git-clone[1]).

  - add to the update command description that modules can be
    specificed on the command line:

      Update all submodules registered in $GIT_DIR/config, or only
      those specified as arguments on the command line.

  - clarify what a detached HEAD is:

      This will make the submodules HEAD be detached (it then
      references a specific commit, not the tip of a branch anymore)

I am looking forward to your comments!

Thanks again for your patience.

-- 
martin;              (greetings from the heart of the sun.)
  \____ echo mailto: !#^."<*>"|tr "<*> mailto:" net@madduck
 
if loving linux is wrong, i don't want to be right.
 
spamtraps: madduck.bogus@madduck.net