doctor

​

Usage

chezmoi doctor

​

Description

• Version information: chezmoi version, Go version, OS/arch
• Configuration: Config file location and validity
• Directories: Source, working tree, and destination directories
• VCS: Git repository status (clean, dirty, or error)
• Tools: Editor, shell, diff, merge, and git commands
• Encryption: age, GPG, and other encryption tools
• Secret managers: 1Password, Bitwarden, LastPass, etc.
• System capabilities: Symlinks, hard links

• ok - Check passed
• info - Informational message (not a problem)
• warning - Potential issue (chezmoi will still work)
• error - Problem that needs to be fixed
• skipped - Check was skipped (e.g., no network for version check)
• failed - Check could not be completed

​

Flags

​

Examples

​

Run a full health check

chezmoi doctor

​

Run without network access

chezmoi doctor --no-network

​

Check exit code

if chezmoi doctor; then
    echo "All checks passed"
else
    echo "Issues detected"
fi

​

Terminal Output

$ chezmoi doctor
RESULT   CHECK                MESSAGE
ok       version              v2.46.1, commit abc1234, built at 2024-01-15T10:30:00Z
ok       latest-version       v2.46.1
ok       os-arch              linux/amd64 (Ubuntu 22.04)
ok       go-version           go1.21.5 (gc)
ok       executable           /usr/local/bin/chezmoi
ok       upgrade-method       snap-refresh
ok       config-file          found ~/.config/chezmoi/chezmoi.toml, last modified 2024-01-10T14:22:30Z
ok       source-dir           ~/.local/share/chezmoi is a git working tree (clean)
ok       working-tree         ~/.local/share/chezmoi is a directory
ok       dest-dir             ~ is a directory
ok       cd-command           found /bin/bash
ok       cd-args              /bin/bash
info     diff-command         not set
ok       edit-command         found /usr/bin/vim
ok       edit-args            /usr/bin/vim
ok       git-command          found /usr/bin/git, version 2.39.2
warning  merge-command        not set
ok       shell-command        found /bin/zsh
ok       shell-args           /bin/zsh
warning  age-command          not set
info     gpg-command          found /usr/bin/gpg, version 2.2.27
info     1password-command    found /usr/bin/op, version 2.18.0
info     bitwarden-command    not set

​

Check Descriptions

​

Version Checks

• Shows chezmoi version, commit, and build date
• warning if version information is incomplete

• Compares installed version with latest GitHub release
• warning if a newer version is available
• skipped with --no-network

• Shows Go version used to build chezmoi

• Shows operating system and architecture
• Includes OS release information if available

​

Executable Checks

• Shows path to chezmoi binary

• Shows detected upgrade method (e.g., brew-upgrade, snap-refresh)
• Helps determine how to upgrade chezmoi

​

Configuration Checks

• Validates config file exists and is readable
• Shows path and last modification time
• info if config file doesn’t exist (optional)
• error if config file is invalid

​

Directory Checks

• Verifies source directory exists
• Shows git status if it’s a repository:
  • (clean) - No uncommitted changes
  • (dirty) - Uncommitted changes present
  • (error) - Git error

• Verifies working tree directory exists

• Verifies destination directory exists

​

Tool Checks

• error if not found and required
• Shows path and version if available

• info if not set (optional tools)
• warning if set but not found

• warning if not found
• Shows version if found

​

Encryption Tool Checks

• info if not found (optional)
• Shows version if found

• Used by GPG for password entry
• info if not set
• warning if set but not found

​

Secret Manager Checks

• info if not found (optional)
• Shows version if found
• error if found but version is too old

​

System Capability Checks

• Tests if symbolic links can be created
• failed if symlinks not supported

• Tests if hard links can be created

• Shows current umask value

​

Common Issues

​

Config file not found

info     config-file          ~/.config/chezmoi/chezmoi.toml: not found

chezmoi edit-config

​

Dirty working tree

warning  source-dir           ~/.local/share/chezmoi is a git working tree (dirty)

chezmoi cd
git status
git add .
git commit -m "Update"

​

Outdated version

warning  latest-version       v2.47.0

chezmoi upgrade

​

Tool not found

warning  git-command          git not found in $PATH

# Ubuntu/Debian
sudo apt install git

# macOS
brew install git

# Fedora
sudo dnf install git

​

Minimum version not met

error    gopass-command       found /usr/bin/gopass, version 1.12.0, need 1.14.0

​

Troubleshooting Workflow

# 1. Run doctor
chezmoi doctor

# 2. Review errors and warnings
# Fix any issues

# 3. Verify fixes
chezmoi doctor

# 4. Test chezmoi functionality  
chezmoi apply --dry-run --verbose

​

CI/CD Usage

​

Verify environment

- name: Verify chezmoi environment
  run: |
    chezmoi doctor
    chezmoi doctor --no-network

​

Fail on warnings

#!/bin/bash
output=$(chezmoi doctor 2>&1)
echo "$output"

if echo "$output" | grep -q "error\|warning"; then
    echo "Doctor found issues"
    exit 1
fi

​

Saving Output

​

Save for bug reports

chezmoi doctor > chezmoi-doctor.txt 2>&1

​

Redact sensitive information

chezmoi doctor | sed "s|$HOME|~|g"

​

Related Commands

• upgrade - Upgrade chezmoi to the latest version
• init - Initialize chezmoi