Re: [PATCH] Documentation/fetch-options: emit recurse-submodules, jobs unconditionally

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 26, 2016, 20:29 UTC
Message-ID: <xmqq7f9yqu9w.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20160926193553.32631-1-sbeller@google.com>

Stefan Beller <sbeller@google.com> writes:

Show 8 quoted lines

> Currently the section about recursing into submodules is repeated in
> git-pull word for word as it is in fetch-options.
>
> Don't repeat ourselves here and include the --recurse-submodules via
> fetch options.
>
> As a bonus expose the --jobs parameter in git-pull as well as that is
> declared as a OPT_PASSTHRU for fetch internally already.

The above may not be technically wrong, but smells like an under-researched description.

IOW, "Why did the commit that introduced the option described it this way in the first place? Was there a specific reason why it had to be that way, and that reason is no longer with us now, which makes this change safe?" is a very natural question somebody who sees this patch, and your description does not answer it.

It seems that the option to recurse into submodules was added by Jens's 7dce19d3 ("fetch/pull: Add the --recurse-submodules option", 2010-11-12) to both fetch and pull at the same time. I suspected perhaps we hid it from pull initially while describing it for fetch, but that does not seem to be the case, and back at that version, pull and fetch shared the description without duplicating.

So where did we go wrong? Was there a good reason why we have two instances of these option descriptions, and if so, are we sure that that reason is no longer applicable to today's system that we can safely share the description? The proposed log message is a place to answer these questions.

By the way, 7dce19d3 is interesting in another way and worth studying in that it adds --submodule-prefix ;-) It may be something we want to consider consolidating with what Brandon has been working on.

By the way^2, the "unconditionally" on the title conveyed less information than their bits weigh. Unless a reader knows fetch-options are shared between fetch and pull, s/he would not know you meant by "unconditionally" to show these in both fetch and pull.

    Documentation: share more descriptions for options between fetch and pull

perhaps?

Thanks.