git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Philippe Blain <levraiphilippeblain@gmail.com>
To: Damien Robert <damien.olivier.robert@gmail.com>
Cc: git@vger.kernel.org, Damien Robert <damien.olivier.robert+git@gmail.com>
Subject: Re: [PATCH v3 5/5] doc: --recurse-submodules mostly only apply to active submodules
Date: Sun, 22 Mar 2020 18:38:47 -0400	[thread overview]
Message-ID: <3689E44D-AB57-448E-99AA-C5317373E825@gmail.com> (raw)
In-Reply-To: <20200320213729.571924-6-damien.olivier.robert+git@gmail.com>


> Le 20 mars 2020 à 17:37, Damien Robert <damien.olivier.robert@gmail.com> a écrit

in the title, I'd drop the "only"
"mostly only apply" -> "mostly applies"

> :
> 
> The documentation refers to "initialized" or "populated" submodules,
> to explain which submodules are affected by '--recurse-submodules', but
> the real terminology here is 'active' submodules. Update the
> documentation accordingly.
> 
> Some terminology:
> - Active is defined in gitsubmodules(7), it only involves the
>  configuration variables 'submodule.active', 'submodule.<name>.active'
>  and 'submodule.<name>.url'. The function
>  submodule.c::is_submodule_active checks that a submodule is active.
> - Populated means that the submodule's working tree is present (and the
>  gitfile correctly points to the submodule repository), i.e. either the
>  superproject was cloned with ` --recurse-submodules`, or the user ran
>  `git submodule update --init`, or `git submodule init [<path>]` and
>  `git submodule update [<path]`

missing a closing '>' here (my mistake).

> separately which populated the
>  submodule working tree. This does not involve the 3 configuration
>  variables above.
> - Initialized (at least in the context of the man pages involved in this
>  patch) means both "populated" and "active" as defined above, i.e. what
>  `git submodule update --init` does.
> 
> The --recurse-submodules option mostly affects submodules.

I think you meant  "mostly affects active submodules" here, right?

> An exception
> is `git fetch` where the option affects populated submodules.
> As a consequence, in `git pull` the fetch affects populated submodules,
> but the resulting working tree update only affects active submodules.
> 
> In the documentation of `git-pull` we only refer to active submodules,
> since it is implicit that the fetching behaviour is governed by the
> fetch command.

This last paragraph is not a description of the current state of the code base, 
but describes the changes introduced by this patch. As such, it's customary
to write it in the imperative mode. A simple suggestion to fix that:

s/we/let's/

> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
> index 47bc4a7061..2285f3729d 100644
> --- a/Documentation/git-pull.txt
> +++ b/Documentation/git-pull.txt
> @@ -85,7 +85,7 @@ OPTIONS
> 	Pass --verbose to git-fetch and git-merge.
> 
> --[no-]recurse-submodules[=yes|on-demand|no]::
> -	This option controls if new commits of all populated submodules should
> +	This option controls if new commits of all active submodules should
> 	be fetched and updated, too (see linkgit:git-fetch[1], linkgit:git-config[1] and linkgit:gitmodules[5]).

I understand that the goal here is to make the formulation not too heavy, as you wrote in 
https://lore.kernel.org/git/20200320222328.lynvrgqc35pvxxnl@doriath/. However I think the formulation 
is awkward to begin with : commits are "fetched", but commits are not "updated", the submodules working tree 
are updated. So maybe:

This option controls if new commits of populated submodules should be fetched, 
and if the working trees of active submodules should be updated, too

  reply	other threads:[~2020-03-22 22:38 UTC|newest]

