Merge pull request #1889 from contour-terminal/feature/env-var-expansion-config-paths

Add environment variable expansion in configuration file paths (#1278)

Author: christianparpart

docs/configuration/colors.md

@@ -36,7 +36,7 @@ color_schemes:
       blur: false
 
 ```
-:octicons-horizontal-rule-16: ==path== To specify the image file to use as the background, you need to provide the full path to the image. By default, the path option is set to an empty string, indicating that background image support is disabled. <br/>
+:octicons-horizontal-rule-16: ==path== To specify the image file to use as the background, you need to provide the full path to the image. Both `~` (home directory) and `${VAR}` (environment variable) expansion are supported — see [Path Handling](paths.md) for details. By default, the path option is set to an empty string, indicating that background image support is disabled. <br/>
 :octicons-horizontal-rule-16: ==opacity== option controls the opacity of the background image. It determines how transparent or intense the image appears. The default value is 0.5, which provides a moderately transparent background. You can adjust this value to make the image more or less prominent, depending on your preferences. <br/>
 :octicons-horizontal-rule-16: ==blur== option applies a blur effect to the background image. This can help reduce distractions and keep the focus on the terminal contents. By default, the blur option is set to false, indicating that background image blurring is disabled. If you want to enable it, set the value to true.
 

docs/configuration/paths.md

@@ -0,0 +1,88 @@
+# Path Handling in Configuration
+
+Contour supports special syntax in configuration file paths to make configs portable across machines and platforms.
+
+## Tilde Expansion
+
+Use `~` at the start of a path to refer to the user's home directory:
+
+``` yaml
+profiles:
+  main:
+    shell:
+      initial_working_directory: ~/workspace
+```
+
+On Linux/macOS this expands to e.g. `/home/user/workspace`, on Windows to `C:\Users\user\workspace`.
+
+## Environment Variable Expansion
+
+Use `${VAR_NAME}` to reference environment variables:
+
+``` yaml
+color_schemes:
+  default:
+    background_image:
+      path: '${HOME}/Pictures/terminal-bg.png'
+```
+
+This resolves `${HOME}` to its value at config load time.
+
+### Multiple Variables
+
+You can use several variables in the same value:
+
+``` yaml
+profiles:
+  main:
+    shell:
+      program: '${MY_SHELL_DIR}/${MY_SHELL_NAME}'
+```
+
+### Combining with Tilde
+
+Environment variables are expanded **before** tilde resolution, so both syntaxes compose correctly:
+
+``` yaml
+profiles:
+  main:
+    shell:
+      initial_working_directory: '~/${PROJECT_DIR}'
+```
+
+This first resolves `${PROJECT_DIR}` (e.g. to `workspace`), then resolves `~` to the home directory, yielding `/home/user/workspace`.
+
+## Where Expansion Applies
+
+The following configuration values support both `~` and `${VAR}` expansion:
+
+| Configuration value | Example |
+|---------------------|---------|
+| `background_image.path` | `'${HOME}/Pictures/bg.png'` |
+| `shell.program` | `'${MY_SHELL}'` |
+| `shell.arguments` (each entry) | `'--config=${XDG_CONFIG_HOME}/shell.conf'` |
+| `shell.initial_working_directory` | `'~/${PROJECT_DIR}'` |
+| Any `std::filesystem::path` config entry | General file path values |
+
+## Cross-Platform Configuration
+
+A primary motivation for environment variable expansion is writing configs that work on multiple operating systems without modification:
+
+``` yaml
+# Works on both Linux and Windows — no hardcoded paths
+color_schemes:
+  default:
+    background_image:
+      path: '${HOME}/Pictures/terminal-bg.png'
+
+profiles:
+  main:
+    shell:
+      initial_working_directory: '${HOME}/projects'
+```
+
+## Edge Cases
+
+- **Undefined variables** expand to an empty string and a warning is logged.
+- **Malformed markers** like `${UNCLOSED` (missing closing `}`) pass through the string unchanged — no partial substitution occurs.
+- **No markers** — strings without any `${...}` syntax are passed through unchanged.

metainfo.xml

@@ -144,6 +144,7 @@
           <li>Adds natural momentum scrolling for touchpad gestures with configurable falloff via momentum_scrolling profile setting</li>
           <li>Adds Kitty OSC 99 desktop notification protocol with D-Bus backend on Linux, supporting structured metadata, chunked payloads, base64 encoding, urgency levels, display occasion filtering, bidirectional close/activation events, and query/alive responses</li>
           <li>Adds complete DECCIR (Cursor Information Report) response including character set designations, GL/GR mappings, and wrap-pending state (#97)</li>
+          <li>Adds environment variable expansion (${VAR_NAME} syntax) in configuration file paths for cross-platform config reuse (#1278)</li>
         </ul>
       </description>
     </release>

mkdocs.yml

@@ -92,6 +92,7 @@ nav:
     - configuration/profiles.md
     - configuration/colors.md
     - configuration/indicator-statusline.md
+    - configuration/paths.md
     - configuration/key-mapping.md
     #- Images (Advanced) : configuration/advanced/images.md
     #- Mouse (Advanced) : configuration/advanced/images.md

src/contour/Config.cpp

@@ -17,6 +17,7 @@
 #include <QtGui/QOpenGLContext>
 
 #include <algorithm>
+#include <cstdlib>
 #include <fstream>
 #include <iostream>
 
@@ -304,6 +305,40 @@ optional<std::string> readConfigFile(std::string const& filename)
     return nullopt;
 }
 
+YAMLConfigReader::YAMLConfigReader(std::string const& filename,
+                                   logstore::category const& log,
+                                   VariableReplacer replacer):
+    configFile(filename), logger { log }, variableReplacer { std::move(replacer) }
+{
+    if (!variableReplacer)
+    {
+        variableReplacer = [&log = logger](std::string_view name) -> std::string {
+            if (auto const* value = std::getenv(std::string(name).c_str()))
+                return value;
+            log()("Undefined environment variable: ${{{}}}", name);
+            return {};
+        };
+    }
+    try
+    {
+        doc = YAML::LoadFile(configFile.string());
+    }
+    catch (std::exception const& e)
+    {
+        errorLog()("Configuration file is corrupted. {}\nDefault config will be loaded.", e.what());
+    }
+}
+
+std::string YAMLConfigReader::resolveVariables(std::string const& input) const
+{
+    return replaceVariables(input, variableReplacer);
+}
+
+std::filesystem::path YAMLConfigReader::resolvedPath(std::string const& input) const
+{
+    return homeResolvedPath(resolveVariables(input), vtpty::Process::homeDirectory());
+}
+
 // NOLINTBEGIN(readability-convert-member-functions-to-static)
 void YAMLConfigReader::loadFromEntry(YAML::Node const& node,
                                      std::string const& entry,
@@ -312,8 +347,7 @@ void YAMLConfigReader::loadFromEntry(YAML::Node const& node,
     auto const child = node[entry];
     if (child)
     {
-        where = crispy::homeResolvedPath(std::filesystem::path(child.as<std::string>()).string(),
-                                         vtpty::Process::homeDirectory());
+        where = resolvedPath(child.as<std::string>());
     }
 }
 
@@ -733,9 +767,9 @@ void YAMLConfigReader::loadFromEntry(YAML::Node const& node,
         loadFromEntry(child, "path", filename);
         loadFromEntry(child, "opacity", where->opacity);
         loadFromEntry(child, "blur", where->blur);
-        auto resolvedPath = crispy::homeResolvedPath(filename, vtpty::Process::homeDirectory());
-        where->location = resolvedPath;
-        where->hash = crispy::strong_hash::compute(resolvedPath.string());
+        auto const resolved = resolvedPath(filename);
+        where->location = resolved;
+        where->hash = crispy::strong_hash::compute(resolved.string());
     }
 }
 
@@ -856,13 +890,13 @@ void YAMLConfigReader::loadFromEntry(YAML::Node const& node,
 {
     if (auto const child = node[entry])
     {
-        where.program = child.as<std::string>();
+        where.program = resolveVariables(child.as<std::string>());
     }
     // loading arguments from the profile
     if (auto args = node["arguments"]; args && args.IsSequence())
     {
         for (auto const& argNode: args)
-            where.arguments.emplace_back(argNode.as<string>());
+            where.arguments.emplace_back(resolveVariables(argNode.as<string>()));
     }
     if (node["initial_working_directory"])
     {

src/contour/Config.h

@@ -47,6 +47,7 @@
 #include <exception>
 #include <filesystem>
 #include <format>
+#include <functional>
 #include <limits>
 #include <memory>
 #include <optional>
@@ -856,22 +857,23 @@ struct Config
 
 struct YAMLConfigReader
 {
+    /// Callable that resolves a variable name to its value.
+    using VariableReplacer = std::function<std::string(std::string_view)>;
+
     std::filesystem::path configFile;
     YAML::Node doc;
     logstore::category const& logger;
+    VariableReplacer variableReplacer;
 
-    YAMLConfigReader(std::string const& filename, logstore::category const& log):
-        configFile(filename), logger { log }
-    {
-        try
-        {
-            doc = YAML::LoadFile(configFile.string());
-        }
-        catch (std::exception const& e)
-        {
-            errorLog()("Configuration file is corrupted. {}\nDefault config will be loaded.", e.what());
-        }
-    }
+    YAMLConfigReader(std::string const& filename,
+                     logstore::category const& log,
+                     VariableReplacer replacer = {});
+
+    /// Expands `${VAR}` tokens in @p input using the configured variable replacer.
+    [[nodiscard]] std::string resolveVariables(std::string const& input) const;
+
+    /// Expands `${VAR}` tokens then resolves `~` to the home directory.
+    [[nodiscard]] std::filesystem::path resolvedPath(std::string const& input) const;
 
     template <typename T, documentation::StringLiteral ConfigDoc, documentation::StringLiteral WebDoc>
     void loadFromEntry(YAML::Node const& node,

src/crispy/utils_test.cpp

@@ -144,6 +144,57 @@ TEST_CASE("homeResolvedPath")
     CHECK("/var/tmp/workspace" == crispy::homeResolvedPath("~/workspace", "/var/tmp").generic_string());
 }
 
+TEST_CASE("expandEnvironmentVariables")
+{
+    auto const envReplacer = [](string_view name) -> string {
+        if (name == "HOME")
+            return "/home/user";
+        if (name == "SHELL")
+            return "/bin/bash";
+        return {};
+    };
+
+    // Known variables resolve correctly
+    CHECK("/home/user/Pictures" == crispy::replaceVariables("${HOME}/Pictures", envReplacer));
+    CHECK("/bin/bash" == crispy::replaceVariables("${SHELL}", envReplacer));
+
+    // Multiple variables in one string
+    CHECK("/home/user runs /bin/bash" == crispy::replaceVariables("${HOME} runs ${SHELL}", envReplacer));
+
+    // Unknown variables expand to empty string
+    CHECK("/Pictures" == crispy::replaceVariables("${UNDEFINED}/Pictures", envReplacer));
+
+    // No markers at all — input passes through unchanged
+    CHECK("/usr/local/bin" == crispy::replaceVariables("/usr/local/bin", envReplacer));
+
+    // Malformed ${UNCLOSED at start of string passes through unchanged
+    CHECK("${UNCLOSED" == crispy::replaceVariables("${UNCLOSED", envReplacer));
+}
+
+TEST_CASE("replaceVariables.and.homeResolvedPath.composition")
+{
+    auto const envReplacer = [](string_view name) -> string {
+        if (name == "HOME")
+            return "/home/user";
+        if (name == "PICS")
+            return "Pictures";
+        return {};
+    };
+
+    auto const resolve = [&](string const& input) {
+        return crispy::homeResolvedPath(crispy::replaceVariables(input, envReplacer), "/home/user");
+    };
+
+    // ${HOME}/path → env expansion → home resolution (no ~ involved)
+    CHECK("/home/user/Pictures/bg.png" == resolve("${HOME}/Pictures/bg.png").generic_string());
+
+    // ~/path → no env vars to expand → home resolution handles ~
+    CHECK("/home/user/workspace" == resolve("~/workspace").generic_string());
+
+    // Mixed: env var inside path with ~
+    CHECK("/home/user/Pictures" == resolve("~/${PICS}").generic_string());
+}
+
 TEST_CASE("unescapeURL")
 {
     CHECK(crispy::unescapeURL(""sv).empty());