From c7592b747b332eded1a1728e87abbc6e66b934f4 Mon Sep 17 00:00:00 2001
From: polykernel <81340136+polykernel@users.noreply.github.com>
Date: Wed, 8 Dec 2021 22:02:00 -0500
Subject: [PATCH] treewide: prefer XDG variables over dot directories

Currently, dot directories and XDG base directories are used
inconsistently in the Home Manager option declarations. This creates
ambiguity for the user as to where the location of the file should be
albeit this is rarely encountered in practice as it is sufficient to
read upstream documentation. The rationale is to make declarations
consistent and make a clear distinction between hardcoded and modular
specifications.

References to ~/.config in relevant nixpkgs modules were untouched as
the location is hardcoded upstream[1]. Furthermore, modules of
programs which do not follow XDG specifications were also untouched.

Generalization of tilde(~) expansions to $HOME were also considered,
however there isn't sufficient rationale despite the use of $HOME
being more universal. The expansion is standardized in POSIX[2] and is
essentially portable across all shells, thus there is no pragmatic
value to introducing the change.

[1] https://github.com/nixos/nixpkgs/blob/master/pkgs/top-level/impure.nix
[2] https://pubs.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_06_01
---
 docs/man-home-manager.xml      | 4 ++--
 modules/misc/gtk.nix           | 4 ++--
 modules/programs/alacritty.nix | 2 +-
 modules/programs/atuin.nix     | 2 +-
 modules/programs/beets.nix     | 2 +-
 modules/programs/direnv.nix    | 4 ++--
 modules/programs/hexchat.nix   | 4 ++--
 modules/programs/htop.nix      | 2 +-
 modules/programs/kakoune.nix   | 2 +-
 modules/programs/kitty.nix     | 2 +-
 modules/programs/lazygit.nix   | 2 +-
 modules/programs/lsd.nix       | 2 +-
 modules/programs/mangohud.nix  | 4 ++--
 modules/programs/mpv.nix       | 6 +++---
 modules/programs/ncspot.nix    | 2 +-
 modules/programs/noti.nix      | 2 +-
 modules/programs/nushell.nix   | 2 +-
 modules/programs/rtorrent.nix  | 2 +-
 modules/programs/sm64ex.nix    | 2 +-
 modules/programs/starship.nix  | 2 +-
 modules/programs/topgrade.nix  | 2 +-
 modules/services/grobi.nix     | 4 ++--
 22 files changed, 30 insertions(+), 30 deletions(-)

diff --git a/docs/man-home-manager.xml b/docs/man-home-manager.xml
index 9f5374503..5a4f2d5d0 100644
--- a/docs/man-home-manager.xml
+++ b/docs/man-home-manager.xml
@@ -414,7 +414,7 @@
     <listitem>
      <para>
       Indicates the path to the Home Manager configuration file. If not given,
-      <filename>~/.config/nixpkgs/home.nix</filename> is used.
+      <filename>$XDG_CONFIG_HOME/nixpkgs/home.nix</filename> is used.
      </para>
     </listitem>
    </varlistentry>
@@ -589,7 +589,7 @@
   <variablelist>
    <varlistentry>
     <term>
-     <filename>~/.local/share/home-manager/news-read-ids</filename>
+     <filename>$XDG_DATA_HOME/home-manager/news-read-ids</filename>
     </term>
     <listitem>
      <para>
diff --git a/modules/misc/gtk.nix b/modules/misc/gtk.nix
index 669329b7b..0b5a54d5f 100644
--- a/modules/misc/gtk.nix
+++ b/modules/misc/gtk.nix
@@ -123,7 +123,7 @@ in {
           };
           description = ''
             Extra configuration options to add to
-            <filename>~/.config/gtk-3.0/settings.ini</filename>.
+            <filename>$XDG_CONFIG_HOME/gtk-3.0/settings.ini</filename>.
           '';
         };
 
@@ -132,7 +132,7 @@ in {
           default = "";
           description = ''
             Extra configuration lines to add verbatim to
-            <filename>~/.config/gtk-3.0/gtk.css</filename>.
+            <filename>$XDG_CONFIG_HOME/gtk-3.0/gtk.css</filename>.
           '';
         };
       };
