From 5043e2d16f863993b32882608a6cf6bfde3b6a6f Mon Sep 17 00:00:00 2001
From: Ian Butterworth <i.r.butterworth@gmail.com>
Date: Wed, 16 Oct 2024 09:57:12 -0400
Subject: [PATCH] fix and test when JULIA_DEPOT_PATH has leading empty entry

---
 base/initdefs.jl                        | 11 +++++++----
 doc/src/manual/environment-variables.md | 26 ++++++++++++++++---------
 test/loading.jl                         |  2 +-
 3 files changed, 25 insertions(+), 14 deletions(-)

diff --git a/base/initdefs.jl b/base/initdefs.jl
index 707c96a2444d6..85b708433c0ef 100644
--- a/base/initdefs.jl
+++ b/base/initdefs.jl
@@ -112,20 +112,23 @@ function init_depot_path()
 
         # otherwise, populate the depot path with the entries in JULIA_DEPOT_PATH,
         # expanding empty strings to the bundled depot
-        populated = false
-        for path in eachsplit(str, Sys.iswindows() ? ';' : ':')
+        pushfirst_default = true
+        for (i, path) in enumerate(eachsplit(str, Sys.iswindows() ? ';' : ':'))
             if isempty(path)
                 append_bundled_depot_path!(DEPOT_PATH)
             else
                 path = expanduser(path)
                 path in DEPOT_PATH || push!(DEPOT_PATH, path)
-                populated = true
+                if i == 1
+                    # if a first entry is given, don't add the default depot at the start
+                    pushfirst_default = false
+                end
             end
         end
 
         # backwards compatibility: if JULIA_DEPOT_PATH only contains empty entries
         # (e.g., JULIA_DEPOT_PATH=':'), make sure to use the default depot
-        if !populated
+        if pushfirst_default
             pushfirst!(DEPOT_PATH, joinpath(homedir(), ".julia"))
         end
     else
diff --git a/doc/src/manual/environment-variables.md b/doc/src/manual/environment-variables.md
index b86822e0be4b7..5aa0701c9aafe 100644
--- a/doc/src/manual/environment-variables.md
+++ b/doc/src/manual/environment-variables.md
@@ -130,17 +130,19 @@ environment variable or if it must have a value, set it to the string `:`.
 
 ### [`JULIA_DEPOT_PATH`](@id JULIA_DEPOT_PATH)
 
-The [`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH) environment variable is used to populate the global Julia
-[`DEPOT_PATH`](@ref) variable, which controls where the package manager, as well
-as Julia's code loading mechanisms, look for package registries, installed
-packages, named environments, repo clones, cached compiled package images,
-configuration files, and the default location of the REPL's history file.
+The [`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH) environment variable is used to populate the
+global Julia [`DEPOT_PATH`](@ref) variable, which controls where the package manager, as well
+as Julia's code loading mechanisms, look for package registries, installed packages, named
+environments, repo clones, cached compiled package images, configuration files, and the default
+location of the REPL's history file.
 
 Unlike the shell `PATH` variable but similar to [`JULIA_LOAD_PATH`](@ref JULIA_LOAD_PATH),
-empty entries in [`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH) are expanded to the default
-value of `DEPOT_PATH`, excluding the user depot. This allows easy overriding of the user
-depot, while still retaining access to resources that are bundled with Julia, like cache
-files, artifacts, etc. For example, to switch the user depot to `/foo/bar` just do
+empty entries in [`JULIA_DEPOT_PATH`](@ref JULIA_DEPOT_PATH) have special behavior:
+- At the end, it is expanded to the default value of `DEPOT_PATH`, *excluding* the user depot.
+- At the start, it is expanded to the default value of `DEPOT_PATH`, *including* the user depot.
+This allows easy overriding of the user depot, while still retaining access to resources that
+are bundled with Julia, like cache files, artifacts, etc. For example, to switch the user depot
+to `/foo/bar` use a trailing `:`
 ```sh
 export JULIA_DEPOT_PATH="/foo/bar:"
 ```
@@ -150,6 +152,12 @@ resources will still be available. If you really only want to use the depot at `
 and not load any bundled resources, simply set the environment variable to `/foo/bar`
 without the trailing colon.
 
+To append a depot at the end of the full default list, including the default user depot, use a
+leading `:`
+```sh
+export JULIA_DEPOT_PATH=":/foo/bar"
+```
+
 There are two exceptions to the above rule. First, if [`JULIA_DEPOT_PATH`](@ref
 JULIA_DEPOT_PATH) is set to the empty string, it expands to an empty `DEPOT_PATH` array. In
 other words, the empty string is interpreted as a zero-element array, not a one-element
diff --git a/test/loading.jl b/test/loading.jl
index 4877b256a6ad9..9e7e40ff3b50a 100644
--- a/test/loading.jl
+++ b/test/loading.jl
@@ -731,7 +731,7 @@ end
         "" => [],
         "$s" => [default; bundled],
         "$tmp$s" => [tmp; bundled],
-        "$s$tmp" => [bundled; tmp],
+        "$s$tmp" => [default; bundled; tmp],
         )
     for (env, result) in pairs(cases)
         script = "DEPOT_PATH == $(repr(result)) || error(\"actual depot \" * join(DEPOT_PATH,':') * \" does not match expected depot \" * join($(repr(result)), ':'))"