Configuration Overview¶

tidydots uses a two-level configuration system: a minimal app config that points to your dotfiles repository, and a repo config inside that repository that describes everything tidydots manages.

Two-Level Configuration¶

App Config¶

Location: ~/.config/tidydots/config.yaml

This file is created by tidydots init and contains a single field:

# tidydots app configuration
# This file only stores the path to your configurations repository

config_dir: ~/dotfiles

Repo Config¶

Location: <config_dir>/tidydots.yaml

This is the main configuration file that lives inside your dotfiles repository. It describes all applications, their config entries, and packages.

version: 3

applications:
  - name: "nvim"
    description: "Neovim text editor"
    entries:
      - name: "nvim-config"
        backup: "./nvim"
        targets:
          linux: "~/.config/nvim"
          windows: "~/AppData/Local/nvim"
    package:
      managers:
        pacman: "neovim"
        apt: "neovim"
        brew: "neovim"

Root-Level Fields¶

The tidydots.yaml file supports the following root-level fields:

version¶

version: 3

The version field is required. tidydots currently only supports version 3. If omitted, it defaults to 3, but explicitly setting it is recommended for clarity.

backup_root¶

backup_root: "./backups"

Sets the base directory for resolving relative backup paths in config entries. Defaults to ".", meaning relative paths are resolved from the directory containing tidydots.yaml.

default_manager¶

default_manager: "yay"

Specifies which package manager to prefer when multiple are available on the system. This is overridden by manager_priority if both are set.

manager_priority¶

manager_priority:
  - paru
  - yay
  - pacman

An ordered list of package managers. tidydots tries each in order and uses the first one available on the system. This takes precedence over default_manager.

applications¶

applications:
  - name: "zsh"
    entries:
      - name: "zshrc"
        backup: "./zsh"
        targets:
          linux: "~/.config/zsh"

An array of Application objects. Each application groups related config entries and an optional package definition under a single name.

Complete Example¶

version: 3
backup_root: "."
default_manager: "yay"
manager_priority:
  - paru
  - yay
  - pacman

applications:
  - name: "nvim"
    description: "Neovim text editor"
    when: '{{ or (eq .OS "linux") (eq .OS "windows") }}'
    entries:
      - name: "nvim-config"
        backup: "./nvim"
        targets:
          linux: "~/.config/nvim"
          windows: "~/AppData/Local/nvim"
    package:
      managers:
        pacman: "neovim"
        apt: "neovim"
        brew: "neovim"
        winget: "Neovim.Neovim"

  - name: "zsh"
    description: "Z shell configuration"
    when: '{{ eq .OS "linux" }}'
    entries:
      - name: "zshrc"
        backup: "./zsh"
        targets:
          linux: "~/.config/zsh"
    package:
      managers:
        pacman: "zsh"
        apt: "zsh"
        brew: "zsh"

Configuration Loading¶

When you run any tidydots command:

1. tidydots reads ~/.config/tidydots/config.yaml to find your config_dir
2. It loads <config_dir>/tidydots.yaml as the repo config
3. Paths containing ~ are expanded to your home directory
4. Paths containing {{ }} template expressions are rendered (see Templates)
5. Applications are filtered by their when expressions against the current platform