git@vger.kernel.org mailing list mirror (one of many)
 help / Atom feed
From: Stefan Beller <sbeller@google.com>
To: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>,
	Brandon Williams <bmwill@google.com>
Cc: Git mailing list <git@vger.kernel.org>
Subject: Re: [PATCH 0/8] Doc/submodules: a few updates
Date: Mon, 8 Jan 2018 11:08:42 -0800
Message-ID: <CAGZ79kZ-UNCyCzmg=5PQ_p5xbmCp7HUc0=TXNBxwTjZDCnJtBg@mail.gmail.com> (raw)
In-Reply-To: <20180106184614.20115-1-kaartic.sivaraam@gmail.com>

On Sat, Jan 6, 2018 at 10:46 AM, Kaartic Sivaraam
<kaartic.sivaraam@gmail.com> wrote:
> These are just a few improvements that I thought would make the documentation
> related to submodules a little better in various way such as readability,
> consistency etc., These were things I noticed while reading thise documents.
>
> Sorry, for the highly granular patches. I did the commits as and when I was
> reading them and tried to keep them focused to one particular change by rebasing
> them as needed. In case they need some change, let me know.

While small patches are really appreciated for code (bisect, automated
testing, and
the general difficulty to reason about code, as a very small change
may affect the whole
code base), I am not sure if they benefit in documentation.
Documentation is a rather
local human readable thing, so by changing one sentence we don't
affect the understanding
of documentation at a completely unrelated place.

Also it helps to read more than just sentence fragments, i.e. I tried
looking at the
whole paragraph for review. May I suggest to squash them all and
resend as one patch?


>
> I based these patches on top of 'master'.

I am not aware of other submodule patches affecting documentation in master..pu,
so this should be easy to merge.

>
> Apart from the changes, I saw a few things that needed improvement/clarification
> but wasn't able to do that myself due to my limited knowledge of submodules. They
> are listed below. I'll add in patches for them if they are correctly clarified.
>
>
> 1.
>
>  man gitsubmodules
>
>        ·   The configuration file $GIT_DIR/config in the superproject. Typical configuration at this place is controlling if a submodule is
>            recursed into at all via the active flag for example.
>
>            If the submodule is not yet initialized, then the configuration inside the submodule does not exist yet, so configuration where to
>            obtain the submodule from is configured here for example.
>
> What's the "active flag" mentioned above? Also I find the phrase "is recursed into at all"
> to be a little slippery. How could it be improved?

There are multiple ways to indicate if a submodule is "active", i.e. if Git is
supposed to pay attention. Historically we had to set the
submodule.<name>.url flag in the config, but last year Brandon added
submodule.active as well as submodule.<name>.active which supersede
the .url flag.

(See is_submodule_active() in submodule.c to see the definitive answer to
"should Git pay attention?")
https://github.com/git/git/blob/master/submodule.c#L224

I wonder if this indicates a lack of documentation when the active
flags were introduced.
They are found in 'man git config', but maybe we need to spell them
out explicitly
in the submodule related docs.

> 2.
>
>  man git submodule
>
>        update
>            ...
>
>            checkout
>                ....
>
>                If --force is specified, the submodule will be checked out (using git checkout --force if appropriate), even if the commit
>                specified in the index of the containing repository already matches the commit checked out in the submodule.
>
> I'm not sure this is conveying all the information it should be conveying.
> It seems to making the user wonder, "How at all does 'git submodule update --force'
> differs from 'git submodule update'?" also "using git checkout --force if appropriate"
> seems to be invoking all sorts confusion as "appropriate" is superfluous.

When "submodule update" is invoked with the `--force` flag, that flag is passed
on to the 'checkout' operation. If you do not give the --force, then
the checkout
will also be done without --force.

>
> How could these confusions be clarified?

I tried giving an alternative snippet above, not sure how else to tell.

  parent reply index

