Skip to content

FAQ

Jump to bottom
Aleem Isiaka edited this page Mar 31, 2026 · 5 revisions

FAQ

Frequently asked questions about Heimdal.

Table of Contents

General

What is Heimdal?

Heimdal is a dotfile and system configuration manager. It helps you:

  • Manage dotfiles across multiple machines with symlinking
  • Install packages from various package managers (Homebrew, APT, DNF, Pacman, APK, MAS)
  • Sync configurations using Git
  • Use multiple profiles for different machines
  • Store secrets securely in OS keychains
  • Import from existing tools (Stow, dotbot, chezmoi, yadm, homesick)

What platforms does Heimdal support?

  • macOS — Full support (Homebrew, Homebrew Casks, MAS)
  • Linux — Full support (APT, DNF, Pacman, APK)
    • Debian/Ubuntu
    • Fedora/RHEL
    • Arch Linux
    • Alpine Linux

How is Heimdal different from GNU Stow?

Feature Heimdal GNU Stow
Symlinks Yes Yes
Package management Yes No
Git sync Yes No
Multiple profiles Yes No
Secret management Yes No
Templates Yes No
Import from Stow Yes —

Heimdal is Stow-compatible — you can import existing Stow setups with heimdal import --from stow.

Is there a package database?

No. There is no external package database, no network fetching, and no local cache. Packages are defined directly in heimdal.yaml. packages search and packages info shell out to the native package manager.

Getting Started

How do I install Heimdal?

macOS (Homebrew):

brew install limistah/tap/heimdal

Any platform (Cargo):

cargo install heimdal

See Installation for all methods.

How do I get started?

Option 1: Fresh start (recommended)

heimdal wizard

Option 2: Import from an existing tool

heimdal import --path ~/.dotfiles --from stow

Option 3: Clone existing dotfiles

heimdal init --repo git@github.com:you/dotfiles.git --profile default
heimdal apply

See Quick Start for step-by-step guidance.

Can I preview changes before applying?

Yes. Use --dry-run on any apply command:

heimdal apply --dry-run

Where does Heimdal store its files?

File Location
Configuration <dotfiles_path>/heimdal.yaml
State ~/.heimdal/state.json (not inside dotfiles dir)
Secret names manifest <dotfiles_path>/.heimdal/secrets_manifest.json
Secret values OS keychain (macOS Keychain / Linux Secret Service)

Configuration

What is heimdal.yaml?

heimdal.yaml is the main configuration file. It defines:

  • Global settings (heimdal.version, heimdal.repo)
  • Top-level packages (applied to every profile)
  • Profiles (packages, dotfiles, templates, hooks, ignore)

Minimum valid config:

heimdal:
  version: "1"

profiles:
  default:
    packages:
      homebrew: [git, vim]
    dotfiles:
      - .vimrc

Where should heimdal.yaml live?

In the root of your dotfiles repository:

~/.dotfiles/
├── heimdal.yaml   ← here
├── .vimrc
└── .zshrc

How do I validate my configuration?

heimdal validate

This checks YAML syntax, required fields, valid profile extends references, and hook syntax.

Package Management

What package managers does Heimdal support?

Key Manager Platform
common Detected PM Any OS
homebrew Homebrew macOS / Linux
homebrew_casks Homebrew Casks macOS
apt APT Debian / Ubuntu
dnf DNF Fedora / RHEL
pacman Pacman Arch Linux
apk APK Alpine Linux
mas Mac App Store macOS

How does Heimdal know which package manager to use?

Heimdal auto-detects the OS and installs only from the manager(s) present on the current machine. Keys for other platforms are silently skipped:

packages:
  homebrew: [neovim]   # used only on macOS/Linux with Homebrew
  apt: [neovim]        # used only on Debian/Ubuntu
  dnf: [neovim]        # used only on Fedora/RHEL

What is the common key?

common is for packages that have the same name across all package managers. Heimdal installs them via the first available PM on the current OS:

packages:
  common: [git, curl, vim]   # installs on any OS via detected PM

Can Heimdal update or upgrade packages?

No. Heimdal does not provide packages update, packages upgrade, or packages outdated commands. Use the native package manager for updates:

brew upgrade        # macOS
sudo apt upgrade    # Debian/Ubuntu
sudo dnf upgrade    # Fedora

How do I find the right package name?

heimdal packages search <query>
# or directly:
brew search <name>
apt-cache search <name>

