chezmoi-chef

# Chezmoi Dotfile Management

Chezmoi manages dotfiles across machines with templating, encryption, and password manager integration.

## Quick Reference

```bash
chezmoi init                    # Initialize
chezmoi add ~/.bashrc           # Add file
chezmoi add --template ~/.zshrc # Add as template
chezmoi add --encrypt ~/.secret # Add encrypted
chezmoi edit ~/.bashrc          # Edit and apply
chezmoi apply                   # Apply all changes
chezmoi diff                    # Preview changes
chezmoi update                  # Pull and apply
chezmoi cd                      # Shell in source dir
```

## Core Workflows

### Initialize on New Machine

From GitHub:
```bash
chezmoi init --apply github-username
```

One-liner install + init:
```bash
sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply github-username
```

### Add Files to Management

```bash
chezmoi add ~/.bashrc ~/.zshrc ~/.gitconfig    # Multiple files
chezmoi add -r ~/.config/nvim                  # Directory
chezmoi add --template ~/.bashrc               # As template
chezmoi add --encrypt ~/.ssh/id_rsa            # Encrypted
```

### Edit Managed Files

```bash
chezmoi edit ~/.bashrc          # Opens source file
chezmoi edit --apply ~/.bashrc  # Auto-apply after save
```

### Sync Changes

```bash
chezmoi cd                      # Enter source directory
git add . && git commit -m "update dotfiles" && git push
exit
chezmoi apply                   # Apply locally
```

Or use chezmoi's git wrapper:
```bash
chezmoi git add .
chezmoi git commit -m "update"
chezmoi git push
```

## Templating

Create machine-specific configs. See [templates.md](references/templates.md) for full guide.

Convert to template:
```bash
chezmoi add --template ~/.bashrc
# or
chezmoi chattr +template ~/.bashrc
```

Common patterns:

```bash
# OS-specific
{{ if eq .chezmoi.os "darwin" -}}
export PATH="/opt/homebrew/bin:$PATH"
{{- else if eq .chezmoi.os "linux" -}}
export PATH="/home/linuxbrew/.linuxbrew/bin:$PATH"
{{- end }}

# Hostname-specific
{{ if eq .chezmoi.hostname "work-laptop" -}}
export HTTP_PROXY="http://proxy.company.com:8080"
{{- end }}

# Distro-specific (Linux)
{{ if eq .chezmoi.osRelease.id "fedora" -}}
alias update="sudo dnf upgrade"
{{- else if eq .chezmoi.osRelease.id "ubuntu" -}}
alias update="sudo apt update && sudo apt upgrade"
{{- end }}
```

Custom variables in `~/.config/chezmoi/chezmoi.toml`:
```toml
[data]
  email = "user@example.com"
  editor = "nvim"
```

Test templates:
```bash
chezmoi execute-template '{{ .chezmoi.os }}'
chezmoi data  # Show all variables
chezmoi cat ~/.bashrc  # Show rendered output
```

## Secrets Management

Integrate password managers to avoid committing secrets. See [password-managers.md](references/password-managers.md) for all integrations.

### 1Password Example

Config (`~/.config/chezmoi/chezmoi.toml`):
```toml
[onepassword]
  command = "op"
  prompt = true
```

Template:
```bash
export GITHUB_TOKEN='{{ onepasswordRead "op://Personal/github/token" }}'
export AWS_ACCESS_KEY='{{ onepasswordRead "op://Work/aws/access-key" }}'
```

### Bitwarden Example

```bash
export API_KEY='{{ (bitwarden "item" "api-credentials").login.password }}'
```

### pass Example

```bash
export SECRET='{{ pass "path/to/secret" }}'
```

## Encryption

Encrypt sensitive files stored in source directory.

### Setup with age

```bash
chezmoi age keygen -o ~/.config/chezmoi/key.txt
```

Config:
```toml
encryption = "age"
[age]
  identity = "~/.config/chezmoi/key.txt"
  recipient = "age1..." # Public key from keygen output
```

### Add Encrypted Files

```bash
chezmoi add --encrypt ~/.ssh/id_rsa
chezmoi add --encrypt ~/.aws/credentials
```

Files stored with `encrypted_` prefix, decrypted on apply.

## Run Scripts

Execute scripts during apply for setup tasks.

Create in source directory:
```bash
chezmoi cd
```

Script naming:
- `run_once_install.sh` - Run once ever
- `run_onchange_setup.sh` - Run when script changes
- `run_always.sh` - Run every apply

Example `run_once_install-packages.sh`:
```bash
#!/bin/bash
{{ if eq .chezmoi.os "darwin" -}}
brew install ripgrep fd bat
{{- else if eq .chezmoi.osRelease.id "fedora" -}}
sudo dnf install -y ripgrep fd-find bat
{{- end }}
```

## Command Reference

See [commands.md](references/commands.md) for complete command list.

## Troubleshooting

```bash
chezmoi doctor    # Check configuration
chezmoi verify    # Verify targets match source
chezmoi diff      # See pending changes
chezmoi status    # File status overview
chezmoi --debug apply  # Verbose output
```

Reset run_once scripts:
```bash
chezmoi state delete-bucket --bucket=scriptState
```