dotfiles-manage

---

name: dotfiles-manage

description: "Use when the user wants their config files (shell, editor, git, tmux) versioned in git and deployable to a new machine in one command, or wants to sync dotfiles across multiple machines."

version: 1.0.0

author: Hermes Agent

license: MIT

metadata:

  hermes:

    tags: [dotfiles, git-bare-repo, gnu-stow, chezmoi, yadm, config-sync]

    related_skills: [env-config-manager, git-backup]

---



# dotfiles-manage



## Overview



Set up dotfiles management — version control for your configuration files (shell config, editor config, git config, etc.) with the ability to deploy them to any new machine in one command.



## When to Use



- The user wants their config files versioned and backed up.

- The user is setting up a new machine and wants their configs deployed automatically.

- The user wants to sync configs across multiple machines.

- The user says "set up dotfiles", "version my configs", or "I want my settings on my new laptop".



## Strategies



Four approaches, ranked by simplicity:



| Strategy | How it works | Best for |

|---|---|---|

| **Git bare repo** | A bare git repo stores dotfiles; alias manages add/commit | Minimalists, no extra tools |

| **GNU Stow** | Symlinks from a directory to your home dir | Organized by package, standard tool |

| **chezmoi** | Templated dotfiles with encryption and machine-specific values | Multiple machines with different needs |

| **yadm** | Yet Another Dotfiles Manager — git wrapper for home dir | Git-familiar users who want extras |



## Strategy 1: Git Bare Repo (simplest)



No extra software needed — just git.



### Setup



```bash

# Create a bare repo

git init --bare $HOME/.cfg



# Add an alias to your shell config

echo "alias config='/usr/bin/git --git-dir=\$HOME/.cfg/ --work-tree=\$HOME'" >> ~/.bashrc

source ~/.bashrc



# Ignore untracked files in your home dir

config config --local status.showUntrackedFiles no

```



### Add files



```bash

config add .bashrc .vimrc .gitconfig .tmux.conf

config commit -m "Initial dotfiles"

config remote add origin git@github.com:youruser/dotfiles.git

config push -u origin main

```



### Deploy on a new machine



```bash

# Clone as bare repo

git clone --bare git@github.com:youruser/dotfiles.git $HOME/.cfg



# Add the alias

echo "alias config='/usr/bin/git --git-dir=\$HOME/.cfg/ --work-tree=\$HOME'" >> ~/.bashrc

source ~/.bashrc



# Checkout the files

config checkout



# If it fails because files already exist, back them up first:

mkdir -p .config-backup

config checkout 2>&1 | grep "\t" | awk {'print $1'} | xargs -I{} mv {} .config-backup/{}

config checkout



# Set ignore

config config --local status.showUntrackedFiles no

```



## Strategy 2: GNU Stow



Organizes dotfiles into "packages" and symlinks them into your home directory.



### Setup



```bash

# Install stow

# Linux: apt install stow / pacman -S stow

# macOS: brew install stow



# Create a dotfiles directory

mkdir ~/dotfiles

cd ~/dotfiles



# Organize by package (each package is a directory)

mkdir -p bash vim git tmux



# Move configs into the package directories

mv ~/.bashrc ~/dotfiles/bash/.bashrc

mv ~/.vimrc ~/dotfiles/vim/.vimrc

mv ~/.gitconfig ~/dotfiles/git/.gitconfig



# Stow (create symlinks)

stow bash vim git



# Verify

ls -la ~/.bashrc  # → ~/dotfiles/bash/.bashrc

```



### Deploy on a new machine



```bash

git clone git@github.com:youruser/dotfiles.git ~/dotfiles

cd ~/dotfiles

stow bash vim git tmux

```



### Remove a package



```bash

stow -D vim  # removes the symlinks for the vim package

```



## Strategy 3: chezmoi (for multiple machines with differences)



chezmoi handles machine-specific values, templating, and secrets.



### Setup



```bash

# Install

# Linux: snap install chezmoi --classic / or download

# macOS: brew install chezmoi



# Initialize

chezmoi init



# Add a file

chezmoi add ~/.bashrc

chezmoi add ~/.gitconfig



# Edit managed files

chezmoi edit ~/.bashrc



# Apply changes to your home dir

chezmoi apply



# Push to git

chezmoi cd

git add -A

git commit -m "Initial dotfiles"

git remote add origin git@github.com:youruser/dotfiles.git

git push -u origin main

```



### Deploy on a new machine



```bash

chezmoi init git@github.com:youruser/dotfiles.git

chezmoi apply

```



