From 0af23e9dc9c7e0f84d66b538fd755e7e14d5d89f Mon Sep 17 00:00:00 2001
From: Mike McQuaid <mike@mikemcquaid.com>
Date: Thu, 31 Jul 2025 12:18:08 +0100
Subject: [PATCH] Document `HOMEBREW_DOWNLOAD_CONCURRENCY` environment variable

We're going to be ready in 4.6.0 for users to try this out (but not
yet for it to be the default).
---
 Library/Homebrew/env_config.rb | 8 +++++++-
 docs/Manpage.md                | 9 +++++++++
 manpages/brew.1                | 7 +++++++
 3 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/Library/Homebrew/env_config.rb b/Library/Homebrew/env_config.rb
index 1d363b5d57..6b76aad65a 100644
--- a/Library/Homebrew/env_config.rb
+++ b/Library/Homebrew/env_config.rb
@@ -182,6 +182,13 @@ module Homebrew
         description: "Use this bearer token for authenticating with a Docker registry proxying GitHub Packages. " \
                      "Preferred over `$HOMEBREW_DOCKER_REGISTRY_BASIC_AUTH_TOKEN`.",
       },
+      HOMEBREW_DOWNLOAD_CONCURRENCY:             {
+        description: "If set, Homebrew will download in parallel using this many concurrent connections. " \
+                     "Setting to `auto` will use twice the number of available CPU cores " \
+                     "(what our benchmarks showed to produce the best performance). " \
+                     "If set to `1` (the default), Homebrew will download in serial.",
+        default:     1,
+      },
       HOMEBREW_EDITOR:                           {
         description:  "Use this editor when editing a single formula, or several formulae in the " \
                       "same directory." \
@@ -633,7 +640,6 @@ module Homebrew
 
     sig { returns(Integer) }
     def download_concurrency
-      # TODO: document this variable when ready to publicly announce it.
       concurrency = ENV.fetch("HOMEBREW_DOWNLOAD_CONCURRENCY", 1)
       concurrency = if concurrency == "auto"
         require "os"
diff --git a/docs/Manpage.md b/docs/Manpage.md
index cfdafbb973..e96fbcb444 100644
--- a/docs/Manpage.md
+++ b/docs/Manpage.md
@@ -4043,6 +4043,15 @@ command execution e.g. `$(cat file)`.
 : Use this bearer token for authenticating with a Docker registry proxying
   GitHub Packages. Preferred over `$HOMEBREW_DOCKER_REGISTRY_BASIC_AUTH_TOKEN`.
 
+`HOMEBREW_DOWNLOAD_CONCURRENCY`
+
+: If set, Homebrew will download in parallel using this many concurrent
+  connections. Setting to `auto` will use twice the number of available CPU
+  cores (what our benchmarks showed to produce the best performance). If set to
+  `1` (the default), Homebrew will download in serial.
+  
+  *Default:* `1`.
+
 `HOMEBREW_EDITOR`
 
 : Use this editor when editing a single formula, or several formulae in the same
diff --git a/manpages/brew.1 b/manpages/brew.1
index 5981153260..6f0150f886 100644
--- a/manpages/brew.1
+++ b/manpages/brew.1
@@ -2617,6 +2617,13 @@ Use this base64 encoded username and password for authenticating with a Docker r
 \fBHOMEBREW_DOCKER_REGISTRY_TOKEN\fP
 Use this bearer token for authenticating with a Docker registry proxying GitHub Packages\. Preferred over \fB$HOMEBREW_DOCKER_REGISTRY_BASIC_AUTH_TOKEN\fP\&\.
 .TP
+\fBHOMEBREW_DOWNLOAD_CONCURRENCY\fP
+If set, Homebrew will download in parallel using this many concurrent connections\. Setting to \fBauto\fP will use twice the number of available CPU cores (what our benchmarks showed to produce the best performance)\. If set to \fB1\fP (the default), Homebrew will download in serial\.
+.RS
+.P
+\fIDefault:\fP \fB1\fP\&\.
+.RE
+.TP
 \fBHOMEBREW_EDITOR\fP
 Use this editor when editing a single formula, or several formulae in the same directory\.
 .RS