{"thread":{"id":"65015","subject":"[PATCH] doc: fetch: document `--jobs=0` behavior","startedAt":"2026-02-18T19:32:42Z","lastAt":"2026-03-02T19:33:12Z","messageCount":8,"participants":["Daniel D. Beck via GitGitGadget","Patrick Steinhardt","Junio C Hamano","Daniel Beck","Johannes Schindelin"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"536324","messageId":"pull.2047.git.1771443159369.gitgitgadget@gmail.com","threadId":"65015","inReplyTo":null,"subject":"[PATCH] doc: fetch: document `--jobs=0` behavior","fromName":"Daniel D. Beck via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-02-18T19:32:39Z","receivedAt":"2026-02-18T19:32:42Z","isPatch":true,"sender":{"key":"name:Daniel D. Beck","avatar":null},"body":"From: \"Daniel D. Beck\" \n\nIn c39952b92 (fetch: choose a sensible default with --jobs=0 again,\n2023-02-20), the `--jobs=0` behavior was (re)introduced, but it went\nundocumented. Since this is the same behavior as `git -c fetch.parallel=0\nfetch`, which is documented, this change creates symmetry between the two\ndocumentation sections.\n\nSigned-off-by: Daniel D. Beck \n---\n doc: fetch: document --jobs=0 behavior\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2047%2Fddbeck%2Fdoc-git-fetch-jobs-0-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2047/ddbeck/doc-git-fetch-jobs-0-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/2047\n\n Documentation/fetch-options.adoc | 2 ++\n 1 file changed, 2 insertions(+)\n\ndiff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc\nindex fcba46ee9e..e15cbc51f2 100644\n--- a/Documentation/fetch-options.adoc\n+++ b/Documentation/fetch-options.adoc\n@@ -234,6 +234,8 @@ endif::git-pull[]\n `--jobs=`::\n \tParallelize all forms of fetching up to __ jobs at a time.\n +\n+A value of 0 will use some reasonable default.\n++\n If the `--multiple` option was specified, the different remotes will be fetched\n in parallel. If multiple submodules are fetched, they will be fetched in\n parallel. To control them independently, use the config settings\n\nbase-commit: 852829b3dd2fe4e7c7fc4d8badde644cf1b66c74\n-- \ngitgitgadget\n"},{"id":"536397","messageId":"aZb2acEvAtNmt-4j@pks.im","threadId":"65015","inReplyTo":"pull.2047.git.1771443159369.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: fetch: document `--jobs=0` behavior","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-02-19T11:39:27Z","receivedAt":"2026-02-19T11:39:39Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Wed, Feb 18, 2026 at 07:32:39PM +0000, Daniel D. Beck via GitGitGadget wrote:\n> diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc\n> index fcba46ee9e..e15cbc51f2 100644\n> --- a/Documentation/fetch-options.adoc\n> +++ b/Documentation/fetch-options.adoc\n> @@ -234,6 +234,8 @@ endif::git-pull[]\n> `--jobs=`::\n> \tParallelize all forms of fetching up to __ jobs at a time.\n> +\n> +A value of 0 will use some reasonable default.\n\nCan't we do better though than saying \"some reasonable default\"? As a\nuser I would wonder what this is even supposed to mean. True, we don't\ndo so either in the documentation of \"fetch.parallel\". But arguably, we\nshould update both sites to reflect the status quo.\n\nGoing into the code we seem to fall back to `online_cpus()`. So should\nwe document this accordingly?\n\nThanks!\n\nPatrick\n"},{"id":"536422","messageId":"xmqq342w7hx2.fsf@gitster.g","threadId":"65015","inReplyTo":"pull.2047.git.1771443159369.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: fetch: document `--jobs=0` behavior","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-02-19T17:38:17Z","receivedAt":"2026-02-19T17:38:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Daniel D. Beck via GitGitGadget\" writes:\n\n> From: \"Daniel D. Beck\" \n>\n> In c39952b92 (fetch: choose a sensible default with --jobs=0 again,\n> 2023-02-20), the `--jobs=0` behavior was (re)introduced, but it went\n> undocumented. Since this is the same behavior as `git -c fetch.parallel=0\n> fetch`, which is documented, this change creates symmetry between the two\n> documentation sections.\n\nMakes sense. In hindsight, we might have been better off if we also\ncalled this \"--jobs=auto\", but documenting the behaviour is a good\nfirst step.\n\nWill queue. Thanks.\n\n\n>\n> Signed-off-by: Daniel D. Beck \n> ---\n> doc: fetch: document --jobs=0 behavior\n>\n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2047%2Fddbeck%2Fdoc-git-fetch-jobs-0-v1\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2047/ddbeck/doc-git-fetch-jobs-0-v1\n> Pull-Request: https://github.com/gitgitgadget/git/pull/2047\n>\n> Documentation/fetch-options.adoc | 2 ++\n> 1 file changed, 2 insertions(+)\n>\n> diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc\n> index fcba46ee9e..e15cbc51f2 100644\n> --- a/Documentation/fetch-options.adoc\n> +++ b/Documentation/fetch-options.adoc\n> @@ -234,6 +234,8 @@ endif::git-pull[]\n> `--jobs=`::\n> \tParallelize all forms of fetching up to __ jobs at a time.\n> +\n> +A value of 0 will use some reasonable default.\n> ++\n> If the `--multiple` option was specified, the different remotes will be fetched\n> in parallel. If multiple submodules are fetched, they will be fetched in\n> parallel. To control them independently, use the config settings\n>\n> base-commit: 852829b3dd2fe4e7c7fc4d8badde644cf1b66c74\n"},{"id":"536433","messageId":"xmqq4inc5zlt.fsf@gitster.g","threadId":"65015","inReplyTo":"aZb2acEvAtNmt-4j@pks.im","subject":"Re: [PATCH] doc: fetch: document `--jobs=0` behavior","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-02-19T18:59:10Z","receivedAt":"2026-02-19T18:59:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n> On Wed, Feb 18, 2026 at 07:32:39PM +0000, Daniel D. Beck via GitGitGadget wrote:\n>> diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc\n>> index fcba46ee9e..e15cbc51f2 100644\n>> --- a/Documentation/fetch-options.adoc\n>> +++ b/Documentation/fetch-options.adoc\n>> @@ -234,6 +234,8 @@ endif::git-pull[]\n>> `--jobs=`::\n>> \tParallelize all forms of fetching up to __ jobs at a time.\n>> +\n>> +A value of 0 will use some reasonable default.\n>\n> Can't we do better though than saying \"some reasonable default\"? As a\n> user I would wonder what this is even supposed to mean. True, we don't\n> do so either in the documentation of \"fetch.parallel\". But arguably, we\n> should update both sites to reflect the status quo.\n>\n> Going into the code we seem to fall back to `online_cpus()`. So should\n> we document this accordingly?\n\nI do not have time to dig this out myself from ancient discussion\nthreads, but we probably had the same discussion when \"git config\n--help\" described the fetch.parallel with exactly the same phrasing\nand decided to leave the exact implementation detail out of the\nend-user facing documentation.\n\nThanks.\n"},{"id":"536494","messageId":"aZggm7R-4VohiCYm@pks.im","threadId":"65015","inReplyTo":"xmqq4inc5zlt.fsf@gitster.g","subject":"Re: [PATCH] doc: fetch: document `--jobs=0` behavior","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-02-20T08:51:39Z","receivedAt":"2026-02-20T08:51:48Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Thu, Feb 19, 2026 at 10:59:10AM -0800, Junio C Hamano wrote:\n> Patrick Steinhardt writes:\n> \n> > On Wed, Feb 18, 2026 at 07:32:39PM +0000, Daniel D. Beck via GitGitGadget wrote:\n> >> diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc\n> >> index fcba46ee9e..e15cbc51f2 100644\n> >> --- a/Documentation/fetch-options.adoc\n> >> +++ b/Documentation/fetch-options.adoc\n> >> @@ -234,6 +234,8 @@ endif::git-pull[]\n> >> `--jobs=`::\n> >> \tParallelize all forms of fetching up to __ jobs at a time.\n> >> +\n> >> +A value of 0 will use some reasonable default.\n> >\n> > Can't we do better though than saying \"some reasonable default\"? As a\n> > user I would wonder what this is even supposed to mean. True, we don't\n> > do so either in the documentation of \"fetch.parallel\". But arguably, we\n> > should update both sites to reflect the status quo.\n> >\n> > Going into the code we seem to fall back to `online_cpus()`. So should\n> > we document this accordingly?\n> \n> I do not have time to dig this out myself from ancient discussion\n> threads, but we probably had the same discussion when \"git config\n> --help\" described the fetch.parallel with exactly the same phrasing\n> and decided to leave the exact implementation detail out of the\n> end-user facing documentation.\n\nDoesn't look like it. The thread in question is [1], and neither the\ncommit message nor the discussion around the patch mentioned why we\ndon't document what the reasonable default is.\n\nDscho, do you remember by chance why you decided to not be more specific\nhere?\n\nThanks!\n\nPatrick\n\n[1]: \n"},{"id":"536957","messageId":"FDB97002-401E-4F36-95AA-7FB772F9301F@ddbeck.com","threadId":"65015","inReplyTo":"aZggm7R-4VohiCYm@pks.im","subject":"Re: [PATCH] doc: fetch: document `--jobs=0` behavior","fromName":"Daniel Beck","fromEmail":"daniel@ddbeck.com","sentAt":"2026-02-24T09:47:44Z","receivedAt":"2026-02-24T09:47:57Z","isPatch":true,"sender":{"key":"daniel@ddbeck.com","avatar":null},"body":"\n> On 20 Feb 2026, at 09:51, Patrick Steinhardt wrote:\n> \n> On Thu, Feb 19, 2026 at 10:59:10AM -0800, Junio C Hamano wrote:\n>> Patrick Steinhardt writes:\n>> \n>>> On Wed, Feb 18, 2026 at 07:32:39PM +0000, Daniel D. Beck via GitGitGadget wrote:\n>>>> diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc\n>>>> index fcba46ee9e..e15cbc51f2 100644\n>>>> --- a/Documentation/fetch-options.adoc\n>>>> +++ b/Documentation/fetch-options.adoc\n>>>> @@ -234,6 +234,8 @@ endif::git-pull[]\n>>>> `--jobs=`::\n>>>> Parallelize all forms of fetching up to __ jobs at a time.\n>>>> +\n>>>> +A value of 0 will use some reasonable default.\n>>> \n>>> Can't we do better though than saying \"some reasonable default\"? As a\n>>> user I would wonder what this is even supposed to mean. True, we don't\n>>> do so either in the documentation of \"fetch.parallel\". But arguably, we\n>>> should update both sites to reflect the status quo.\n>>> \n>>> Going into the code we seem to fall back to `online_cpus()`. So should\n>>> we document this accordingly?\n>> \n>> I do not have time to dig this out myself from ancient discussion\n>> threads, but we probably had the same discussion when \"git config\n>> --help\" described the fetch.parallel with exactly the same phrasing\n>> and decided to leave the exact implementation detail out of the\n>> end-user facing documentation.\n> \n> Doesn't look like it. The thread in question is [1], and neither the\n> commit message nor the discussion around the patch mentioned why we\n> don't document what the reasonable default is.\n\n(This is my first reply to this mailing list. Apologies in advance for any\nformatting mistakes.)\n\nTo set aside the history for a moment, I submitted this patch because, as a\nGit user, I was looking for someone to just tell me a reasonable number of\njobs to use. I was pleased to find that Git already had a \"don't make me\nthink\" value built in.\n\nIf there's a possibility to giving this behavior a name like `--jobs=auto`\n[1], then I'd recommend against specifically promising a strategy in the\ndocs. It would preserve that \"don't make me think\" quality. Plus it would\nleave the door open to changing that strategy, if a better method came\nalong.\n\nThat said, if the strategy is meant to be meaningful to users, then I'd\nsuggest naming it something like `--jobs=cpus` at the same time as\ndescribing the workings of `online_cpus()`.\n\nIn any case, thanks for the thoughtful consideration of my patch.\n\nDaniel\n\n[1]: \n\n> \n> Dscho, do you remember by chance why you decided to not be more specific\n> here?\n> \n> Thanks!\n> \n> Patrick\n> \n> [1]: \n> \n\n"},{"id":"537517","messageId":"25715312-b6a0-0cdd-d62c-3a4a840b0244@gmx.de","threadId":"65015","inReplyTo":"aZggm7R-4VohiCYm@pks.im","subject":"Re: [PATCH] doc: fetch: document `--jobs=0` behavior","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2026-03-02T12:35:03Z","receivedAt":"2026-03-02T12:35:13Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Patrick,\n\nOn Fri, 20 Feb 2026, Patrick Steinhardt wrote:\n\n> On Thu, Feb 19, 2026 at 10:59:10AM -0800, Junio C Hamano wrote:\n> > Patrick Steinhardt writes:\n> > \n> > > On Wed, Feb 18, 2026 at 07:32:39PM +0000, Daniel D. Beck via GitGitGadget wrote:\n> > >> diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc\n> > >> index fcba46ee9e..e15cbc51f2 100644\n> > >> --- a/Documentation/fetch-options.adoc\n> > >> +++ b/Documentation/fetch-options.adoc\n> > >> @@ -234,6 +234,8 @@ endif::git-pull[]\n> > >> `--jobs=`::\n> > >> \tParallelize all forms of fetching up to __ jobs at a time.\n> > >> +\n> > >> +A value of 0 will use some reasonable default.\n> > >\n> > > Can't we do better though than saying \"some reasonable default\"? As a\n> > > user I would wonder what this is even supposed to mean. True, we don't\n> > > do so either in the documentation of \"fetch.parallel\". But arguably, we\n> > > should update both sites to reflect the status quo.\n> > >\n> > > Going into the code we seem to fall back to `online_cpus()`. So should\n> > > we document this accordingly?\n> > \n> > I do not have time to dig this out myself from ancient discussion\n> > threads, but we probably had the same discussion when \"git config\n> > --help\" described the fetch.parallel with exactly the same phrasing\n> > and decided to leave the exact implementation detail out of the\n> > end-user facing documentation.\n> \n> Doesn't look like it. The thread in question is [1], and neither the\n> commit message nor the discussion around the patch mentioned why we\n> don't document what the reasonable default is.\n\nThank you for digging deeper. There was indeed no discussion about this in\nhttps://lore.kernel.org/git/pull.369.git.gitgitgadget@gmail.com/t/#u.\n\nThere was no discussion about that, either, in response to the What's\nCooking email talking about the preceding pd/fetch-jobs branch:\nhttps://lore.kernel.org/git/mhng-2c9b8fd0-22e7-4679-9d9b-f8128881fada@palmer-si-x1e/t/#mb58c71041bd41456ba0135437952ae15760e6724\n\nNor was there any discussion about the \"reasonable default\" in thr\noriginal `pd/fetch-jobs` contribution:\nhttps://lore.kernel.org/git/mhng-0d288d1c-02fc-4280-bd8f-b7f611af3e8a@palmer-si-x1c4/t/#u\n\n> Dscho, do you remember by chance why you decided to not be more specific\n> here?\n\nUnfortunately not.\n\nSo I went on reconstructing the lay of the land back when d54dea77dba\n(fetch: let --jobs= parallelize --multiple, too, 2019-10-05) landed.\nWith that commit, the `max_children` variable (which `--jobs=0` would set\nto 0) would be passed via `fetch_multiple()` [*1*] or\n`fetch_populated_submodules()` [*2*] to `run_processes_parallel_tr2()`,\nwhich would pass it through to `run_processes_parallel()` as the first\nparameter (called `n`) [*3*]. That function would pass that variable to\n`pp_init()` first thing [*4*], which would fall back to `online_cpus()` if\nit saw a value smaller than 1 [*5*].\n\nSo: The \"reasonable default\" is the number of CPUs, or more correctly, of\nCPU cores. It does seem, though, that that was considered common knowledge\nat the time, given e.g. v2.40.0's release notes saying [*6*]:\n\n \"git fetch --jobs=0\" used to hit a BUG(), which has been corrected\n to use the available CPUs.\n\nCiao,\nJohannes\n\n> \n> Thanks!\n> \n> Patrick\n> \n> [1]: \n> \n\nFootnote *1*:\nhttps://gitlab.com/git-scm/git/-/blob/d54dea77dba081770fec7707110d8480ccaf9439/builtin/fetch.c#L1783\n\nFootnote *2*:\nhttps://gitlab.com/git-scm/git/-/blob/d54dea77dba081770fec7707110d8480ccaf9439/builtin/fetch.c#L1796\n\nFootnote *3*:\nhttps://gitlab.com/git-scm/git/-/blob/d54dea77dba081770fec7707110d8480ccaf9439/run-command.c#L1860\n\nFootnote *4*:\nhttps://gitlab.com/git-scm/git/-/blob/d54dea77dba081770fec7707110d8480ccaf9439/run-command.c#L1819\n\nFootnote *5*:\nhttps://gitlab.com/git-scm/git/-/blob/d54dea77dba081770fec7707110d8480ccaf9439/run-command.c#L1611-1612\n\nFootnote *6*:\nhttps://gitlab.com/git-scm/git/-/blob/v2.40.0/Documentation/RelNotes/2.40.0.txt#L57-58\n"},{"id":"537595","messageId":"xmqqo6l6yqkp.fsf@gitster.g","threadId":"65015","inReplyTo":"25715312-b6a0-0cdd-d62c-3a4a840b0244@gmx.de","subject":"Re: [PATCH] doc: fetch: document `--jobs=0` behavior","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-03-02T19:33:10Z","receivedAt":"2026-03-02T19:33:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Schindelin writes:\n\n>> Dscho, do you remember by chance why you decided to not be more specific\n>> here?\n>\n> Unfortunately not.\n>\n> So I went on reconstructing the lay of the land back when d54dea77dba\n> (fetch: let --jobs= parallelize --multiple, too, 2019-10-05) landed.\n> With that commit, the `max_children` variable (which `--jobs=0` would set\n> to 0) would be passed via `fetch_multiple()` [*1*] or\n> `fetch_populated_submodules()` [*2*] to `run_processes_parallel_tr2()`,\n> which would pass it through to `run_processes_parallel()` as the first\n> parameter (called `n`) [*3*]. That function would pass that variable to\n> `pp_init()` first thing [*4*], which would fall back to `online_cpus()` if\n> it saw a value smaller than 1 [*5*].\n>\n> So: The \"reasonable default\" is the number of CPUs, or more correctly, of\n> CPU cores. It does seem, though, that that was considered common knowledge\n> at the time, given e.g. v2.40.0's release notes saying [*6*]:\n>\n> \"git fetch --jobs=0\" used to hit a BUG(), which has been corrected\n> to use the available CPUs.\n\nThe belief that \"available CPU cores is a reasonable default\" turns\nout to be older than that.\n\nBack in the days we didn't thread iterations of the same topic\nproperly, so visiting the discussion thread and trying to find older\niterations of the same topic was a nightmare, but I think I found\nwhere the phrasing came from:\n\nhttps://lore.kernel.org/git/1446074504-6014-6-git-send-email-sbeller@google.com/\n\nThis is a step in the second iteration of fetching submodules in\nparallel topic from 28 Oct 2015, where \"some reasonable default\"\nappears. I think it was done in response to a review comment on its\nearlier iteration which was:\n\nhttps://lore.kernel.org/git/xmqqio5sni1j.fsf@gitster.mtv.corp.google.com/\n\nLater the work resulted in a028a193 (fetching submodules: respect\n`submodule.fetchJobs` config option, 2016-02-29).\n\nhttps://lore.kernel.org/git/1456798040-30129-4-git-send-email-sbeller@google.com/\n\nThe variable fetch.parallel did not exist until d54dea77 (fetch: let\n--jobs= parallelize --multiple, too, 2019-10-05) copied the\nfamous \"some reasonable default\" phrasing to its documentation.\n"}]}