From 29c3a52e964a97dddaed876ce472aeb167774acf Mon Sep 17 00:00:00 2001
From: Mitchell Hashimoto <m@mitchellh.com>
Date: Mon, 18 Nov 2024 15:14:12 -0800
Subject: [PATCH] config: clarify config-file behavior

No one has actually ever complained about this but I wanted to
explicitly call it out.
---
 src/config/Config.zig | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/src/config/Config.zig b/src/config/Config.zig
index a3ee8ccf0..6e569e795 100644
--- a/src/config/Config.zig
+++ b/src/config/Config.zig
@@ -1199,6 +1199,21 @@ keybind: Keybinds = .{},
 ///
 /// Cycles are not allowed. If a cycle is detected, an error will be logged and
 /// the configuration file will be ignored.
+///
+/// Configuration files are loaded after the configuration they're defined
+/// within in the order they're defined. **THIS IS A VERY SUBTLE BUT IMPORTANT
+/// POINT.** To put it another way: configuration files do not take effect
+/// until after the entire configuration is loaded. For example, in the
+/// configuration below:
+///
+/// ```
+/// config-file = "foo"
+/// a = 1
+/// ```
+///
+/// If "foo" contains `a = 2`, the final value of `a` will be 2, because
+/// `foo` is loaded after the configuration file that configures the
+/// nested `config-file` value.
 @"config-file": RepeatablePath = .{},
 
 /// When this is true, the default configuration file paths will be loaded.