Re: [PATCH] doc: fetch: document `--jobs=0` behavior

From: Daniel Beck <daniel@ddbeck.com>
Date: Feb 24, 2026, 09:47 UTC
Message-ID: <FDB97002-401E-4F36-95AA-7FB772F9301F@ddbeck.com>
In-Reply-To: <aZggm7R-4VohiCYm@pks.im>

Show 33 quoted lines

> On 20 Feb 2026, at 09:51, Patrick Steinhardt <ps@pks.im> wrote:
> 
> On Thu, Feb 19, 2026 at 10:59:10AM -0800, Junio C Hamano wrote:
>> Patrick Steinhardt <ps@pks.im> writes:
>> 
>>> On Wed, Feb 18, 2026 at 07:32:39PM +0000, Daniel D. Beck via GitGitGadget wrote:
>>>> diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc
>>>> index fcba46ee9e..e15cbc51f2 100644
>>>> --- a/Documentation/fetch-options.adoc
>>>> +++ b/Documentation/fetch-options.adoc
>>>> @@ -234,6 +234,8 @@ endif::git-pull[]
>>>> `--jobs=<n>`::
>>>> Parallelize all forms of fetching up to _<n>_ jobs at a time.
>>>> +
>>>> +A value of 0 will use some reasonable default.
>>> 
>>> Can't we do better though than saying "some reasonable default"? As a
>>> user I would wonder what this is even supposed to mean. True, we don't
>>> do so either in the documentation of "fetch.parallel". But arguably, we
>>> should update both sites to reflect the status quo.
>>> 
>>> Going into the code we seem to fall back to `online_cpus()`. So should
>>> we document this accordingly?
>> 
>> I do not have time to dig this out myself from ancient discussion
>> threads, but we probably had the same discussion when "git config
>> --help" described the fetch.parallel with exactly the same phrasing
>> and decided to leave the exact implementation detail out of the
>> end-user facing documentation.
> 
> Doesn't look like it. The thread in question is [1], and neither the
> commit message nor the discussion around the patch mentioned why we
> don't document what the reasonable default is.

(This is my first reply to this mailing list. Apologies in advance for any formatting mistakes.)

To set aside the history for a moment, I submitted this patch because, as a Git user, I was looking for someone to just tell me a reasonable number of jobs to use. I was pleased to find that Git already had a "don't make me think" value built in.

If there's a possibility to giving this behavior a name like `--jobs=auto` [1], then I'd recommend against specifically promising a strategy in the docs. It would preserve that "don't make me think" quality. Plus it would leave the door open to changing that strategy, if a better method came along.

That said, if the strategy is meant to be meaningful to users, then I'd suggest naming it something like `--jobs=cpus` at the same time as describing the workings of `online_cpus()`.

In any case, thanks for the thoughtful consideration of my patch.

Daniel

[1]: <xmqq342w7hx2.fsf@gitster.g>

Show 10 quoted lines

> 
> Dscho, do you remember by chance why you decided to not be more specific
> here?
> 
> Thanks!
> 
> Patrick
> 
> [1]: <pull.369.git.gitgitgadget@gmail.com>
>