userctx/config_reimagined.toml

[general]
# if dry run is set to true
# userctx will only validate config 
# and tell you what it will do to execute
# tasks
dry_run = true

# "apps" array tells userctx what to do (which apps
# should be actually managed). If it is empty or not
# set, then userctx will do nothing.
apps = [
  "sway",
  "gtk",
  "helix",
  "foot",
  "wofi",
  "mako",
]

# target directory where managed configs
# are located 
# defaults to $XDG_CONFIG_HOME if specifically set
# or ~/.config if $XGD_CONFIG_HOME is not set
target_path = "~/.config"

# directory where contexts are stored
# default is "~/.config/userctx"
source_path = "~/.config/userctx" 

[apps]
helix.symlink."*" = "themes/theme.toml"
helix.exec = "pkill -USR1 hx"

example2.scripts = ["s1", "s2"]

[apps.example]
symlink."this.file" = "that.file"
symlink."*" = "theme.conf" # TODO: handle any file to particular name
exec = 'echo "this simulates reload command"'

[apps.niri]
exec = "this simulates code for niri restart"

[apps.niri.symlink]
"another.file" = "another.link"

# section that demonstrates all the available
# features of userctx
[apps.example]
# Path to appliaction configs is read from
# general.soucre_path. The default source path is 
# ~/.config/userctx/<context_name>/example for this
# app. 
# Individual path for app can be provided via
# "source_path" for particular app. Then userctx will try to lookup
# app settings in /source_path/<context_name>
# Default is general.source_path/<context_name>/<app_name>.
# For this example it will expand to
# ~/.config/userctx/<context_name/example.
# TODO: do we really need this? 
source_path = "~/tmp/contexts"

# The default path to apply your context to is
# ~/.config/example (for app name "example")
# if not overridden with general.target_path.
# Setting "target_path" overrides this.
# $CONTEXT_DST env will hold  the actual destination path.
# symlinks will be created relative to this specified 
# path.
target_path = "~/.config/example/configs"

# "symlink" map defines
# which files will be symlinked to users home
# directory.
# Names of files in thes mapping are relative to 
# context directory and target directory
# by default source is ~/.config/userctx/<context_name>/example 
# and target directory is ~/.config/example
# for app named "example" 
#
# this will link file from context dir to destination dir
# $CONTEXT_SRC/context_file.conf -> $CONTEXT_DST/symlink_to_context_file.conf
symlink."context_file.conf" = "symlink_to_context_file.conf"

# this will link file to subdirectory inside destination dir
# Note that destination subdir must be created beforehand.
# $CONTEXT_SRC/other_file.conf -> $CONTEXT_DST/subdir/other_file.conf
symlink."other_file.conf" = "subdir/other_file.conf"
symlink."subdir/yet_another_file.conf" = "yet_another_file.conf" 


# "exec" let's you write a reload command or
# even a bigger custom script that will apply contents of
# your context. Note the triple double-qoutes for multiline
# strings (see TOML spec). 
# This string will be passed as is to $SHELL for execution.
exec = """
  # this is a normal shell script which will
  # be executed by user's $SHELL or 'bash' binary
  # if users $SHELL is empty

  # users envs are available
  echo "$HOME" 

  # additional envs are available 
  echo "$CONTEXT_SRC"
  echo "$CONTEXT_DST"
  echo "$CONTEXT_NAME"
"""

# scripts array will try to find
# named files in $CONTEXT_SRC and 
# execute them with $SHELL <script>
# IMPORTANT: if array is empty
# and action "scripts" is present in 
# "actions" array above then all files
# in $CONTEXT_SRC will be treated as scripts
# (note the "apps.gtk section below")
scripts = [
  "script1.sh",
  "script2.sh",
]

#########################
settings for some
commonly used apps
#########################

[apps.niri]
target_path = "~/.config/niri/configs"
actions = [
  "symlinks",
  "code",
]

# The snippet below is needed for niri 25.8 which did not
# support imports/includes in the config. I'm splitting
# config into several parts and them concatenating them 
# after applying changes to theme. The other parts are left intact.
# Also note the custom target path above. It instructs userctx to
# symlink configs found in the context dir to 
# ~/.config/niri/configs, which then get concatenated.
# For niri since 25.11 you can just put your includes
# into the context dir and omit [apps.niri] altogether.
exec = """
  cat ~/.config/niri/configs/* > ~/.config/niri/config.kdl
"""

[apps.helix]
actions = [
  "symlinks",
  "code",
]
# context must contain file named "helix.toml" which describes a theme.
  # $CONTEXT_SRC/helix.toml -> $CONTEXT_DST/themes/current_theme.toml
symlink."helix.toml" = "themes/current_theme.toml"

exec = """
  sed -i -E 's/^theme = (.+)/theme = "current_theme"/' ~/.config/helix/config.toml
  pkill -USR1 hx
"""

[apps.gtk]
# To setup the look of GTK you may put a simple shell script
# into ~/.userctx/<context_name>/gtk/theme.sh with contents similar to: 
# gsettings set org.gnome.desktop.interface color-scheme 'default'
# gsettings set org.gnome.desktop.interface gtk-theme 'Yaru'
# gsettings set org.gnome.desktop.interface icon-theme 'Yaru'
actions = ["scripts"]

[apps.mako]
exec = "makoctl reload"

[apps.sway]
exec = "swaymsg reload"

[apps.kitty]
exec = 'pkill -USR1 kitty'

[apps.waybar]
exec = 'pkill -USR2 waybar'

[apps.swaybg]
# This config is for swaybg setup as s systemd service.
# Unit runs "swaybg -m fill -i "%h/.config/swaybg/wallpaper".
# ~/.config/userctx/<context>/swaybg/ contains single file 
# called "wallpaper" which gets symlinked to ~/.config/swaybg/wallpaper
target_path = '~/.config/swaybg'
reload = ['systemctl', '--user', 'restart', 'swaybg.service']