Profiles

Profiles are the core organizational unit in dotts. They define logical groupings of configurations, packages, and settings that can be composed through inheritance.

Concept

Think of profiles as layers that stack on top of each other:

┌─────────────────────────────────────┐
│           machine config            │  (most specific)
├─────────────────────────────────────┤
│          desktop profile            │
├─────────────────────────────────────┤
│           linux profile             │
├─────────────────────────────────────┤
│           base profile              │  (most generic)
└─────────────────────────────────────┘

Each layer can add configs, packages, and settings. More specific layers override settings from generic ones.

Profile Structure

# profiles/base.yaml
name: base
description: Universal base configuration

configs:
  - shell
  - git
  - tools

packages:
  - common

settings:
  shell: fish
  editor: nvim
  theme: catppuccin

scripts:
  post_install:
    - ./scripts/setup-shell.sh

Fields

Field	Type	Description
`name`	string	Profile identifier
`description`	string	Human-readable description
`inherits`	list	Profiles to inherit from
`configs`	list	Config directories to include
`packages`	list	Package manifests to include
`settings`	map	Key-value settings
`scripts`	object	Lifecycle scripts

Inheritance

Profiles can inherit from other profiles using the inherits field:

# profiles/linux.yaml
name: linux
description: Linux-specific configuration

inherits:
  - base

configs:
  - terminal

packages:
  - arch

# profiles/desktop.yaml
name: desktop
description: Desktop workstation with Hyprland

inherits:
  - linux

configs:
  - editor
  - wm

settings:
  compositor: hyprland
  bar: waybar

Inheritance Rules

Configs are merged (union of all configs in the chain)
Packages are merged (union of all package manifests)
Settings are merged with override (child overrides parent)
Scripts are concatenated (all scripts run in order)

Common Patterns

Platform Profiles

# profiles/linux.yaml
name: linux
inherits: [base]
packages: [linux-common]

# profiles/darwin.yaml
name: darwin
inherits: [base]
packages: [darwin-common]

Use Case Profiles

# profiles/server.yaml
name: server
inherits: [linux]
configs: [shell, tools]

# profiles/desktop.yaml
name: desktop
inherits: [linux]
configs: [shell, editor, terminal, wm]

# profiles/notebook.yaml
name: notebook
inherits: [desktop]
settings:
  monitors: 1
  battery: true

Settings

Settings flow through the inheritance chain and can be overridden at any level:

# base.yaml
settings:
  theme: catppuccin
  monitors: 1

# desktop.yaml
settings:
  monitors: 2  # overrides base

# machine config
settings:
  monitors: 3  # overrides desktop

Settings are available as template variables. See Templates for more information.

Scripts

Lifecycle scripts run at specific points during setup:

scripts:
  pre_install:
    - ./scripts/pre-setup.sh
  post_install:
    - ./scripts/configure-shell.sh
    - ./scripts/setup-neovim.sh
  pre_update:
    - ./scripts/backup-configs.sh
  post_update:
    - ./scripts/reload-configs.sh

Scripts from parent profiles run before child profile scripts.

Best Practices

Keep base minimal - Only include truly universal configs
Use clear naming - Profile names should be descriptive
Avoid deep nesting - 3-4 levels of inheritance is usually enough
Document settings - Add descriptions to non-obvious settings
Test inheritance - Use dotts status to verify the resolved config

Profiles

On this page