# [PATCH] doc: fetch: document `--jobs=0` behavior 8 messages from 2026-02-18 to 2026-03-02. Participants: Daniel D. Beck via GitGitGadget, Patrick Steinhardt, Junio C Hamano, Daniel Beck, Johannes Schindelin. Thread: https://gitlist.dev/t/65015 ## Daniel D. Beck via GitGitGadget, 2026-02-18 19:32 Subject: [PATCH] doc: fetch: document `--jobs=0` behavior Message-ID: URL: https://gitlist.dev/e/pull.2047.git.1771443159369.gitgitgadget%40gmail.com ``` From: "Daniel D. Beck" In c39952b92 (fetch: choose a sensible default with --jobs=0 again, 2023-02-20), the `--jobs=0` behavior was (re)introduced, but it went undocumented. Since this is the same behavior as `git -c fetch.parallel=0 fetch`, which is documented, this change creates symmetry between the two documentation sections. Signed-off-by: Daniel D. Beck --- doc: fetch: document --jobs=0 behavior Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2047%2Fddbeck%2Fdoc-git-fetch-jobs-0-v1 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2047/ddbeck/doc-git-fetch-jobs-0-v1 Pull-Request: https://github.com/gitgitgadget/git/pull/2047 Documentation/fetch-options.adoc | 2 ++ 1 file changed, 2 insertions(+) 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=`:: Parallelize all forms of fetching up to __ jobs at a time. + +A value of 0 will use some reasonable default. ++ If the `--multiple` option was specified, the different remotes will be fetched in parallel. If multiple submodules are fetched, they will be fetched in parallel. To control them independently, use the config settings base-commit: 852829b3dd2fe4e7c7fc4d8badde644cf1b66c74 -- gitgitgadget ``` ## Patrick Steinhardt, 2026-02-19 11:39 Subject: Re: [PATCH] doc: fetch: document `--jobs=0` behavior Message-ID: URL: https://gitlist.dev/e/aZb2acEvAtNmt-4j%40pks.im In-Reply-To: ``` 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=`:: > Parallelize all forms of fetching up to __ 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? Thanks! Patrick ``` ## Junio C Hamano, 2026-02-19 17:38 Subject: Re: [PATCH] doc: fetch: document `--jobs=0` behavior Message-ID: URL: https://gitlist.dev/e/xmqq342w7hx2.fsf%40gitster.g In-Reply-To: ``` "Daniel D. Beck via GitGitGadget" writes: > From: "Daniel D. Beck" > > In c39952b92 (fetch: choose a sensible default with --jobs=0 again, > 2023-02-20), the `--jobs=0` behavior was (re)introduced, but it went > undocumented. Since this is the same behavior as `git -c fetch.parallel=0 > fetch`, which is documented, this change creates symmetry between the two > documentation sections. Makes sense. In hindsight, we might have been better off if we also called this "--jobs=auto", but documenting the behaviour is a good first step. Will queue. Thanks. > > Signed-off-by: Daniel D. Beck > --- > doc: fetch: document --jobs=0 behavior > > Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2047%2Fddbeck%2Fdoc-git-fetch-jobs-0-v1 > Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2047/ddbeck/doc-git-fetch-jobs-0-v1 > Pull-Request: https://github.com/gitgitgadget/git/pull/2047 > > Documentation/fetch-options.adoc | 2 ++ > 1 file changed, 2 insertions(+) > > 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=`:: > Parallelize all forms of fetching up to __ jobs at a time. > + > +A value of 0 will use some reasonable default. > ++ > If the `--multiple` option was specified, the different remotes will be fetched > in parallel. If multiple submodules are fetched, they will be fetched in > parallel. To control them independently, use the config settings > > base-commit: 852829b3dd2fe4e7c7fc4d8badde644cf1b66c74 ``` ## Junio C Hamano, 2026-02-19 18:59 Subject: Re: [PATCH] doc: fetch: document `--jobs=0` behavior Message-ID: URL: https://gitlist.dev/e/xmqq4inc5zlt.fsf%40gitster.g In-Reply-To: ``` Patrick Steinhardt 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=`:: >> Parallelize all forms of fetching up to __ 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. Thanks. ``` ## Patrick Steinhardt, 2026-02-20 08:51 Subject: Re: [PATCH] doc: fetch: document `--jobs=0` behavior Message-ID: URL: https://gitlist.dev/e/aZggm7R-4VohiCYm%40pks.im In-Reply-To: ``` On Thu, Feb 19, 2026 at 10:59:10AM -0800, Junio C Hamano wrote: > Patrick Steinhardt 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=`:: > >> Parallelize all forms of fetching up to __ 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. Dscho, do you remember by chance why you decided to not be more specific here? Thanks! Patrick [1]: ``` ## Daniel Beck, 2026-02-24 09:47 Subject: Re: [PATCH] doc: fetch: document `--jobs=0` behavior Message-ID: URL: https://gitlist.dev/e/FDB97002-401E-4F36-95AA-7FB772F9301F%40ddbeck.com In-Reply-To: ``` > On 20 Feb 2026, at 09:51, Patrick Steinhardt wrote: > > On Thu, Feb 19, 2026 at 10:59:10AM -0800, Junio C Hamano wrote: >> Patrick Steinhardt 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=`:: >>>> Parallelize all forms of fetching up to __ 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]: > > Dscho, do you remember by chance why you decided to not be more specific > here? > > Thanks! > > Patrick > > [1]: > ``` ## Johannes Schindelin, 2026-03-02 12:35 Subject: Re: [PATCH] doc: fetch: document `--jobs=0` behavior Message-ID: <25715312-b6a0-0cdd-d62c-3a4a840b0244@gmx.de> URL: https://gitlist.dev/e/25715312-b6a0-0cdd-d62c-3a4a840b0244%40gmx.de In-Reply-To: ``` Hi Patrick, On Fri, 20 Feb 2026, Patrick Steinhardt wrote: > On Thu, Feb 19, 2026 at 10:59:10AM -0800, Junio C Hamano wrote: > > Patrick Steinhardt 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=`:: > > >> Parallelize all forms of fetching up to __ 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= 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 > > Thanks! > > Patrick > > [1]: > 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 ``` ## Junio C Hamano, 2026-03-02 19:33 Subject: Re: [PATCH] doc: fetch: document `--jobs=0` behavior Message-ID: URL: https://gitlist.dev/e/xmqqo6l6yqkp.fsf%40gitster.g In-Reply-To: <25715312-b6a0-0cdd-d62c-3a4a840b0244@gmx.de> ``` Johannes Schindelin writes: >> 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= 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. The belief that "available CPU cores is a reasonable default" turns out to be older than that. Back in the days we didn't thread iterations of the same topic properly, so visiting the discussion thread and trying to find older iterations of the same topic was a nightmare, but I think I found where the phrasing came from: https://lore.kernel.org/git/1446074504-6014-6-git-send-email-sbeller@google.com/ This is a step in the second iteration of fetching submodules in parallel topic from 28 Oct 2015, where "some reasonable default" appears. I think it was done in response to a review comment on its earlier iteration which was: https://lore.kernel.org/git/xmqqio5sni1j.fsf@gitster.mtv.corp.google.com/ Later the work resulted in a028a193 (fetching submodules: respect `submodule.fetchJobs` config option, 2016-02-29). https://lore.kernel.org/git/1456798040-30129-4-git-send-email-sbeller@google.com/ The variable fetch.parallel did not exist until d54dea77 (fetch: let --jobs= parallelize --multiple, too, 2019-10-05) copied the famous "some reasonable default" phrasing to its documentation. ```