terrylica/cc-skills

chezmoi-workflows

Dotfile backup and sync with chezmoi.

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/terrylica/cc-skills --skill chezmoi-workflows

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

Chezmoi Workflows

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

Use this skill when:

  • Backing up dotfiles to Git repository
  • Syncing configuration files across machines
  • Tracking changes to shell configs, editor settings, or other dotfiles
  • Managing templated configurations with chezmoi
  • Troubleshooting dotfile drift between source and target

Architecture

ComponentLocationPurpose
Source$(chezmoi source-path)Git repository with dotfile templates
Target~/Home directory (deployed files)
RemoteGitHub (private recommended)Cross-machine sync and backup
Config~/.config/chezmoi/chezmoi.tomlUser preferences and settings

1. Status Check

bash
chezmoi source-path                    # Show source directory
chezmoi git -- remote -v               # Show GitHub remote
chezmoi status                         # Show drift between source and target
chezmoi managed | wc -l                # Count tracked files

2. Track File Changes

After editing a config file, add it to chezmoi:

bash
chezmoi status                         # 1. Verify file shows as modified
chezmoi diff ~/.zshrc                  # 2. Review changes
chezmoi add ~/.zshrc                   # 3. Add to source (auto-commits if configured)
chezmoi git -- log -1 --oneline        # 4. Verify commit created
chezmoi git -- push                    # 5. Push to remote

3. Track New File

Add a previously untracked config file:

bash
chezmoi add ~/.config/app/config.toml  # 1. Add file to source
chezmoi managed | grep app             # 2. Verify in managed list
chezmoi git -- push                    # 3. Push to remote

4. Sync from Remote

Pull changes from GitHub and apply to home directory:

bash
chezmoi update                         # 1. Pull + apply (single command)
chezmoi verify                         # 2. Verify all files match source
chezmoi status                         # 3. Confirm no drift

5. Push All Changes

Bulk sync all modified tracked files to remote:

bash
chezmoi status                         # 1. Review all drift
chezmoi re-add                         # 2. Re-add all managed files (auto-commits)
chezmoi git -- push                    # 3. Push to remote

6. First-Time Setup

Install chezmoi

bash
brew install chezmoi                   # macOS

Initialize (fresh start)

bash
/usr/bin/env bash << 'CONFIG_EOF'
chezmoi init                           # Create empty source
chezmoi add ~/.zshrc ~/.gitconfig      # Add first files
gh repo create dotfiles --private --source="$(chezmoi source-path)" --push
CONFIG_EOF

Initialize (clone existing)

bash
chezmoi init git@github.com:<user>/dotfiles.git
chezmoi apply                          # Deploy to home directory

7. Configure Source Directory

Move source to custom location (e.g., for multi-account SSH):

bash
/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
mv "$(chezmoi source-path)" ~/path/to/dotfiles
SKILL_SCRIPT_EOF

Edit ~/.config/chezmoi/chezmoi.toml:

toml
sourceDir = "~/path/to/dotfiles"

Verify:

bash
chezmoi source-path                    # Should show new location

8. Change Remote

Switch to different GitHub account or repository:

bash
chezmoi git -- remote -v                                              # View current
chezmoi git -- remote set-url origin git@github.com:<user>/<repo>.git # Change
chezmoi git -- push -u origin main                                    # Push to new remote

9. Resolve Merge Conflicts

bash
/usr/bin/env bash << 'GIT_EOF'
chezmoi git -- status                  # 1. Identify conflicted files
chezmoi git -- diff                    # 2. Review conflicts
# Manually edit files in $(chezmoi source-path)
chezmoi git -- add <resolved-files>    # 3. Stage resolved files
chezmoi git -- commit -m "Resolve merge conflict"
chezmoi apply                          # 4. Apply to home directory
chezmoi git -- push                    # 5. Push resolution
GIT_EOF

10. Validation (SLO)

After major operations, verify system state:

bash
chezmoi verify                         # Exit 0 = all files match source
chezmoi diff                           # Empty = no drift
chezmoi managed                        # Lists all tracked files
chezmoi git -- log --oneline -3        # Recent commit history

11. Forget (Untrack) a File

Stop tracking a file without deleting it from home directory:

bash
chezmoi managed | grep config.local     # 1. Confirm file is tracked
chezmoi forget --force ~/.config/app/config.local.toml  # 2. Remove from source (--force skips TTY prompt)
chezmoi git -- push                     # 3. Push removal to remote
ls ~/.config/app/config.local.toml      # 4. Verify file still exists in home

When to use: Machine-specific configs, files with secrets that shouldn't be synced, files accidentally added.


12. Template Management

Create OS/architecture-conditional configs using Go templates:

Convert existing file to template

bash
chezmoi add --template ~/.config/app/config.toml  # 1. Add as template (creates .tmpl suffix in source)
chezmoi edit ~/.config/app/config.toml             # 2. Edit template in $EDITOR (helix)
chezmoi diff ~/.config/app/config.toml             # 3. Preview what would change
chezmoi apply ~/.config/app/config.toml            # 4. Apply rendered template to home

