git@vger.kernel.org mailing list mirror (one of many)
 help / Atom feed
From: Stefan Beller <sbeller@google.com>
To: Junio C Hamano <gitster@pobox.com>, mlevedahl@gmail.com
Cc: "git@vger.kernel.org" <git@vger.kernel.org>, Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
Subject: Re: [PATCH/RFC] Cleanup Documentation
Date: Sun, 18 Jun 2017 22:50:54 -0700
Message-ID: <CAGZ79kbqBXZ5S2TBk6B5gRk+Y-ev2rdgkQZrF-MmHQc0Thj7EQ@mail.gmail.com> (raw)
In-Reply-To: <xmqq1sqgv9ax.fsf@gitster.mtv.corp.google.com>

On Sun, Jun 18, 2017 at 10:24 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Stefan, this was sent in my way, but I know you are the primary
> person who is looking into updating submodule documentation these
> days, so I am forwarding it in your way to ask you to give the first
> comment.
>
> Thanks.

AFAICT this is specific to the arguments of 'add', such that it would not
collide with sb/submodule-doc[1]. However my series was RFC, while this
is on the order of "documentation bug fix", so this would be more important
than rewriting the documentation from scrach any way. :)



[1] https://public-inbox.org/git/20170607185354.10050-1-sbeller@google.com/


>
> Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:
>
>> 1. Remove redundancy from documentation
>> 2. Remove unclear reference to alternative
>>
>> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
>> ---
>>
>> The following line seemes unclear and hence was removed for now. Suggest any
>> changes that could make it clear.
>>
>> "This second form is provided to ease creating a new submodule from scratch,
>> and presumes the user will later push the submodule to the given URL."

+cc Marc who wrote this sentence originally.


>>
>>
>>  Documentation/git-submodule.txt | 37 ++++++++++++++++---------------------
>>  1 file changed, 16 insertions(+), 21 deletions(-)
>>
>> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
>> index 74bc6200d..9812b0655 100644
>> --- a/Documentation/git-submodule.txt
>> +++ b/Documentation/git-submodule.txt
>> @@ -63,13 +63,7 @@ add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--dep
>>       to the changeset to be committed next to the current
>>       project: the current project is termed the "superproject".
>>  +
>> -This requires at least one argument: <repository>. The optional
>> -argument <path> is the relative location for the cloned submodule
>> -to exist in the superproject. If <path> is not given, the
>> -"humanish" part of the source repository is used ("repo" for
>> -"/path/to/repo.git" and "foo" for "host.xz:foo/.git").
>> -The <path> is also used as the submodule's logical name in its
>> -configuration entries unless `--name` is used to specify a logical name.
>> +This requires at least one argument: <repository>.
>>  +

So we're losing the information how the submodule name is chosen.
This may be fine as I plan (long term) to make the name an arbitrary random
string (IMHO that reduces confusion as there will be less 'nearly the same'
things)

On the other hand the newly added line
  'This requires at least one argument: <repository'
(actually moved, but) is sort of redundant. The notation in the argument line
should make that clear, already?


>>  <repository> is the URL of the new submodule's origin repository.
>>  This may be either an absolute URL, or (if it begins with ./
>> @@ -87,21 +81,22 @@ If the superproject doesn't have a default remote configured
>>  the superproject is its own authoritative upstream and the current
>>  working directory is used instead.
>>  +
>> -<path> is the relative location for the cloned submodule to
>> -exist in the superproject. If <path> does not exist, then the
>> -submodule is created by cloning from the named URL. If <path> does
>> -exist and is already a valid Git repository, then this is added
>> -to the changeset without cloning. This second form is provided
>> -to ease creating a new submodule from scratch, and presumes
>> -the user will later push the submodule to the given URL.
>> +The optional argument <path> is the relative location for the cloned
>> +submodule to exist in the superproject. If <path> is not given, the
>> +"humanish" part of the source repository is used ("repo" for
>> +"/path/to/repo.git" and "foo" for "host.xz:foo/.git"). If <path>
>> +exists and is already a valid Git repository, then this is added
>> +to the changeset without cloning. The <path> is also used as the
>> +submodule's logical name in its configuration entries unless `--name`
>> +is used to specify a logical name.

This sounds good, it consolidates all information about [<path>]
in one paragraph. While at it, maybe let's find another (better)
substitute for "humanish" as that can be anything(?).

Maybe "the last part of the URL" (without any .git)

>>  +
>> -In either case, the given URL is recorded into .gitmodules for
>> -use by subsequent users cloning the superproject. If the URL is
>> -given relative to the superproject's repository, the presumption
>> -is the superproject and submodule repositories will be kept
>> -together in the same relative location, and only the
>> -superproject's URL needs to be provided: git-submodule will correctly
>> -locate the submodule using the relative URL in .gitmodules.
>> +The given URL is recorded into .gitmodules for use by subsequent users
>> +cloning the superproject. If the URL is given relative to the
>> +superproject's repository, the presumption is the superproject and
>> +submodule repositories will be kept together in the same relative
>> +location, and only the superproject's URL needs to be provided.
>> +git-submodule will correctly locate the submodule using the relative
>> +URL in .gitmodules.
>>

(While at it:)
Please markup the '.gitmodules' either via single quotes or `.
(or even link to 'gitmodules(5)' )

>>  status [--cached] [--recursive] [--] [<path>...]::
>>       Show the status of the submodules. This will print the SHA-1 of the

I am undecided if this is really removing (2) unclearness, but the
(1) redundancy seems fine to me.

Thanks,
Stefan

  reply index

Thread overview: 15+ messages in thread (expand / mbox.gz / Atom feed / [top])
2017-06-19  3:05 Kaartic Sivaraam
2017-06-19  5:24 ` Junio C Hamano
2017-06-19  5:50   ` Stefan Beller [this message]
2017-06-19 17:33     ` Kaartic Sivaraam
2017-06-19 17:54       ` Stefan Beller
2017-06-20  3:12         ` Kaartic Sivaraam
2017-06-20 16:57           ` Stefan Beller
2017-06-20 17:05             ` Stefan Beller
2017-06-21  3:02               ` [PATCH/FINALRFC] Documentation/git-submodule: cleanup Kaartic Sivaraam
2017-06-21 16:11                 ` Junio C Hamano
2017-06-21 17:41                   ` Kaartic Sivaraam
2017-06-22  2:51                     ` [PATCH/FINAL] " Kaartic Sivaraam
2017-06-22 19:07                       ` Junio C Hamano
2017-06-22 19:13                         ` Stefan Beller
2017-06-20 18:27             ` [PATCH/RFC] Cleanup Documentation Kaartic Sivaraam

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=CAGZ79kbqBXZ5S2TBk6B5gRk+Y-ev2rdgkQZrF-MmHQc0Thj7EQ@mail.gmail.com \
    --to=sbeller@google.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=kaarticsivaraam91196@gmail.com \
    --cc=mlevedahl@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