Thread overview: 69+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-02-28 10:35 [PATCH 0/4] doc: --recurse-submodules Damien Robert
2020-02-28 10:35 ` [PATCH 1/4] doc: list all commands affected by recurse.submodule Damien Robert
2020-03-02  4:43   ` Philippe Blain
2020-03-03 17:09     ` Damien Robert
2020-02-28 10:35 ` [PATCH 2/4] doc: document --recurse-submodules for reset and restore Damien Robert
2020-03-02  4:45   ` Philippe Blain
2020-03-03 17:26     ` Damien Robert
2020-03-06  4:16       ` Philippe Blain
2020-02-28 10:35 ` [PATCH 3/4] doc: explain how to deactivate recurse.submodule completely Damien Robert
2020-03-02  4:45   ` Philippe Blain
2020-02-28 10:35 ` [PATCH 4/4] doc: be more precise on (fetch|pull).recurseSubmodules Damien Robert
2020-03-02  4:46   ` Philippe Blain
2020-02-28 10:44 ` [PATCH 0/4] doc: --recurse-submodules Damien Robert
2020-03-03  5:18   ` Philippe Blain
2020-03-02  4:47 ` Philippe Blain
2020-03-03 17:07 ` [PATCH v2 0/5] " Damien Robert
2020-03-03 17:07   ` [PATCH v2 1/5] doc: list all commands affected by submodule.recurse Damien Robert
2020-03-03 17:07   ` [PATCH v2 2/5] doc: document --recurse-submodules for reset and restore Damien Robert
2020-03-03 21:54     ` Junio C Hamano
2020-03-06  4:16     ` Philippe Blain
2020-03-03 17:07   ` [PATCH v2 3/5] doc: explain how to deactivate recurse.submodule completely Damien Robert
2020-03-03 21:57     ` Junio C Hamano
2020-03-03 22:05       ` Robert P. J. Day
2020-03-03 22:04     ` Damien Robert
2020-03-06  4:16       ` Philippe Blain
2020-03-03 17:07   ` [PATCH v2 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert
2020-03-03 22:05     ` Junio C Hamano
2020-03-03 22:12       ` Robert P. J. Day
2020-03-03 17:07   ` [PATCH v2 5/5] doc: --recurse-submodules only apply to active submodules Damien Robert
2020-03-06  4:17     ` Philippe Blain
2020-03-20 22:23       ` Damien Robert
2020-03-20 21:37 ` [PATCH v3 0/5] doc: --recurse-submodules Damien Robert
2020-03-20 21:37   ` [PATCH v3 1/5] doc: list all commands affected by submodule.recurse Damien Robert
2020-03-20 21:37   ` [PATCH v3 2/5] doc: document --recurse-submodules for reset and restore Damien Robert
2020-03-22 22:36     ` Philippe Blain
2020-03-25 21:05       ` Damien Robert
2020-03-20 21:37   ` [PATCH v3 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert
2020-03-22 22:36     ` Philippe Blain
2020-03-20 21:37   ` [PATCH v3 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert
2020-03-22 22:37     ` Philippe Blain
2020-03-22 23:01       ` Junio C Hamano
2020-03-22 23:21         ` Philippe Blain
2020-03-20 21:37   ` [PATCH v3 5/5] doc: --recurse-submodules mostly only apply to active submodules Damien Robert
2020-03-22 22:38     ` Philippe Blain [this message]
2020-03-25 21:09   ` [PATCH v4 0/5] doc: --recurse-submodules Damien Robert
2020-03-25 21:09     ` [PATCH v4 1/5] doc: list all commands affected by submodule.recurse Damien Robert
2020-03-25 21:09     ` [PATCH v4 2/5] doc: document --recurse-submodules for reset and restore Damien Robert
2020-03-29 20:34       ` Philippe Blain
2020-03-25 21:09     ` [PATCH v4 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert
2020-03-25 21:09     ` [PATCH v4 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert
2020-03-29 20:49       ` Philippe Blain
2020-03-25 21:09     ` [PATCH v4 5/5] doc: --recurse-submodules mostly applies to active submodules Damien Robert
2020-04-05 20:16   ` [PATCH v5 0/5] doc: --recurse-submodules Damien Robert
2020-04-05 20:16     ` [PATCH v5 1/5] doc: list all commands affected by submodule.recurse Damien Robert
2020-04-05 20:16     ` [PATCH v5 2/5] doc: document --recurse-submodules for reset and restore Damien Robert
2020-04-05 20:16     ` [PATCH v5 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert
2020-04-05 20:16     ` [PATCH v5 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert
2020-04-05 21:57       ` Junio C Hamano
2020-04-06 13:49         ` Damien Robert
2020-04-06 17:56           ` Junio C Hamano
2020-04-06 18:42             ` Damien Robert
2020-04-05 20:16     ` [PATCH v5 5/5] doc: --recurse-submodules mostly applies to active submodules Damien Robert
2020-04-06 13:57   ` [PATCH v6 0/5] doc: --recurse-submodules Damien Robert
2020-04-06 13:57     ` [PATCH v6 1/5] doc: list all commands affected by submodule.recurse Damien Robert
2020-04-06 13:57     ` [PATCH v6 2/5] doc: document --recurse-submodules for reset and restore Damien Robert
2020-04-06 13:57     ` [PATCH v6 3/5] doc: explain how to deactivate submodule.recurse completely Damien Robert
2020-04-06 13:57     ` [PATCH v6 4/5] doc: be more precise on (fetch|push).recurseSubmodules Damien Robert
2020-04-06 13:57     ` [PATCH v6 5/5] doc: --recurse-submodules mostly applies to active submodules Damien Robert
2020-04-16 13:09     ` [PATCH v6 0/5] doc: --recurse-submodules Philippe Blain

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=3689E44D-AB57-448E-99AA-C5317373E825@gmail.com \
    --to=levraiphilippeblain@gmail.com \
    --cc=damien.olivier.robert+git@gmail.com \
    --cc=damien.olivier.robert@gmail.com \
    --cc=git@vger.kernel.org \
    /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).