diff --git a/modules/programs/alacritty.nix b/modules/programs/alacritty.nix
index d34efb775..c82d9c979 100644
--- a/modules/programs/alacritty.nix
+++ b/modules/programs/alacritty.nix
@@ -37,7 +37,7 @@ in {
         '';
         description = ''
           Configuration written to
-          <filename>~/.config/alacritty/alacritty.yml</filename>. See
+          <filename>$XDG_CONFIG_HOME/alacritty/alacritty.yml</filename>. See
           <link xlink:href="https://github.com/jwilm/alacritty/blob/master/alacritty.yml"/>
           for the default configuration.
         '';
diff --git a/modules/programs/atuin.nix b/modules/programs/atuin.nix
index dcf1232f8..0e5fa071d 100644
--- a/modules/programs/atuin.nix
+++ b/modules/programs/atuin.nix
@@ -60,7 +60,7 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>~/.config/atuin/config.toml</filename>.
+        <filename>$XDG_CONFIG_HOME/atuin/config.toml</filename>.
         </para><para>
         See <link xlink:href="https://github.com/ellie/atuin/blob/main/docs/config.md" /> for the full list
         of options.
diff --git a/modules/programs/beets.nix b/modules/programs/beets.nix
index a0b8a346b..fa959669c 100644
--- a/modules/programs/beets.nix
+++ b/modules/programs/beets.nix
@@ -45,7 +45,7 @@ in {
         default = { };
         description = ''
           Configuration written to
-          <filename>~/.config/beets/config.yaml</filename>
+          <filename>$XDG_CONFIG_HOME/beets/config.yaml</filename>
         '';
       };
     };
diff --git a/modules/programs/direnv.nix b/modules/programs/direnv.nix
index ad4c49934..5220aaa10 100644
--- a/modules/programs/direnv.nix
+++ b/modules/programs/direnv.nix
@@ -29,7 +29,7 @@ in {
       default = { };
       description = ''
         Configuration written to
-        <filename>~/.config/direnv/config.toml</filename>.
+        <filename>$XDG_CONFIG_HOME/direnv/config.toml</filename>.
         </para><para>
         See
         <citerefentry>
@@ -45,7 +45,7 @@ in {
       default = "";
       description = ''
         Custom stdlib written to
-        <filename>~/.config/direnv/direnvrc</filename>.
+        <filename>$XDG_CONFIG_HOME/direnv/direnvrc</filename>.
       '';
     };
 
diff --git a/modules/programs/hexchat.nix b/modules/programs/hexchat.nix
index b0836758f..5971bba6e 100644
--- a/modules/programs/hexchat.nix
+++ b/modules/programs/hexchat.nix
@@ -270,7 +270,7 @@ in {
           };
         }'';
       description = ''
-        Configures <filename>~/.config/hexchat/servlist.conf</filename>.
+        Configures <filename>$XDG_CONFIG_HOME/hexchat/servlist.conf</filename>.
       '';
     };
 
@@ -286,7 +286,7 @@ in {
         };
       '';
       description = ''
-        Configuration for <filename>~/.config/hexchat/hexchat.conf</filename>, see
+        Configuration for <filename>$XDG_CONFIG_HOME/hexchat/hexchat.conf</filename>, see
         <link xlink:href="https://hexchat.readthedocs.io/en/latest/settings.html#list-of-settings"/>
         for supported values.
       '';
diff --git a/modules/programs/htop.nix b/modules/programs/htop.nix
index 1506aab5b..1c8a59312 100644
--- a/modules/programs/htop.nix
+++ b/modules/programs/htop.nix
@@ -133,7 +133,7 @@ in {
       '';
       description = ''
         Configuration options to add to
-        <filename>~/.config/htop/htoprc</filename>.
+        <filename>$XDG_CONFIG_HOME/htop/htoprc</filename>.
       '';
     };
 
diff --git a/modules/programs/kakoune.nix b/modules/programs/kakoune.nix
index 49f259d01..d177048b9 100644
--- a/modules/programs/kakoune.nix
+++ b/modules/programs/kakoune.nix
@@ -635,7 +635,7 @@ in {
         default = "";
         description = ''
           Extra configuration lines to add to
-          <filename>~/.config/kak/kakrc</filename>.
+          <filename>$XDG_CONFIG_HOME/kak/kakrc</filename>.
         '';
       };
 
diff --git a/modules/programs/kitty.nix b/modules/programs/kitty.nix
index 6d3d4d00d..2eefa8ab7 100644
--- a/modules/programs/kitty.nix
+++ b/modules/programs/kitty.nix
@@ -57,7 +57,7 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>~/.config/kitty/kitty.conf</filename>. See
+        <filename>$XDG_CONFIG_HOME/kitty/kitty.conf</filename>. See
         <link xlink:href="https://sw.kovidgoyal.net/kitty/conf.html" />
         for the documentation.
       '';
