Configs (SubEntry)¶

A SubEntry (config entry) represents a single configuration that tidydots manages, by default through symlinks. Config entries live inside an Application's entries array and define where files are backed up in your dotfiles repo and where they should be deployed on the target system.

Schema Reference¶

How It Works¶

When you run tidydots restore, for each config entry tidydots:

1. Reads the backup path (relative to the config directory)
2. Looks up the targets map for the current OS
3. Creates a symlink from the target path pointing to the backup path (or writes a real file copy, if method: copy is set — see Deployment Method)
4. If files is specified, only those specific files are symlinked (or copied)

The result is that your system reads configuration from the target path, but the actual files live in your dotfiles repository.

Fields in Detail¶

backup¶

The backup field specifies where the configuration files are stored in your dotfiles repository. This path is relative to the directory containing tidydots.yaml.

backup: "./nvim"           # Relative to config directory
backup: "./shell/zsh"      # Nested directory

targets¶

The targets field is a map from OS identifier to the target path on that OS. tidydots looks up the current OS and uses the corresponding path.

At least one target must be declared. A config entry with backup set but no targets will be rejected during validation.

targets:
  linux: "~/.config/nvim"
  windows: "~/AppData/Local/nvim"

Supported OS keys:

Paths support ~ expansion to the user's home directory.

Path templating is also supported. Any path containing {{ }} delimiters is rendered as a Go template before expansion:

targets:
  linux: "~/.config/{{ .Hostname }}/nvim"

See Templates for available template variables and functions.

files¶

The files field is an optional list of specific filenames to manage. When specified, only those files are symlinked individually. When omitted or empty, the entire folder is symlinked.

# Symlink specific files only
files:
  - ".zshrc"
  - ".zprofile"

# Symlink the entire folder (files omitted)
files: []

method¶

The method field selects how tidydots deploys this entry's files to the target path:

• symlink (default, or when method is omitted) — creates a symlink at the target pointing back into the dotfiles repo.
• copy — writes a real, independent file at the target instead. The repo file remains the source of truth.

method: copy

See Deployment Method below for the full behavior, migration notes, and v1 limitations.

sudo¶

When sudo: true is set, tidydots uses elevated privileges for all symlink operations on this entry. This is required for targets outside your home directory, such as system configuration files.

sudo: true

Deployment Method¶

By default, config entries are deployed as symlinks: the target path becomes a symlink pointing back into your dotfiles repo, and the repo file is what you actually edit. Setting method: copy on an entry switches to writing a real, independent file at the target instead.

entries:
  - name: "blacklist"
    method: copy
    files: ["blacklist-raydium.conf"]
    backup: "./Linux/modprobe"
    targets:
      linux: "/etc/modprobe.d"
    sudo: true

Symlink vs. Copy¶

Refresh and Idempotency¶

With method: copy, every tidydots restore compares the target file's content against the corresponding repo (backup) file:

• If the contents differ, the target is overwritten with the current repo content.
• If the contents already match, tidydots makes no changes (a no-op).

Because the target is a real file rather than a live link, editing the file in the dotfiles repo and re-running tidydots restore is how changes reach a copy-mode target.

Migrating from Symlink to Copy¶

If the target currently exists as a symlink (for example, the entry was previously deployed with method: symlink, or adopted), switching the entry to method: copy and re-running tidydots restore removes the existing symlink and replaces it with a real file copied from the repo. This makes symlink-to-copy migration safe without any manual cleanup.

v1 Limitations¶

• Files only — method: copy requires an explicit, non-empty files: list. Whole-folder copying (files: []) is not supported and is rejected during config validation.
• No template rendering — Template (.tmpl) rendering only ever applies to folder entries (an entry with an empty files: list); see Template Files in Config Entries. Since method: copy requires an explicit, non-empty files: list, template rendering never applies to copy entries — this is a consequence of copy mode being files-only, not an additional restriction.

When to Use It¶

Use method: copy for files that must be readable very early in boot, before $HOME (or an encrypted subvolume containing your dotfiles repo) is mounted — for example /etc/modprobe.d or /etc/udev/rules.d. At that point in boot, a symlink into the dotfiles repo would be a dangling link, since its target isn't available yet; a real copied file has no such dependency and is readable immediately.

Examples¶

Single File¶

Manage a single configuration file:

entries:
  - name: "gitconfig"
    backup: "./git"
    files:
      - ".gitconfig"
    targets:
      linux: "~"
      windows: "~"

This creates a symlink ~/.gitconfig pointing to <dotfiles>/git/.gitconfig.

Entire Folder¶

Manage an entire configuration directory:

entries:
  - name: "nvim-config"
    backup: "./nvim"
    targets:
      linux: "~/.config/nvim"
      windows: "~/AppData/Local/nvim"

This creates a symlink ~/.config/nvim pointing to <dotfiles>/nvim/.

Multiple Files from One Backup¶

Pick specific files from a backup directory:

entries:
  - name: "zsh-dotfiles"
    backup: "./zsh"
    files:
      - ".zshrc"
      - ".zprofile"
      - ".zshenv"
    targets:
      linux: "~"

This creates three individual symlinks (~/.zshrc, ~/.zprofile, ~/.zshenv), each pointing to the corresponding file in <dotfiles>/zsh/.

Cross-Platform Entry¶

Define different target paths per OS:

entries:
  - name: "terminal-config"
    backup: "./alacritty"
    targets:
      linux: "~/.config/alacritty"
      windows: "~/AppData/Roaming/alacritty"

On Linux the symlink is at ~/.config/alacritty; on Windows it is at ~/AppData/Roaming/alacritty. Both point to the same <dotfiles>/alacritty/ backup directory.

Path Templates¶

Use template expressions in target paths for host-specific layouts:

entries:
  - name: "nvim-config"
    backup: "./nvim"
    targets:
      linux: "~/.config/{{ .Hostname }}/nvim"

On a machine with hostname desktop, this resolves to ~/.config/desktop/nvim. See Templates for the full set of available variables.

System-Level Config with Sudo¶

Manage files that require root privileges:

entries:
  - name: "pacman-conf"
    sudo: true
    backup: "./system/pacman"
    files:
      - "pacman.conf"
    targets:
      linux: "/etc"

  - name: "hosts"
    sudo: true
    backup: "./system"
    files:
      - "hosts"
    targets:
      linux: "/etc"

Multiple Entries in One Application¶

Group related configs under one application:

applications:
  - name: "zsh"
    description: "Z shell configuration"
    when: '{{ ne .OS "windows" }}'
    entries:
      - name: "zsh-dotfiles"
        backup: "./zsh"
        files:
          - ".zshrc"
          - ".zprofile"
        targets:
          linux: "~"

      - name: "zsh-custom"
        backup: "./zsh/custom"
        targets:
          linux: "~/.config/zsh/custom"
    package:
      managers:
        pacman: "zsh"
        apt: "zsh"
        brew: "zsh"

Template Files in Config Entries¶

Config entries can contain .tmpl template files in their backup directory. During restore, these files are rendered using the template engine, and the output is written as .tmpl.rendered sibling files. The symlink then points to the rendered output.

For example, if your backup directory contains alacritty.toml.tmpl:

1. tidydots renders the template to alacritty.toml.tmpl.rendered
2. A relative symlink alacritty.toml is created pointing to alacritty.toml.tmpl.rendered
3. The folder-level symlink from the target path points to the backup directory as usual

See Templates for the full template system documentation.