Dotfiles

mise saves the history of the configuration files you edit in place, or deploys them from a dotfiles repository as links, copies, and templates. The commands are under mise dotfiles, which these pages shorten to its alias mise dot; mise bootstrap dotfiles runs the same commands. Dotfiles work on their own, with or without mise bootstrap.

Recommended setup

If you are not sure where to start, track your files in place, let the watcher save every edit, and share them through a private Git repository. Add the watcher to ~/.config/mise/config.toml:

[bootstrap.services.mise-history]
builtin = "history-watch"

Then track your files and your mise configuration, start the watcher, and connect the repository:

mise dot track ~/.zshrc ~/.config/nvim ~/.config/mise/config.toml
mise bootstrap services apply
mise dot origin set https://github.com/you/dotfiles.git --sync sync

On another machine, mise bootstrap --adopt you/dotfiles restores them. Set up a machine walks through each step. The rest of these pages cover the other approaches and every option; you do not need them to get started.

Choose an approach

Tracking leaves each file where it is, as a regular file you keep editing, and saves its versions in a local Git repository that you can roll back and share between machines. Deploying keeps the files in a source directory you maintain, such as a dotfiles repository, and mise dot apply makes the live files match it. You can combine the two and track a file that mise deploys.

You want to	Use
Keep editing a file where it is, and undo or share changes	mode = "track"
Keep files in a repository and link them into place	symlink or symlink-each
Give an application a regular file that it can also rewrite	copy
Generate a file that differs per machine	template
Deploy a whole tree, and choose parts of it per machine	Groups
Own a few keys in a file that an application also writes	merge = true
Add a line or block to a file you do not otherwise manage	line or block
Remove an old file from every machine	mode = "absent"

Track a file in place

mise dot track ~/.zshrc

mise leaves the file where it is, saves its current contents as a checkpoint, and adds "~/.zshrc" = { mode = "track" } to your global config (~/.config/mise/config.toml). Run mise dot save after you edit it, or install the watcher to save every edit automatically. Dotfiles history covers comparing and rolling back versions, and Sync across machines shares them through a private Git repository. Set up a machine walks through the whole flow on two machines.

Deploy from a repository

Suppose your dotfiles live in a Git repository:

~/src/dotfiles/
├── mise.toml
├── git/config
└── nvim/

Declare each target and its source in the repository's mise.toml:

# ~/src/dotfiles/mise.toml
[dotfiles]
"~/.gitconfig" = { source = "git/config", mode = "copy" }
"~/.config/nvim" = { source = "nvim" }   # a symlink, the default mode

Trust the file, preview, apply, and check the result:

cd ~/src/dotfiles
mise trust
mise dot apply --dry-run
mise dot apply
mise dot status

mise copies git/config to ~/.gitconfig and links ~/.config/nvim to the nvim directory, and status reports both as applied. Relative sources start from the directory of the config file that declares them. To change a file later, edit its source and run mise dot apply again.

A repository's mise.toml is project config. mise reads its [dotfiles] only after you trust it, and only when it runs inside that directory, or with mise -C ~/src/dotfiles dot apply from anywhere else.

To deploy the whole repository into your home directory, one entry can walk it:

[dotfiles]
"~" = { source = ".", mode = "symlink-each", exclude = ["mise.toml", "*.md", ".git"] }

For a GNU Stow layout, with one directory per application, use groups. To start from files you already have, mise dot add moves each one into your dotfiles directory and links it back. Managed files covers modes, templates, permissions, and conflicts.

Where to declare dotfiles

Put [dotfiles] in one of these places:

• Your global config, ~/.config/mise/config.toml, so that it applies from any directory. mise dot track writes its entries here, and so does mise dot add, unless write_targets.dotfiles names another global file.
• A conf.d folder next to the sources it uses. The folder can be a symlink into your dotfiles repository.
• The mise.toml of your dotfiles repository, as above.

Entries merge across these files like the rest of the config hierarchy: a more local file replaces an entry with the same target. Tracking entries and the [history] table are read only from global and system config. To give some entries to one machine or operating system, put them in config.local.toml, or in a platform file such as config.macos.toml with the auto_env setting on; see Platform environments.

With mise bootstrap

mise bootstrap applies [dotfiles] as one step of a full machine setup, after it clones repositories, so a source can come from a repository it just cloned; see the run order. mise dot apply runs the same step on its own. Both run your pre-dotfiles and post-dotfileshooks before and after they write (--dry-run prints the hooks instead), and the [history.reload] commands that match the files they wrote. mise dot add and mise dot edit --apply do not run these hooks.

Commands

Task	Commands
Preview and apply	mise dot diff, mise dot apply
Check state	mise dot status
Adopt a file or capture edits	mise dot add, mise dot edit
Remove deployed files	mise dot unapply
Track and save	mise dot track, mise dot save, mise dot untrack
Browse and restore	mise dot history, mise dot rollback, mise dot undo
Share between machines	mise dot origin, mise dot sync, mise dot pull

See mise dotfiles for every subcommand and flag.

Next steps

• Managed files: entries, modes, templates, permissions, and conflicts.
• Groups: deploy directory trees and choose them per machine.
• Edit part of a file: blocks, lines, and merged keys.
• Dotfiles history: save, compare, and roll back tracked files.
• Dotfiles reference: every key, pattern rule, and status state.
• Dotfiles That Save Themselves walks through tracking and syncing a real setup.