diff --git a/modules/programs/lazygit.nix b/modules/programs/lazygit.nix
index f2d516200..87bcdecce 100644
--- a/modules/programs/lazygit.nix
+++ b/modules/programs/lazygit.nix
@@ -32,7 +32,7 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>~/.config/lazygit/config.yml</filename> on Linux
+        <filename>$XDG_CONFIG_HOME/lazygit/config.yml</filename> on Linux
         or <filename>~/Library/Application Support/lazygit/config.yml</filename> on Darwin. See
         <link xlink:href="https://github.com/jesseduffield/lazygit/blob/master/docs/Config.md"/>
         for supported values.
diff --git a/modules/programs/lsd.nix b/modules/programs/lsd.nix
index b5dd260e0..0b54abe3d 100644
--- a/modules/programs/lsd.nix
+++ b/modules/programs/lsd.nix
@@ -39,7 +39,7 @@ in {
       };
       description = ''
         Configuration written to
-        <filename>~/.config/lsd/config.yaml</filename>. See
+        <filename>$XDG_CONFIG_HOME/lsd/config.yaml</filename>. See
         <link xlink:href="https://github.com/Peltoche/lsd#config-file-content"/>
         for supported values.
       '';
diff --git a/modules/programs/mangohud.nix b/modules/programs/mangohud.nix
index 0f14a8c63..ca77c07c6 100644
--- a/modules/programs/mangohud.nix
+++ b/modules/programs/mangohud.nix
@@ -55,7 +55,7 @@ in {
         '';
         description = ''
           Configuration written to
-          <filename>~/.config/MangoHud/MangoHud.conf</filename>. See
+          <filename>$XDG_CONFIG_HOME/MangoHud/MangoHud.conf</filename>. See
           <link xlink:href="https://github.com/flightlessmango/MangoHud/blob/master/bin/MangoHud.conf"/>
           for the default configuration.
         '';
@@ -74,7 +74,7 @@ in {
         description = ''
           Sets MangoHud settings per application.
           Configuration written to
-          <filename>~/.config/MangoHud/{application_name}.conf</filename>. See
+          <filename>$XDG_CONFIG_HOME/MangoHud/{application_name}.conf</filename>. See
           <link xlink:href="https://github.com/flightlessmango/MangoHud/blob/master/bin/MangoHud.conf"/>
           for the default configuration.
         '';
diff --git a/modules/programs/mpv.nix b/modules/programs/mpv.nix
index a53f4c40d..b37a2516a 100644
--- a/modules/programs/mpv.nix
+++ b/modules/programs/mpv.nix
@@ -90,7 +90,7 @@ in {
       config = mkOption {
         description = ''
           Configuration written to
-          <filename>~/.config/mpv/mpv.conf</filename>. See
+          <filename>$XDG_CONFIG_HOME/mpv/mpv.conf</filename>. See
           <citerefentry>
             <refentrytitle>mpv</refentrytitle>
             <manvolnum>1</manvolnum>
@@ -112,7 +112,7 @@ in {
       profiles = mkOption {
         description = ''
           Sub-configuration options for specific profiles written to
-          <filename>~/.config/mpv/mpv.conf</filename>. See
+          <filename>$XDG_CONFIG_HOME/mpv/mpv.conf</filename>. See
           <option>programs.mpv.config</option> for more information.
         '';
         type = mpvProfiles;
@@ -143,7 +143,7 @@ in {
       bindings = mkOption {
         description = ''
           Input configuration written to
-          <filename>~/.config/mpv/input.conf</filename>. See
+          <filename>$XDG_CONFIG_HOME/mpv/input.conf</filename>. See
           <citerefentry>
             <refentrytitle>mpv</refentrytitle>
             <manvolnum>1</manvolnum>
diff --git a/modules/programs/ncspot.nix b/modules/programs/ncspot.nix
index 7acb8d364..3b6d401e6 100644
--- a/modules/programs/ncspot.nix
+++ b/modules/programs/ncspot.nix
@@ -32,7 +32,7 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>~/.config/ncspot/config.toml</filename>.
+        <filename>$XDG_CONFIG_HOME/ncspot/config.toml</filename>.
         </para><para>
         See <link xlink:href="https://github.com/hrkfdn/ncspot#configuration" />
         for the full list of options.
diff --git a/modules/programs/noti.nix b/modules/programs/noti.nix
index 069d87e64..d8affdd53 100644
--- a/modules/programs/noti.nix
+++ b/modules/programs/noti.nix
@@ -17,7 +17,7 @@ in {
       default = { };
       description = ''
         Configuration written to
-        <filename>~/.config/noti/noti.yaml</filename>.
+        <filename>$XDG_CONFIG_HOME/noti/noti.yaml</filename>.
         </para><para>
         See
         <citerefentry>
diff --git a/modules/programs/nushell.nix b/modules/programs/nushell.nix
index f37b889a1..4d6ab43a7 100644
--- a/modules/programs/nushell.nix
+++ b/modules/programs/nushell.nix
@@ -42,7 +42,7 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>~/.config/nushell/config.toml</filename>.
+        <filename>$XDG_CONFIG_HOME/nushell/config.toml</filename>.
         </para><para>
         See <link xlink:href="https://www.nushell.sh/book/configuration.html" /> for the full list
         of options.
diff --git a/modules/programs/rtorrent.nix b/modules/programs/rtorrent.nix
index 7beeb2e42..95015e2cb 100644
--- a/modules/programs/rtorrent.nix
+++ b/modules/programs/rtorrent.nix
@@ -17,7 +17,7 @@ in {
       default = "";
       description = ''
         Configuration written to
-        <filename>~/.config/rtorrent/rtorrent.rc</filename>. See
+        <filename>$XDG_CONFIG_HOME/rtorrent/rtorrent.rc</filename>. See
         <link xlink:href="https://github.com/rakshasa/rtorrent/wiki/Config-Guide" />
         for explanation about possible values.
       '';
diff --git a/modules/programs/sm64ex.nix b/modules/programs/sm64ex.nix
index a5debee18..48c1cb9be 100644
--- a/modules/programs/sm64ex.nix
+++ b/modules/programs/sm64ex.nix
@@ -80,7 +80,7 @@ in {
         nullOr (attrsOf (either str (either int (either bool (listOf str)))));
       default = null;
       description =
-        "Settings for sm64ex's <filename>~/.local/share/sm64pc/sm64config.txt</filename> file.";
+        "Settings for sm64ex's <filename>$XDG_DATA_HOME/sm64pc/sm64config.txt</filename> file.";
       example = literalExpression ''
         {
           fullscreen = false;
diff --git a/modules/programs/starship.nix b/modules/programs/starship.nix
index 77a9cad31..85b414130 100644
--- a/modules/programs/starship.nix
+++ b/modules/programs/starship.nix
@@ -51,7 +51,7 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>~/.config/starship.toml</filename>.
+        <filename>$XDG_CONFIG_HOME/starship.toml</filename>.
         </para><para>
         See <link xlink:href="https://starship.rs/config/" /> for the full list
         of options.
diff --git a/modules/programs/topgrade.nix b/modules/programs/topgrade.nix
index 1511d4b45..ac88643d0 100644
--- a/modules/programs/topgrade.nix
+++ b/modules/programs/topgrade.nix
@@ -42,7 +42,7 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>~/.config/topgrade.toml</filename>.
+        <filename>$XDG_CONFIG_HOME/topgrade.toml</filename>.
         </para><para>
         See <link xlink:href="https://github.com/r-darwish/topgrade/wiki/Step-list" /> for the full list
         of options.
diff --git a/modules/services/grobi.nix b/modules/services/grobi.nix
index 2f6431099..d90b7244a 100644
--- a/modules/services/grobi.nix
+++ b/modules/services/grobi.nix
@@ -24,7 +24,7 @@ in {
           Commands to be run after an output configuration was
           changed. The Nix value declared here will be translated to
           JSON and written to the <option>execute_after</option> key
-          in <filename>~/.config/grobi.conf</filename>.
+          in <filename>$XDG_CONFIG_HOME/grobi.conf</filename>.
         '';
       };
 
@@ -64,7 +64,7 @@ in {
           <link xlink:href="https://github.com/fd0/grobi/blob/master/doc/grobi.conf"/>
           for more information. The Nix value declared here will be
           translated to JSON and written to the <option>rules</option>
-          key in <filename>~/.config/grobi.conf</filename>.
+          key in <filename>$XDG_CONFIG_HOME/grobi.conf</filename>.
         '';
       };
     };