181 lines
5.2 KiB
Markdown
181 lines
5.2 KiB
Markdown
# 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.
|
|
```bash
|
|
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.
|
|
```bash
|
|
/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
|
|
symlinked you ~/.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 menu apps
|
|
- *apply* \<context\> applies named context
|
|
|
|
To test your configuration run:
|
|
```bash
|
|
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
|
|
TODO: full description of config options.
|
|
|
|
## 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 out
|
|
context directory.
|
|
|
|
```bash
|
|
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
|
|
```bash
|
|
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:
|
|
```toml
|
|
inherits = "github_light"
|
|
"ui.background" = {}
|
|
```
|
|
Now edit ~/.config/userctx/config.toml.
|
|
|
|
Add the "helix" to "general" section.
|
|
```toml
|
|
[general]
|
|
apps = [
|
|
"foot",
|
|
"sway",
|
|
"helix",
|
|
"wofi",
|
|
]
|
|
```
|
|
2. Add "apps.helix" section:
|
|
```toml
|
|
[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,
|
|
```bash
|
|
userctx --nop apply Goldfish
|
|
```
|
|
|
|
See also template "config.toml" with numerous app settings.
|
|
|