Applications¶

An Application is the top-level grouping unit in tidydots. Each application bundles related config entries and an optional package definition under a single name with optional conditional inclusion.

Schema Reference¶

Minimal Example¶

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

Full Example¶

applications:
  - name: "nvim"
    description: "Neovim text editor"
    when: '{{ eq .OS "linux" }}'
    entries:
      - name: "nvim-config"
        backup: "./nvim"
        targets:
          linux: "~/.config/nvim"
          windows: "~/AppData/Local/nvim"
      - name: "nvim-spell"
        backup: "./nvim-spell"
        files:
          - "en.utf-8.add"
        targets:
          linux: "~/.local/share/nvim/site/spell"
    package:
      managers:
        pacman: "neovim"
        apt: "neovim"
        brew: "neovim"

When Expressions¶

The when field controls whether an application is included based on the current platform. It uses Go text/template syntax and must evaluate to exactly the string "true" for the application to be included.

Template Context¶

Templates have access to the following context variables:

Expression Examples¶

Match a specific OS:

when: '{{ eq .OS "linux" }}'

Match multiple conditions (AND):

when: '{{ and (eq .OS "linux") (eq .Distro "arch") }}'

Match either condition (OR):

when: '{{ or (eq .OS "linux") (eq .OS "windows") }}'

Match a specific hostname:

when: '{{ eq .Hostname "work-laptop" }}'

Negate a condition:

when: '{{ ne .OS "windows" }}'

Check an environment variable:

when: '{{ eq (index .Env "DISPLAY") ":0" }}'

Complex expression (Arch Linux on a specific machine):

when: '{{ and (eq .Distro "arch") (eq .Hostname "desktop") }}'

Evaluation Rules¶

• Empty or missing when: The application is always included.
• Result must be exactly "true": Any other string (including "false", "1", or empty) means the application is excluded.
• Template errors: If the template fails to render (e.g., syntax error), the application is excluded.
• Whitespace: Leading and trailing whitespace in the result is trimmed before comparison.

Entries¶

The entries field is an array of SubEntry objects. Each entry defines a config symlink managed by tidydots. An application must have at least one entry.

entries:
  - name: "main-config"
    backup: "./nvim"
    targets:
      linux: "~/.config/nvim"

  - name: "snippets"
    backup: "./nvim-snippets"
    files:
      - "go.json"
      - "python.json"
    targets:
      linux: "~/.config/nvim/snippets"

See the Configs reference for the full SubEntry schema.

Package¶

The package field defines how to install the application. It is an EntryPackage object with support for system package managers, git repositories, custom commands, and URL downloads.

package:
  managers:
    pacman: "neovim"
    apt: "neovim"
    brew: "neovim"

See the Packages reference for all package types and installation methods.

Sudo Behavior¶

When sudo: true is set on a config entry, tidydots uses elevated privileges for symlink operations on that entry's target path. This is needed for system-level configurations like files under /etc/.

applications:
  - name: "system-config"
    when: '{{ eq .Distro "arch" }}'
    entries:
      - name: "pacman-conf"
        sudo: true
        backup: "./system/pacman"
        targets:
          linux: "/etc/pacman.conf"
      - name: "hosts"
        sudo: true
        backup: "./system/hosts"
        targets:
          linux: "/etc/hosts"

Tips¶