v0.1.0

README.md

@@ -29,8 +29,8 @@ Typically a context directory looks like this.
 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
+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
@@ -41,7 +41,7 @@ The default location for the config is ~/.config/userctx/config.toml.
 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
+- *list* lists available contexts in a manner suitable for dmenu-like apps
 - *apply* \<context\> applies named context
 
 To test your configuration run:
@@ -54,7 +54,33 @@ anything in your home directory.
 For a quickstart and simple examples jump to "Examples" section below.
 
 ## Configuring userctx
-TODO: full description of config options.
+**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 option 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
@@ -62,7 +88,7 @@ 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
+1. First we need to create a separate file for visuals config in our
 context directory.
 
 ```bash
@@ -143,7 +169,7 @@ inherits = "github_light"
 ```
 Now edit  ~/.config/userctx/config.toml.
 
-Add the "helix" to "general" section.
+Add "helix" to "general" section.
 ```toml
 [general]
 apps = [