Dotfiles & Symlinks

How does Heimdal manage dotfiles?

Heimdal creates symlinks from files in your dotfiles repository to their expected locations in ~:

~/.dotfiles/.vimrc  →  ~/.vimrc (symlink)

Changes to ~/.dotfiles/.vimrc are immediately visible at ~/.vimrc.

What happens if a file already exists?

Heimdal exits with an error and reports the conflict. Resolve with:

heimdal apply --backup   # backs up the existing file, then creates the symlink
heimdal apply --force    # overwrites the existing file

What is the GNU Stow fallback?

If dotfiles: is empty or omitted, Heimdal walks the top level of your dotfiles directory and symlinks everything (depth-1 only), identical to how GNU Stow works. This means existing Stow repositories work with Heimdal without any configuration changes.

Can I ignore certain files?

Yes:

profiles:
  default:
    ignore: [".DS_Store", "*.md", "*.swp"]

Git & Sync

Do I need a Git repository?

For local use, no. For syncing across machines, yes — Git is required.

What does heimdal sync do?

heimdal sync runs:

  1. git pull from the remote
  2. Resolves any conflicts (if needed, prompts you)
  3. heimdal apply

How do I push changes to the remote?

Use heimdal commit --push or push directly with Git:

heimdal commit -m "Update configs" --push
# or
heimdal commit -m "Update configs"
git push

How do I set up automatic sync?

heimdal autosync enable --interval 1h

What if I have Git merge conflicts?

Heimdal surfaces the conflict from git pull. Resolve it with standard Git tools:

vim .vimrc                     # edit the conflicted file
git add .vimrc
git commit
heimdal apply

Profiles

What are profiles?

Profiles are named configurations for different machines or use cases:

profiles:
  work-mac:
    packages:
      homebrew: [kubectl, docker]
  personal-linux:
    packages:
      apt: [steam, gimp]

How do I switch profiles?

heimdal profile switch work-mac
heimdal apply

Can profiles inherit from each other?

Yes, with extends:. When a child extends a parent:

  • packages, dotfiles, templates, ignore are unioned
  • hooks are replaced by the child
profiles:
  default:
    packages:
      common: [git, vim]

  work:
    extends: default          # gets git and vim, plus adds slack
    packages:
      homebrew: [slack]

Secrets & Templates

How do I store secrets securely?

# Store in OS keychain
heimdal secret add github_token --value "ghp_..."

# Use in templates
# {{ secrets.github_token }}

What is the secrets_manifest.json file?

It lives at <dotfiles_path>/.heimdal/secrets_manifest.json and lists the names of secrets required by your setup. It contains no values — only names — so it is safe to commit. It helps you know which secrets to set on a new machine.

Are secrets synced across machines?

No. Secret values are per-machine by design. You must run heimdal secret add on each machine. The names manifest is synced via Git so you know which secrets to set.

What template variables does Heimdal provide automatically?

Variable Description
{{ os }} macos or linux
{{ hostname }} Machine hostname
{{ user }} Current username
{{ home }} Home directory path
{{ env.VAR }} Environment variable VAR
{{ secrets.NAME }} Secret value from keychain

Comparison

Heimdal vs. GNU Stow

Use Heimdal if you want package management, profiles, secrets, or templates alongside symlinks. Use Stow if you only need symlinks and prefer minimal tooling. Heimdal can import Stow setups.

Heimdal vs. chezmoi

Heimdal adds package management and has a simpler, YAML-only config. chezmoi has more templating features (Go templates) and encryption. Heimdal can import chezmoi setups.

Heimdal vs. dotbot

Heimdal adds package management, profiles, and secrets. dotbot is Python-based with a plugin system. Heimdal can import dotbot setups.

Heimdal vs. yadm

Heimdal adds package management and profiles. yadm is Git-native with GPG encryption. Heimdal can import yadm setups.

Getting Help

  1. Documentation: Quick Start, Troubleshooting, Commands Overview
  2. Community: GitHub Issues, Discussions
  3. Debugging: heimdal apply --verbose

How do I report a bug?

  1. Check existing issues
  2. Open a new issue with:
    • Heimdal version: heimdal --version
    • OS: uname -a
    • Sanitized heimdal.yaml
    • Full error message
    • Steps to reproduce

Getting Started

User Guides

CLI Reference

Help

Contributing

Main Repository

Clone this wiki locally