Common template patterns

# OS-conditional block
{{ if eq .chezmoi.os "darwin" -}}
export HOMEBREW_PREFIX="/opt/homebrew"
{{ else if eq .chezmoi.os "linux" -}}
export HOMEBREW_PREFIX="/home/linuxbrew/.linuxbrew"
{{ end -}}

# Architecture-conditional
{{ if eq .chezmoi.arch "arm64" -}}
ARCH="aarch64"
{{ else -}}
ARCH="x86_64"
{{ end -}}

# Custom data from chezmoi.toml [data] section
git_name = "{{ .git.name }}"
git_email = "{{ .git.email }}"

# 1Password secret (requires op CLI)
api_key = {{ onepasswordRead "op://Vault/Item/Field" }}

Verify template renders correctly

bash
chezmoi execute-template < "$(chezmoi source-path)/dot_config/app/config.toml.tmpl"
chezmoi cat ~/.config/app/config.toml   # Show rendered output without applying

13. Safe Update (Diff Before Apply)

Pull from remote with review step — safer than blind chezmoi update:

bash
chezmoi git -- pull                    # 1. Pull source changes only (no apply)
chezmoi diff                           # 2. Review what WOULD change in home directory
chezmoi apply --dry-run --verbose      # 3. Dry run — shows actions without executing
chezmoi apply                          # 4. Apply after review
chezmoi status                         # 5. Confirm clean state

When to use: When pulling changes made on another machine, or after a long gap between syncs. Avoids surprise overwrites of local edits.


14. Doctor (Diagnostic)

Troubleshoot chezmoi setup and environment:

bash
chezmoi doctor                         # Full diagnostic — checks all components

Key fields to verify:

CheckExpectedMeaning if failing
config-filefound ~/.config/chezmoi/chezmoi.tomlConfig missing or wrong path
source-dir~/gh/vjspc/dotfiles is a git working tree (clean)Source dirty or not a git repo
git-commandfound /opt/homebrew/bin/gitGit not installed
edit-commandfound /opt/homebrew/bin/hxEditor not configured
1passwordfound /opt/homebrew/bin/op1Password CLI needed for templates
age/gpginfo = optionalOnly needed for encrypted files
bash
chezmoi doctor | grep -v "^ok"         # Show only warnings and errors

Reference

Chezmoi docs: <https://www.chezmoi.io/reference/>


Troubleshooting

IssueCauseSolution
chezmoi not foundNot installedInstall via brew install chezmoi
Source path emptyNot initializedRun chezmoi init
Git remote not setMissing GitHub repoRun chezmoi git -- remote add origin URL
Apply failsTemplate errorCheck template syntax with chezmoi diff
Merge conflictsDiverged source and targetUse chezmoi merge to resolve
Secrets detectedPlain text credentialsUse chezmoi templates with 1Password/Doppler
forget needs TTYInteractive confirmationUse chezmoi forget --force <path>
Template not foundMissing .tmpl suffixUse chezmoi add --template to create .tmpl

Post-Execution Reflection

After this skill completes, check before closing:

  1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
  2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
  3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

aus demselben Repository

Weitere Skills

Alle Skills
terrylica
Community

academic-pdf-to-gfm

Convert academic PDF papers to GitHub-renderable GFM markdown with math equations. TRIGGERS - PDF, GitHub markdown, math

Installationen / 1h
1
GitHub Stars
2
Aktualisiert
5. Nov.
terrylica
Community

adr-code-traceability

Add ADR references to code for traceability. TRIGGERS - ADR traceability, code reference, document decision in code.

Installationen / 1h
1
GitHub Stars
2
Aktualisiert
5. Nov.
terrylica
Community

arxiv-source-first-paper-ingest

Read an arXiv paper faithfully by fetching the authors' own LaTeX source instead of OCR-ing the PDF. Extracts every display equation with its label, environment and enclosing proposition, renders each to MathML, and proves usability by compiling each formula with a real TeX engine. Use when you need a paper's formulas exactly — to replicate a method, implement a loss function or custom objective, verify a quoted number, or check a claim against what the authors actually wrote. TRIGGERS - read th

Installationen / 1h
1
GitHub Stars
2
Aktualisiert
5. Nov.
terrylica
Community

azure-provision

Bootstrap Azure automation when interactive az login is blocked by a Conditional Access policy (error 530035, "Device state: Unregistered"). Mints a service principal through the Azure Portal session ONCE — using Microsoft Graph over a captured token, not DOM clicking — then provisions resource groups, Cognitive Services / AI Language / Speech resources and their keys entirely via az/REST, writing key AND endpoint together into the SCS vault. Use when az login fails but the portal works, when mo

Installationen / 1h
1
GitHub Stars
2
Aktualisiert
5. Nov.