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

From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Mar 2, 2026, 12:35 UTC
Message-ID: <25715312-b6a0-0cdd-d62c-3a4a840b0244@gmx.de>
In-Reply-To: <aZggm7R-4VohiCYm@pks.im>

Hi Patrick,

On Fri, 20 Feb 2026, Patrick Steinhardt wrote:

Show 31 quoted lines

> 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.

Thank you for digging deeper. There was indeed no discussion about this in https://lore.kernel.org/git/pull.369.git.gitgitgadget@gmail.com/t/#u.

There was no discussion about that, either, in response to the What's Cooking email talking about the preceding pd/fetch-jobs branch: https://lore.kernel.org/git/mhng-2c9b8fd0-22e7-4679-9d9b-f8128881fada@palmer-si-x1e/t/#mb58c71041bd41456ba0135437952ae15760e6724

Nor was there any discussion about the "reasonable default" in thr original `pd/fetch-jobs` contribution: https://lore.kernel.org/git/mhng-0d288d1c-02fc-4280-bd8f-b7f611af3e8a@palmer-si-x1c4/t/#u

> Dscho, do you remember by chance why you decided to not be more specific
> here?

Unfortunately not.

So I went on reconstructing the lay of the land back when d54dea77dba (fetch: let --jobs=<n> parallelize --multiple, too, 2019-10-05) landed. With that commit, the `max_children` variable (which `--jobs=0` would set to 0) would be passed via `fetch_multiple()` [*1*] or `fetch_populated_submodules()` [*2*] to `run_processes_parallel_tr2()`, which would pass it through to `run_processes_parallel()` as the first parameter (called `n`) [*3*]. That function would pass that variable to `pp_init()` first thing [*4*], which would fall back to `online_cpus()` if it saw a value smaller than 1 [*5*].

So: The "reasonable default" is the number of CPUs, or more correctly, of
CPU cores. It does seem, though, that that was considered common knowledge
at the time, given e.g. v2.40.0's release notes saying [*6*]:

  "git fetch --jobs=0" used to hit a BUG(), which has been corrected
  to use the available CPUs.

Ciao, Johannes

Show 7 quoted lines

> 
> Thanks!
> 
> Patrick
> 
> [1]: <pull.369.git.gitgitgadget@gmail.com>
>

Footnote *1*: https://gitlab.com/git-scm/git/-/blob/d54dea77dba081770fec7707110d8480ccaf9439/builtin/fetch.c#L1783

Footnote *2*: https://gitlab.com/git-scm/git/-/blob/d54dea77dba081770fec7707110d8480ccaf9439/builtin/fetch.c#L1796

Footnote *3*: https://gitlab.com/git-scm/git/-/blob/d54dea77dba081770fec7707110d8480ccaf9439/run-command.c#L1860

Footnote *4*: https://gitlab.com/git-scm/git/-/blob/d54dea77dba081770fec7707110d8480ccaf9439/run-command.c#L1819

Footnote *5*: https://gitlab.com/git-scm/git/-/blob/d54dea77dba081770fec7707110d8480ccaf9439/run-command.c#L1611-1612

Footnote *6*: https://gitlab.com/git-scm/git/-/blob/v2.40.0/Documentation/RelNotes/2.40.0.txt#L57-58