Profiles, and how they
inherit.

A profile is a named set of dotfiles and packages. You can have several — for work, personal use, a server, or any context you care about — and switch between them in one keystroke.

The short version

• Profiles are independent sets of files. Switch between them and your environment reshapes itself.
• Inheritance lets a profile extend a parent. Children only override what's different.
• Common files are shared across every profile automatically.
• Cycles are detected and rejected. Parent profiles can't be deleted while a child still inherits from them.

Resolution order

When you activate a profile, dotstate walks the inheritance chain and resolves files in this order — highest priority first:

In the example above, work-laptop ends up with: its own .ssh/config, work's .zshrc, base's .vimrc and .tmux.conf, and common's .gitconfig.

Inherit vs. copy

When you create a profile, you can either inherit or copy from an existing one:

• Inherit is a live relationship. Changes to the parent flow down to every child.
• Copy is a one-time fork. After creation, the two profiles are independent.

A good rule: use inherit for long-lived relationships (a "base" profile that every machine extends), and copy for quick one-off duplicates when setting up a similar machine.

Switching profiles

Open Manage Profiles in the TUI, select a profile, and press Enter. dotstate removes the old symlinks and creates new ones — including any inherited files. Common files stay linked across every switch.

From the command line, use dotstate profile switch <name> for the same effect — handy in scripts or when you want to bind it to a shell alias. dotstate profile prints the active profile and dotstate profile list shows all of them.

From a fresh shell on a new machine, dotstate activate re-creates the symlinks for the profile recorded in your config — no flags needed.

If activation fails for any reason, the previous profile is restored automatically.

When to use common files

Put a file in common when it should be identical on every machine, regardless of the active profile — like .gitconfig, .tmux.conf, or editor config files you never vary.

Move files in and out of common from Manage Files by selecting a file and pressing M. See common files for details.

Use cases

• Multi-machine. personal on your laptop, work on your work machine, server on headless boxes. Keep shared configs (.gitconfig, .tmux.conf) in common.
• Same computer, different contexts. Create day, night, or focus profiles with different terminal themes and editor settings, and switch in a keystroke.
• Layered configs. A base profile defines your core setup; work and personal inherit from it and override only what's different.
• Quick duplication. When setting up a second machine, create a new profile by copying from an existing one, then tweak the small things.

Next

Profiles also track packages — CLI tools to install per context. Read package management to learn how.