From: Stefan Beller <sbeller@google.com>
To: Kaartic Sivaraam <kaartic.sivaraam@gmail.com>
Cc: Brandon Williams <bmwill@google.com>,
Git mailing list <git@vger.kernel.org>
Subject: Re: [PATCH 0/8] Doc/submodules: a few updates
Date: Tue, 9 Jan 2018 10:50:10 -0800 [thread overview]
Message-ID: <CAGZ79kZ97-sLS4mP28rLoMqf2z8KU0FZ5=fcogynYQKdxji=ng@mail.gmail.com> (raw)
In-Reply-To: <64503247-66ad-03cf-26ba-3383337971b5@gmail.com>
On Tue, Jan 9, 2018 at 9:06 AM, Kaartic Sivaraam
<kaartic.sivaraam@gmail.com> wrote:
> On Tuesday 09 January 2018 12:38 AM, Stefan Beller wrote:
>> On Sat, Jan 6, 2018 at 10:46 AM, Kaartic Sivaraam
>> <kaartic.sivaraam@gmail.com> wrote:
>>
>> 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 wouldn't mind that. I thought it might be easy to find to find the
> parts I changed when the patches are small. So, I sent them without
> squashing them together. In case you feel it's not worth, let me know so
> I'll squash them in.
>
> BTW, in case I did squash them in, would it be nice to keep the commit
> subjects of the current patch series as bullet points in the unified
> commit message?
Sure.
>> 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.
>>
>
> Possibly. So, why not in Documentation/gitsubmodules! Here's a replaced
> version of that paragraph,
>
> * The configuration file `$GIT_DIR/config` in the superproject.
> Typically this file is used to specify whether the submodule
> is recursed into at all via the `active` flag for example. A
> submodule is considered active if `submodule.<name>.url` is set
> or if the submodules path is present in `submodule.active` or
> if `submodule.<name>.url` is set.
I wonder if we'd want to give an example later, and first describe the
mechanics precisely:
The configuration file `$GIT_DIR/config` in the superproject.
Git only recurses into active submodules. A submodule is
considered active (a) if `submodule.<name>.active` is set
or (b) if the submodules path is matches the pathsepc in
`submodule.active` or (c) if `submodule.<name>.url` is set.
(c) is a historical artefact and will be ignored if the pathspec
set in (b) excludes the submodule. For example:
[submodule "foo"]
active = false
url = https://example.org/foo
[submodule "bar"]
active = true
url = https://example.org/bar
[submodule "baz"]
url = https://example.org/baz
In the above config only the submodule bar and baz are active,
bar due to (a) and baz due to (c). Another example
[submodule "foo"]
active = true
url = https://example.org/foo
[submodule "bar"]
url = https://example.org/bar
[submodule "baz"]
url = https://example.org/baz
[submodule "bob"]
ignore = true
[submodule]
active = b*
active = (:exclude) baz
In here all submodules except baz (foo, bar, bob) are active.
'foo' due to its own active flag and all the others due to the
submodule active pathspec, which specifies that any submodule
starting with 'b' except 'baz' are also active, no matter if the .url field
is present.
>>> 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.
>>
>
> If that's the case then shouldn't the "if appropriate" part of "(using
> git checkout --force if appropriate)" be dropped? That seems to make it
> clear, at least for me. Or is intended as '--force' will not be passed
> to git checkout all the time?
>
Yes, essentially we only pass the force flag when we were given the force flag
("when appropriate" :) Not sure how to say that otherwise. But dropping sounds
good)
Stefan
next prev parent reply other threads:[~2018-01-09 18:50 UTC|newest]
Thread overview: 44+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-01-06 18:46 [PATCH 0/8] Doc/submodules: a few updates 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 ` [PATCH 0/8] Doc/submodules: a few updates Stefan Beller
2018-01-09 17:06 ` Kaartic Sivaraam
2018-01-09 18:50 ` Stefan Beller [this message]
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 publicly 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='CAGZ79kZ97-sLS4mP28rLoMqf2z8KU0FZ5=fcogynYQKdxji=ng@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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).