# dotfiles-sync

> Keep local and server versions of dotfiles aligned while preserving intentional machine-specific differences. PROACTIVELY use when: (1) user says "sync dotfiles", "align dotfiles", "check dotfiles", (2) after editing a .local or .server file, (3) when dotsync is run, (4) periodically after dotfile edits. Analyzes paired files, identifies sync candidates vs intentional differences.

- Author: Cole Tebou
- Repository: coletebou/claude-code
- Version: 20260125145526
- Stars: 1
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/coletebou/claude-code
- Web: https://mule.run/skillshub/@@coletebou/claude-code~dotfiles-sync:20260125145526

---

---
name: dotfiles-sync
description: >
  Keep local and server versions of dotfiles aligned while preserving intentional
  machine-specific differences. PROACTIVELY use when: (1) user says "sync dotfiles",
  "align dotfiles", "check dotfiles", (2) after editing a .local or .server file,
  (3) when dotsync is run, (4) periodically after dotfile edits.
  Analyzes paired files, identifies sync candidates vs intentional differences.
allowed-tools: Read, Edit, Write, Bash, Glob, Grep
---

# Dotfiles Sync

Keep local and server versions of dotfiles aligned while preserving intentional machine-specific differences.

## Quick Start

1. **Review recent changes** - Read last 3 commits to dotfiles repo for context
2. **Run permissions-cleaner** - Clean and optimize Claude permissions before syncing
3. Scan `~/.dotfiles/` for paired files (`*.local` + `*.server`)
4. Compare each pair and categorize differences
5. Identify intentional differences (preserve) vs sync candidates (propagate)
6. Interactive sync: ask user which direction for each candidate
7. Apply changes
8. **Run `dotsync`** - Push all changes to the dotfiles repo and sync

## Dotfiles Structure

```
~/.dotfiles/
├── bash_aliases.local    ←→  bash_aliases.server
├── bashrc.local          ←→  bashrc.server
├── profile.local         ←→  profile.server
├── gitconfig             # Shared (no variants)
├── tmux.conf             # Shared (no variants)
└── claude/settings.json  # Shared (no variants)
```

## Paired Files

Files with `.local` and `.server` suffixes are paired:
- `.local` = Local development machine (WSL, personal PC)
- `.server` = Production server (Hetzner, cloud)

See `references/paired-files.md` for the complete list.

## Analysis Workflow

### Step 1: Review Recent Changes

**First, understand what changed recently in the dotfiles repo.**

```bash
cd ~/.dotfiles && git log --oneline -3 --stat
```

This provides context for:
- What was recently synced
- What might be out of sync
- Any changes made on other machines

If changes were made on another machine, pull first:
```bash
cd ~/.dotfiles && git pull
```

### Step 2: Run Permissions Cleaner

**Before syncing dotfiles, clean permissions first.**

Invoke the `permissions-cleaner` skill to:
- Audit global, project, and local Claude settings
- Remove duplicate permissions
- Consolidate overly-specific patterns
- Warn about dangerous permissions

This ensures `~/.dotfiles/claude/settings.json` is optimized before syncing.

### Step 3: Discovery

```bash
# Find all paired files
cd ~/.dotfiles
for f in *.local; do
  base="${f%.local}"
  if [ -f "${base}.server" ]; then
    echo "Pair: $f ↔ ${base}.server"
  fi
done
```

### Step 4: Diff Analysis

For each pair, categorize differences:

| Category | Action | Example |
|----------|--------|---------|
| Intentional | Preserve | WSL display config, server systemd |
| Sync Candidate | Propagate | New alias added to one file |
| Drift | Review | Same function, different implementation |

### Step 5: Intentional Difference Detection

See `references/intentional-patterns.md` for patterns to preserve:
- Machine-specific paths (`/home/<server-user>/` vs `/home/<user>/`)
- WSL-specific (WSLg, Windows paths, display)
- Server-specific (systemd, SSH hardening, production vars)
- Hardware-specific (GPU, audio, input devices)
- Hostname references

### Step 6: Sync Recommendations

**Sync candidates**:
- New aliases/functions added to one file
- Bug fixes that apply to both
- Updated logic with improved implementation
- New exports/PATH additions

### Step 7: Interactive Sync

For each sync candidate:
1. Show the diff
2. Ask: local→server, server→local, or skip?
3. Apply chosen direction
4. Continue to next candidate

### Step 8: Apply and Sync

**MUST run `dotsync` after all changes are complete.**

```bash
dotsync  # Push changes to dotfiles repo and sync
```

This step is **mandatory** - it:
1. Commits all dotfile changes
2. Pushes to the dotfiles repository
3. Syncs changes to symlinked locations

Never skip this step. If changes were made but not synced, they won't propagate.

## Output Format

```markdown
## Dotfiles Sync Report

### 📁 bash_aliases.local ↔ bash_aliases.server

#### ✅ Intentional Differences (preserved)
- Line 42: WSL display config (local only)
- Line 87: Production API keys (server only)
- Line 150: `/home/<user>/` vs `/home/<server-user>/` paths

#### 🔄 Sync Candidates
- Function `gclean()`: Added in local (lines 120-125), missing in server
  → Sync to server? [y/n/skip]
- Alias `ll`: Updated in server, local has older version
  → Sync to local? [y/n/skip]

#### ⚠️ Drift Detected (manual review)
- `PATH` construction differs slightly
- Export ordering changed
```

## Function Comparison

To detect new/modified functions:

```bash
# Extract function names from bash file
grep -E "^[a-zA-Z_][a-zA-Z0-9_]*\s*\(\)" file.local | sort > /tmp/local_funcs
grep -E "^[a-zA-Z_][a-zA-Z0-9_]*\s*\(\)" file.server | sort > /tmp/server_funcs

# Find unique to each
comm -23 /tmp/local_funcs /tmp/server_funcs  # Only in local
comm -13 /tmp/local_funcs /tmp/server_funcs  # Only in server
```

## Alias Comparison

```bash
# Extract aliases
grep "^alias " file.local | sort > /tmp/local_aliases
grep "^alias " file.server | sort > /tmp/server_aliases

# Compare
diff /tmp/local_aliases /tmp/server_aliases
```

## Safety Rules

1. **Run permissions-cleaner first** - Always clean permissions before dotfiles sync
2. **Never auto-merge** - Always ask user for sync direction
3. **Preserve intentional differences** - Don't touch machine-specific configs
4. **Show full diff** before applying any change
5. **Backup before editing** - Create `.bak` files
6. **MUST run `dotsync` at end** - Changes don't propagate until synced