QOMPASS AI

CLI tool — Python dotfile manager (Dotbot-style), driven by a YAML/JSON config file

Qonfig

Qonfig

Version 1.00Source on GitHub

OVERVIEW

Qonfig is "A Quality Dotfile Manager": you fill in `qonfig.yaml` and Qonfig takes care of the rest, symlinking files, cleaning dead links, and running shell commands from a list of directives. It is installed into a dotfiles repo as a Git submodule (or Mercurial subrepo) behind a small `install` shim.

HOW IT WORKS

  1. 1Add Qonfig to your dotfiles repo: `git submodule add https://github.com/qompassai/qonfig`, copy the shim with `cp qonfig/tools/git-submodule/install .`, and create `qonfig.yaml`.
  2. 2Or bootstrap a new setup with `curl -fsSL https://raw.githubusercontent.com/qompassai/qonfig/main/scripts/quickstart.sh | sh`.
  3. 3Fill in `qonfig.yaml` as a list of tasks using the `defaults`, `clean`, `link`, and `shell` directives.
  4. 4Run `./install`; the shim updates the submodule and calls `bin/qonfig -d <base dir> -c qonfig.yaml`.
  5. 5Qonfig dispatches each task to its plugin, in order, and reports "All tasks executed successfully" or fails.
  6. 6Upgrade later with `git submodule update --remote qonfig`.
How it works, step by step — each step as the project's own documentation states it.

CONCEPTS

QONFIG.YAML — TASKS DISPATCHED IN ORDERqonfig.yamla list of tasks (YAML, or JSON/JSONC)via ./install — bin/qonfig -d BASEDIR -c qonfig.yamlDISPATCHER — each task to its plugin, in orderdefaultsoptions applied tothe tasks that followcleanremove dead symlinkspointing into thedotfiles directorylinksymlink files into placecreate · relink · forcerelative optionsshellrun shell commandsoptional descriptionand stdio toggles'ALL TASKS EXECUTED SUCCESSFULLY' — OR IT FAILSsome configs also use a create directive — the shipped plugins are clean, link and shell;the dispatcher logs any unhandled action instead of applying it
Qonfig's directive pipeline, from its docs and dispatcher: qonfig.yaml is a list of tasks the dispatcher hands to its plugins in order — defaults, clean, link and shell. The create directive used in some configs (including the project's own) has no plugin in the shipped tree and is logged as unhandled, so it is flagged in the figure rather than drawn as an applied step.

CONFIGURATION

OptionDefaultWhat it does
defaults.link.createtrue (in repo's own qonfig.yaml)Create parent directories for links; set via a `defaults:` task applying to following tasks
defaults.link.relinktrue (in repo's own qonfig.yaml)Overwrite incorrect symlinks
link.<target>.pathtarget's plain valueSource path (relative to base directory) for an extended link entry
link.<target>.createfalse (plugin default)Create the parent directory if necessary
link.<target>.relinkfalse (plugin default)Automatically overwrite incorrect symbolic links
link.<target>.forcefalse (plugin default)Forcibly link, overwriting existing files/directories
link.<target>.relativefalse (plugin default)Make the symlink with a relative path
clean`["~", ~/.config]` (repo's own qonfig.yaml)Directories checked for dead symlinks pointing into the dotfiles directory; dead links are removed
shell[].command / description / stdin / stdout / stderr—Extended shell-command form: command plus optional description and stdio toggles
-c / --config-file CONFIGFILErequired (no default)Config file to run
-d / --base-directory BASEDIRrequired (no default)Directory commands execute from within
install shim CONFIG / QONFIG_DIRqonfig.yaml` / `qonfigConfig location and submodule location assumed by the `install` script; editable in the script

CONTROLS

ActionControl
Quick start`curl -fsSL https://raw.githubusercontent.com/qompassai/qonfig/main/scripts/quickstart.sh \
Set up with Gitgit submodule add https://github.com/qompassai/qonfig` then `cp qonfig/tools/git-submodule/install .
Set up with Mercurialhg init`, write `.hgsub`, `git clone https://github.com/qompassai/qonfig`, `cp qonfig/tools/hg-subrepo/install .
Apply the configuration`./install` (shim for `bin/qonfig -d BASEDIR -c CONFIGFILE`)
Run the CLI directly`qonfig -d BASEDIR -c CONFIGFILE` (console script `qonfig = qonfig.cli:main`)
Verbose / quiet output-v/--verbose`, `-q/--quiet`, `-Q/--super-quiet
Load a plugin`-p/--plugin PLUGIN` (repeatable)
Load all plugins in a directory`--plugin-dir PLUGIN_DIR` (repeatable)
Disable built-in plugins--disable-built-in-plugins
Upgrade (submodule install)git submodule update --remote qonfig

NOT COVERED

- The repo's own `qonfig.yaml`/`qonfig.jsonc` (and the dotfiles repo's) use a top-level `- create: [~/Downloads]` directive, but `plugins/` contains only `clean.py`, `link.py`, and `shell.py` and `docs/README.md` documents no `create` directive; the dispatcher logs "Action %s not handled" for unhandled actions (`qonfig/dispatcher.py`). Whether `create` works in the shipped build could not be verified from sources. - Per-link `if:` conditions used in the dotfiles repo's `qonfig.yaml` are likewise not handled in `plugins/link.py` as read. - `pyproject.toml` describes the package as "Quantum AI models for healthcare and education", which does not match the dotfile-manager documentation; treated as stale metadata.

REFERENCES

  1. YAML Specification, version 1.2.2The YAML specification — the format qonfig.yaml task lists are written in (a JSON/JSONC form is also accepted).
  2. Dotbot — a tool that bootstraps your dotfilesThe upstream dotfile manager Qonfig is styled on (Dotbot-style, per the project's own description): a YAML list of directives applied in order.