### Machine-specific values



```bash

# Template file (chezmoi edit ~/.gitconfig)

[user]

    name = {{ .name }}

    email = {{ .email }}



# Set values per machine

chezmoi data --format json  # see current values

# Edit config:

chezmoi edit-config

# Add:

# data:

#   name: "Your Name"

#   email: "your@email.com"

```



## Managing Different OSes



For configs that differ between Linux and macOS:



**chezmoi:**

```bash

# OS-specific files are named with .linux_ or .darwin_ prefix

# chezmoi automatically picks the right one

```



**Git bare repo / Stow:**

```bash

# Use conditionals in your shell config:

if [ "$(uname)" = "Darwin" ]; then

    # macOS-specific settings

elif [ "$(uname)" = "Linux" ]; then

    # Linux-specific settings

fi

```



## Secrets in Dotfiles



Never commit plaintext secrets (API keys, tokens, passwords).



| Method | How |

|---|---|

| **chezmoi encryption** | `chezmoi add --encrypt ~/.config/secrets` — encrypts with age or gpg |

| **Env vars** | Store secrets in a file that's gitignored, load via shell config |

| **Password manager** | Reference secrets from `pass`, `1password-cli`, or `bitwarden-cli` in config |



```bash

# Example: load API key from password manager in .bashrc

export OPENAI_API_KEY=$(pass openai/api-key)

```



## Common Pitfalls



1. **Committing secrets** — Before pushing, check for API keys, tokens, and passwords in your dotfiles. Use `git log -p` to review history. If secrets are already pushed, rotate them immediately — git history is forever.

2. **Symlink loops with Stow** — If you stow a directory that contains a symlink pointing back to your home dir, you'll create a loop. Stow will warn you, but check manually.

3. **Bare repo checkout fails** — If files already exist in your home dir, `config checkout` fails. Back up the conflicting files first (the deploy script above handles this).

4. **Different paths on different OSes** — A config that works on Linux (`~/.config/`) may need a different path on macOS (`~/Library/Application Support/`). Use chezmoi for cross-OS setups, or conditional logic in shell configs.

5. **Forgetting to stow/restow** — After adding a new file to a Stow package, you need to re-run `stow <package>` to create the symlink. It's not automatic.

6. **Machine-specific values in git** — If you hardcode a machine-specific value (hostname, IP, path) in a dotfile, it breaks on other machines. Use templates (chezmoi) or conditionals.



## Verification Checklist



- [ ] `config status` / `git -C ~/dotfiles status` (or `stow -n`/`chezmoi diff`) shows no unexpected changes after setup

- [ ] A clean-machine deploy (fresh clone + checkout/`stow`/`chezmoi apply`) reproduces the expected files or symlinks

- [ ] `git log -p` reviewed for accidentally committed secrets before the first push

- [ ] `status.showUntrackedFiles` is set to `no` for the bare-repo approach so `git status`/`config status` in `$HOME` stays quiet

# dotfiles-manage



Version and sync your configuration files across machines with git — deploy to any new machine in one command.



## What it does



The agent sets up a dotfiles management system using one of four strategies (git bare repo, GNU Stow, chezmoi, or yadm). Your config files get versioned in a git repo, and you can deploy them to any new machine by cloning and running one command. No more manually copying `.bashrc` to a new laptop.



## Install



```bash

hermes skills install https://raw.githubusercontent.com/THEROCKSSS/hermes-skills-portfolio/main/skills/dotfiles-manage/SKILL.md

```



## How to use



```

"Set up dotfiles management for my shell, vim, and git configs"

```



The agent:

1. Recommends a strategy based on your needs (bare repo for simplicity, chezmoi for multiple machines)

2. Sets up the repo structure

3. Adds your config files

4. Pushes to a git remote

5. Shows you the one-command deploy for new machines



## Strategies



| Strategy | Needs | Best for |

|---|---|---|

| Git bare repo | Just git | Minimalists |

| GNU Stow | stow installed | Organized by package |

| chezmoi | chezmoi installed | Multiple machines, templated configs |

| yadm | yadm installed | Git-familiar, wants extras |



## Example



```

User: "I just got a new laptop. I want my configs from my old machine."



Agent:

  1. On old machine: sets up git bare repo at ~/.cfg

  2. Adds: .bashrc, .vimrc, .gitconfig, .tmux.conf

  3. Pushes to github.com/youruser/dotfiles

  4. On new machine: git clone --bare ... ~/.cfg

  5. Runs: config checkout

  6. Returns: "Your configs are now on the new machine."

```