From 76362bf81dff289f47cd0c9c102622150ccce129 Mon Sep 17 00:00:00 2001
From: Casey Rodarmor <casey@rodarmor.com>
Date: Fri, 20 Dec 2024 11:19:02 -0800
Subject: [PATCH 1/2] Update readme to reflect actual behavior of user
 directory functions (#2535)

---
 README.md | 22 ++++++++++++++++------
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 027e556718..74e3d50918 100644
--- a/README.md
+++ b/README.md
@@ -1903,14 +1903,20 @@ for details.
     @echo '{{ style("error") }}OH NO{{ NORMAL }}'
   ```
 
-##### XDG Directories<sup>1.23.0</sup>
+##### User Directories<sup>1.23.0</sup>
 
 These functions return paths to user-specific directories for things like
-configuration, data, caches, executables, and the user's home directory. These
-functions follow the
-[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html),
-and are implemented with the
-[`dirs`](https://docs.rs/dirs/latest/dirs/index.html) crate.
+configuration, data, caches, executables, and the user's home directory.
+
+On Unix, these functions follow the
+[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).
+
+On MacOS and Windows, these functions return the system-specified user-specific
+directories. For example, `cache_directory()` returns `~/Library/Caches` on
+MacOS and `{FOLDERID_LocalAppData}` on Windows.
+
+See the [`dirs`](https://docs.rs/dirs/latest/dirs/index.html) crate for more
+details.
 
 - `cache_directory()` - The user-specific cache directory.
 - `config_directory()` - The user-specific configuration directory.
@@ -1920,6 +1926,10 @@ and are implemented with the
 - `executable_directory()` - The user-specific executable directory.
 - `home_directory()` - The user's home directory.
 
+If you would like to use XDG base directories on all platforms you can use the
+`env(…)` function with the appropriate environment variable, e.g.,
+`env('XDG_CACHE_HOME')`.
+
 ### Constants
 
 A number of constants are predefined:

From 6a2edd9f92036a3fef25ae5bc494891d336377b9 Mon Sep 17 00:00:00 2001
From: Casey Rodarmor <casey@rodarmor.com>
Date: Sat, 21 Dec 2024 18:30:50 -0800
Subject: [PATCH 2/2] Document weird behavior of duplicate definitions in
 imports (#2541)

---
 README.md | 36 +++++++++++++++++++++++++++++++++---
 1 file changed, 33 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 74e3d50918..837c64e44e 100644
--- a/README.md
+++ b/README.md
@@ -3492,9 +3492,39 @@ and recipes defined after the `import` statement.
 Imported files can themselves contain `import`s, which are processed
 recursively.
 
-When `allow-duplicate-recipes` is set, recipes in parent modules override
-recipes in imports. In a similar manner, when `allow-duplicate-variables` is
-set, variables in parent modules override variables in imports.
+`allow-duplicate-recipes` and `allow-duplicate-variables` allow duplicate
+recipes and variables, respectively, to override each other, instead of
+producing an error.
+
+Within a module, later definitions override earlier definitions:
+
+```just
+set allow-duplicate-recipes
+
+foo:
+
+foo:
+  echo 'yes'
+```
+
+When `import`s are involved, things unfortunately get much more complicated and
+hard to explain.
+
+Shallower definitions always override deeper definitions, so recipes at the top
+level will override recipes in imports, and recipes in an import will override
+recipes in an import which itself imports those recipes.
+
+When two duplicate definitions are imported and are at the same depth, the one
+from the earlier import will override the one from the later import.
+
+This is because `just` uses a stack when processing imports, pushing imports
+onto the stack in source-order, and always processing the top of the stack
+next, so earlier imports are actually handled later by the compiler.
+
+This is definitely a bug, but since `just` has very strong backwards
+compatibility guarantees and we take enormous pains not to break anyone's
+`justfile`, we have created issue #2540 to discuss whether or not we can
+actually fix it.
 
 Imports may be made optional by putting a `?` after the `import` keyword: