Skip to content

v0.2.0

Latest
Latest

Choose a tag to compare

View all tags
@evoppuden evoppuden released this 29 Apr 19:33
· 2 commits to main since this release
Latest
59645d5

dotref v0.2.0 — the "actually useful" release

The first version where dotref is a real tool you'd reach for. Reshapes the CLI surface, lands colors and an interactive picker, triples the database, and reconciles the contributor docs with what the code actually does.

Highlights

  • 🎨 Colors + interactive fzf picker. Bare dotref launches a colorized, fuzzy picker for every knob in the database. Type tags (env / parameter / setopt / shopt / config / flag) are color-coded so you can scan output at a glance.
  • 🔍 Direct knob lookup. dotref zsh HISTFILE now works — no more drilling through dotref zsh history and scrolling. Type the subsystem and the knob name; get the answer.
  • 🧱 3× the database. From 6 subsystems / 19 files / ~260 knobs in 0.1.0 to 9 subsystems / 31 files / 429 knobs. New: bash, qt, mesa, plus expanded xdg, hyprland, systemd, uwsm.
  • 🔗 Per-file [meta] block. Each TOML can declare an authoritative docs URL — rendered in category headers, the fzf preview, and --json output. All 31 shipped files seeded.
  • 🤖 Machine-readable output. --json and --plain flags for piping into jq, scripts, and other tools.
  • 📊 Ranked search. Results ordered exact → prefix → substring → description match. dotref search gtk puts gtk/* knobs at the top.
  • 📦 Auto-bootstrap on first run. No more mkdir -p ~/.dotref/data && cp -r data/* after install. The CLI seeds ~/.dotref/data from the bundled database the first time it runs against an empty dir.
  • 🔄 Real dotref update. Fetches the latest data/ tree from this repo as a tarball and atomically replaces ~/.dotref/data. Stdlib-only — no requests dependency. Refuses to operate inside a git checkout.

Breaking changes

  • show subcommand removed. dotref show zsh history no longer works. Use dotref zsh history instead. The first positional argument is the subsystem; the optional second is a category or a knob name.

Install / upgrade

Fresh install:

git clone https://github.com/evoppuden/dotref
cd dotref
pipx install -e .
dotref                  # bootstraps ~/.dotref/data on first run

Existing 0.1.0 install:

cd path/to/dotref && git pull
pipx reinstall dotref
dotref update           # pull the latest data

Optional: install fzf for the interactive picker.

Try it

dotref                          # interactive fzf picker
dotref bash                     # list bash categories
dotref qt scaling               # show all Qt scaling env vars
dotref zsh HISTFILE             # direct knob lookup
dotref search theme             # ranked cross-subsystem search
dotref --json mesa drivers      # machine-readable output
dotref update                   # pull the latest database

Stats

0.1.0 0.2.0
Subsystems 3 9
TOML files 3 31
Knobs ~30 429
CLI LOC ~250 ~600
Subcommands list, show, search, update list, search, pick, update, plus implicit <sub> / <sub> <cat> / <sub> <name>

What's next

The big lever is more data. Planned subsystems wanted by users:

  • wayland, nvidia, x11 (graphics stack)
  • dbus, locale, color (smaller, can land together)
  • expanded zsh (completion, prompt, expansion)

PRs that just add a .toml file are very welcome — see CONTRIBUTING.md.

Full changelog

See CHANGELOG.md for the complete entry.

Thanks to everyone who reviewed early drafts and pointed out that "you know, man zsh really is terrible for finding HISTFILE."

Assets 2
Loading