Thread overview: 44+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-01-06 18:46 Kaartic Sivaraam
2018-01-06 18:46 ` [PATCH 1/8] Doc/gitsubmodules: split a sentence for better readability Kaartic Sivaraam
2018-01-07  0:29   ` Eric Sunshine
2018-01-08 18:33     ` Stefan Beller
2018-01-06 18:46 ` [PATCH 2/8] Doc/gitsubmodules: clearly specify advantage of submodule Kaartic Sivaraam
2018-01-08 18:36   ` Stefan Beller
2018-01-09 15:58     ` Kaartic Sivaraam
2018-01-06 18:46 ` [PATCH 3/8] Doc/gitsubmodules: specify how submodules help in reduced size Kaartic Sivaraam
2018-01-07  0:31   ` Eric Sunshine
2018-01-08 18:38   ` Stefan Beller
2018-01-09 16:01     ` Kaartic Sivaraam
2018-01-09 19:01       ` Stefan Beller
2018-01-09 19:30         ` Kaartic Sivaraam
2018-01-06 18:46 ` [PATCH 4/8] Doc/gitsubmodules: avoid abbreviations Kaartic Sivaraam
2018-01-07  0:36   ` Eric Sunshine
2018-01-08 18:45   ` Stefan Beller
2018-01-09 16:06     ` Kaartic Sivaraam
2018-01-09 19:26       ` Stefan Beller
2018-01-09 19:32         ` Kaartic Sivaraam
2018-01-06 18:46 ` [PATCH 5/8] Doc/gitsubmodules: use "Git directory" consistently Kaartic Sivaraam
2018-01-07  0:39   ` Eric Sunshine
2018-01-08 18:45     ` Stefan Beller
2018-01-06 18:46 ` [PATCH 6/8] Doc/gitsubmodules: improve readability of certain lines Kaartic Sivaraam
2018-01-07  0:44   ` Eric Sunshine
2018-01-08 18:49   ` Stefan Beller
2018-01-09 16:37     ` Kaartic Sivaraam
2018-01-09 19:31       ` Stefan Beller
2018-01-09 19:57         ` Kaartic Sivaraam
2018-01-06 18:46 ` [PATCH 7/8] Doc/git-submodule: improve readability and grammar of a sentence Kaartic Sivaraam
2018-01-08 18:57   ` Stefan Beller
2018-01-06 18:46 ` [PATCH 8/8] Doc/git-submodule: correctly quote important words Kaartic Sivaraam
2018-01-08 19:08 ` Stefan Beller [this message]
2018-01-09 17:06   ` [PATCH 0/8] Doc/submodules: a few updates Kaartic Sivaraam
2018-01-09 18:50     ` Stefan Beller
2018-01-10  6:49 ` [PATCH v2 0/2] " Kaartic Sivaraam
2018-01-10  6:49   ` [PATCH v2 1/2] Doc/gitsubmodules: make some changes to improve readability and syntax Kaartic Sivaraam
2018-01-10 20:49     ` Stefan Beller
2018-01-10  6:49   ` [PATCH v2 2/2] Doc/git-submodule: improve readability and grammar of a sentence Kaartic Sivaraam
2018-01-14 17:37   ` [PATCH v3 0/2] Doc/submodules: a few updates Kaartic Sivaraam
2018-01-14 17:37     ` [PATCH v3 1/2] Doc/gitsubmodules: make some changes to improve readability and syntax Kaartic Sivaraam
2018-01-16 20:03       ` Stefan Beller
2018-01-14 17:37     ` [PATCH v3 2/2] Doc/git-submodule: improve readability and grammar of a sentence Kaartic Sivaraam
2018-01-16 20:02     ` [PATCH v3 0/2] Doc/submodules: a few updates Junio C Hamano
2018-01-17  2:45       ` 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 using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to='CAGZ79kZ-UNCyCzmg=5PQ_p5xbmCp7HUc0=TXNBxwTjZDCnJtBg@mail.gmail.com' \
    --to=sbeller@google.com \
    --cc=bmwill@google.com \
    --cc=git@vger.kernel.org \
    --cc=kaartic.sivaraam@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