userctx/README.md

userctx

Manage you configurations and themes with ease.

Installation

You just need to copy the file to a directory in your $PATH (for example: /usr/loca/bin) and copy/create a config file.

sudo install userctx.py /usr/local/bin/userctx
mkdir -p ~/.config/userctx
cp config.toml ~/.config/userctx

userctx basics

userctx manages configuration contexts. A context is a directory somewhere in your system which stores actual configuration files for your apps similar to what resides in ~/.config.

Typically a context directory looks like this.

/home/dmitry/.config/userctx/Goldfish
├── sway
│   └── theme.conf
└── wofi
    └── style.css

In the above example, context "Goldfish" contains configs for apps "sway" and "wofi". These configs will be applied when you apply context "Goldfish".

When a context is applied the app configs from context directory are get symlinked to youe ~/.config/ folder for each managed app. Goldfish/wofi/style.css symlinks to ~/.config/wofi/style.css, Goldfish/sway/theme.conf symlinks to ~/.config/sway/theme.conf etc.

This default behaviour can be changed and specific actions or customizations can be configured on per-app basis by editing userctx config file. The default location for the config is ~/.config/userctx/config.toml.

userctx can also be configured to run scripts, trigger your apps to reload configs etc. For a detailed overview of all config options see below.

There are two commands userctx understands: list and apply.

• list lists available contexts in a manner suitable for dmenu-like apps
• apply <context> applies named context

To test your configuration run:

userctx --nop apply <context_name>

The program will then only output what it will do without changing anything in your home directory.

For a quickstart and simple examples jump to "Examples" section below.

Configuring userctx

userctx is configured through a TOML file located at ~/.config/userctx/config.toml by default. The configuration is split into two main sections: [general] and [apps].

The [general] section

This section contains global settings for userctx.

• dry_run (boolean, optional): If set to true, userctx will only print the actions it would take without making any changes to the filesystem. This is useful for testing your configuration. The command-line flag --nop overrides this setting.
• apps (array of strings, required): A list of application names that userctx should manage. For each application in this list, userctx will look for a corresponding configuration section in the [apps] table.
• source_path (string, optional): The base path where your contexts are stored. Defaults to $XDG_CONFIG_HOME/userctx or ~/.config/userctx.
• target_path (string, optional): The base path where application configurations are located. Defaults to $XDG_CONFIG_HOME or ~/.config.

The [apps] section

For each application defined in the general.apps array, you can have a dedicated section to specify its configuration.

You can create [apps.<you_app>] section in the config to specify userctx behaviour for the app. The following options are supported.

• source_path (string, optional): Overrides the global source_path for this specific application.
• target_path (string, optional): Overrides the global target_path for this specific application. The final destination path for an application's configuration will be <target_path>/<app_name>.
• actions (array of strings, optional): A list of actions to perform for the application. The available actions are symlink, script, exec, and reload. If not specified, the default actions are [symlink, script, exec, reload] if the corresponding keys (symlink, script, exec, reload) are present in the app's configuration.
• symlink (table, optional): A map of source files to destination files for creating symlinks. The source is relative to the context's application directory (e.g., <source_path>/<context_name>/<app_name>), and the destination is relative to the application's target_path. You can use * as a wildcard to match all files in the source directory.
• exec (string, optional): A shell command or script to execute. The script is executed in a shell environment with the following environment variables set:
  • CONTEXT_NAME: The name of the context being applied.
  • CONTEXT_SRC: The source directory for the current application's context.
  • CONTEXT_DST: The target directory for the current application's configuration.
• script (array of strings, optional): A list of script files to execute. The scripts are looked for in the application's context directory. If the list is empty or not provided, userctx will look for and execute any file ending with .sh in the context directory.
• reload (string, optional): A shell command to execute to reload the application's configuration. This is typically used to make the application aware of the changes applied by userctx.

TODO: a more detailed explanation of wildcard symlinking.

Examples

Basic usecase: we only need symlinks

Let's add configuration for "foot" terminal emulator, which will be applied when we apply context "Goldfish" assuming we would like to switch foot's visual theme when swithching context.

1. First we need to create a separate file for visuals config in our context directory.

mkdir ~/.config/userctx/Goldfish/foot/
vim ~/.config/userctx/Goldfish/foot/theme.ini

And put the awesome "Tempus Day" into theme.ini:

# -*- conf -*-
# theme: Tempus Day
# author: Protesilaos Stavrou (https://protesilaos.com)
# description: Light theme with warm colours (WCAG AA compliant)

[colors]
foreground = 464340
# original background
# background = f8f2e5
background = ffffff
regular0 = 464340
regular1 = c81000
regular2 = 107410
regular3 = 806000
regular4 = 385dc4
regular5 = b63052
regular6 = 007070
regular7 = e7e3d7
bright0 = 68607d
bright1 = b24000
bright2 = 427040
bright3 = 6f6600
bright4 = 0f64c4
bright5 = 8050a7
bright6 = 336c87
bright7 = f8f2e5

You could as well symlink any file (pre-existing theme for foot) to ~/.config/userctx/Goldfish/foot/theme.ini

2. To include this theme file from main foot config add the following line to $HOME/.config/foot/foot.ini (edit to match your user's homedir):

include=/home/dmitry/.config/foot/theme.ini

Do not forget to remove style settings from foot.ini so they do not conflict with separate theme.ini.

3. Finally, tell userctx to manage foot config for you. Edit ~/.config/userctx/config.toml and add "foot" to "apps" array in "general" section of the config.

[general]
apps = [
  "foot",
  "sway",
  "wofi",
]

4. Test you configuration

userctx --nop apply Goldfish

The --nop (no-op) flag tells userctx to perform a dry-run. It will just output what it is going to do when you actually apply context.

If all looks good - that's it. When you issue userctx apply Goldfish a symlink will be created in your homedir:

~/.config/foot/theme.ini -> ~/.config/userctx/Goldfish/foot/theme.ini

More advanced usecase: run command and hot-reload

Let's configure userctx to apply theme to helix editor.

1. Similar to the above section, create ~/.config/userctx/Goldfish/helix/helix.toml with the following contents:

inherits = "github_light"
"ui.background" = {}

Now edit ~/.config/userctx/config.toml.

Add "helix" to "general" section.

[general]
apps = [
  "foot",
  "sway",
  "helix",
  "wofi",
]

2. Add "apps.helix" section:

[apps.helix]
symlink."*" = "themes/current_theme.toml"
exec = """sed -i -E 's/^theme = (.+)/theme = "current_theme"/' ~/.config/helix/config.toml"""
reload = "pkill -USR1 hx"

Here we instruct userctx to symlink any (single) file it finds in "helix" subdirectory of context folder to ~/.config/helix/themes/current_theme.toml

Then we run sed to change the config file. This part is not really necessare if helix is configured to use theme named "current_theme" and you're sure that config won't change. We could just replace the file and issue USR1. The sed part if for the case when config is changed by user or other app.

Finally we set the reload command which will tell helix to reload config.

3. Test your configuration,

userctx --nop apply Goldfish

See also template "config.toml" with numerous app settings.