Your config files
Based keeps its defaults where an update can change them without touching your edits. This page is about Based Workstation and Based Poweruser. The Retro and pure editions lay their files once at install and never update them.
Five kinds of file
| kind | what it is | who changes it |
|---|---|---|
| system file | a package's file under /usr or /etc |
apt. Under /etc your edit is kept, see below |
| stub | a short file in your home that loads Based's defaults, with room for your own lines | Based, and only while you haven't edited it |
| seed-once | a starting file your home gets once | you and the app, from then on |
| managed file | written as you use the machine: the current theme, the desktop's settings, your agents' servers | the program that owns it |
| user file | yours from the start, such as ~/.zsh_aliases |
only you |
A handful of home files are still seed-once today, among them the Starship prompt, lazygit, the
GTK and Qt settings files, btop's config and the bar's ~/.config/omarchy/shell.json. Based never
updates them after your first login. Moving them to system files is planned.
Where your own settings go
| app | Based's defaults | your own settings |
|---|---|---|
| git | /etc/gitconfig, which includes /usr/share/based/gitconfig |
~/.gitconfig. Based never writes to it |
| tmux | /etc/tmux.conf |
a file in ~/.config/tmux/conf.d/, or a ~/.config/tmux/tmux.conf of your own |
| zsh | ~/.zshrc, one line that sources /usr/share/based/zsh/zshrc |
~/.zsh_aliases, ~/.zsh_envs, ~/.zsh_functions, ~/.zsh_sources, and ~/.path.list with one directory per line for PATH |
| sway | ~/.config/sway/config, which includes /usr/share/based/sway/config |
$mod, $term, $browser and $menu in a file under ~/.config/sway/config-vars.d/; everything else below the include |
| Neovim | LazyVim loads Based's plugin specs from /usr/share/based/nvim |
your own spec files in ~/.config/nvim/lua/plugins/ |
| Ghostty | ~/.config/ghostty/config, which includes the package config and the theme |
~/.config/ghostty/overrides.conf |
Your lines load after Based's, so yours win. Two details: in Ghostty a line below the includes
loses to them, so it has to go in overrides.conf, which is also where the font menu and the text
size write. A font-size below the includes is the one exception: it beats Based's size, though
not the Omarchy theme's or the one in overrides.conf. In Neovim, deleting one of Based's files in
~/.config/nvim/lua/plugins/ turns that plugin off.
What happens to your edits
At every login, and after every update in each session that's open, Based brings your home up to the current defaults. This step is called the converge. For each file it gives your home:
| your copy | what the converge does |
|---|---|
| missing, never given | adds it |
| unchanged since Based wrote it | replaces it with the new default |
| changed by you | keeps it, and logs where the new default is |
| deleted by you | leaves it deleted |
| a symlink, or inside a linked folder | never touches it |
listed in ~/.config/based/unmanaged |
never touches it |
Whole-line comments, blank lines and spacing don't count as changes in a format that has comments
(shell, TOML, INI, Lua, sway, Ghostty, git). So you can annotate a file and still get updates, but
when a new default replaces it your comments go with it. A comment after a setting on the same
line does count, since # also starts a colour.
Based tells its own copy from yours by a checksum of each file it wrote, kept in
~/.local/state/based/config/. A home older than that record is compared with every version Based
ever shipped of the file.
To take a new default for a file you changed, look up the path the converge logged and copy it over yours:
journalctl --user -u based-converge
The defaults live under /usr/share/based/config/<package>/skel/.
The first time a full copy becomes a stub
Older homes held whole copies of ~/.zshrc, the sway config, the Ghostty config and the Neovim
config. The first time the converge meets one, a copy that's still a version Based shipped becomes
the stub without a word. A copy you edited moves aside as <name>.bak (.bak.1 if that's taken)
and the stub goes in. Carry the lines you want from the .bak into the places in the table above.
Ghostty's font size and font, which Omarchy's text size and font settings wrote into that copy,
move to overrides.conf by themselves. It happens once per file. After that the stub is yours,
and an edit to it stays.
~/.config/tmux/tmux.conf goes the same way, since tmux now reads /etc/tmux.conf: an unedited
copy is removed and an edited one becomes tmux.conf.bak. ~/.gitconfig is never converted.
Telling Based to leave a file alone
List it in ~/.config/based/unmanaged, one path per line, spelled from your home:
# my own sway config
.config/sway/config
.config/waybar/
package:based-config-ghostty
A trailing / is the whole folder, package:<name> is every file one package gives your home, and
a bare * is your whole home, for when you bring your own dotfiles. Nothing listed is written
again until you take the line out. The installer reads the same file.
Files in /etc
A package's file in /etc follows dpkg's own rule. If you never edited it, an update installs the
new version. If you did, yours stays and the new one lands beside it as <file>.dpkg-dist. The
update never stops to ask. Where an app reads a drop-in folder, such as
/etc/systemd/logind.conf.d/, put your settings there instead of editing the package's file.