# dotfiles

> Manage dotfiles - installation, updates, adding configs, troubleshooting symlinks. Use when asked about dotfiles, system config, or shell setup.

- Author: Sapan Upadhyay
- Repository: thebrokencube/files-with-a-dot
- Version: 20260131111201
- Stars: 1
- Forks: 1
- Last Updated: 2026-02-06
- Source: https://github.com/thebrokencube/files-with-a-dot
- Web: https://mule.run/skillshub/@@thebrokencube/files-with-a-dot~dotfiles:20260131111201

---

---
name: dotfiles
description: Manage dotfiles - installation, updates, adding configs, troubleshooting symlinks. Use when asked about dotfiles, system config, or shell setup.
---

# Dotfiles Management

## Commands
- `/dotfiles` - Show status and help
- `/dotfiles install` - Run full installation
- `/dotfiles update` - Pull latest and update
- `/dotfiles health` - Run diagnostics
- `/dotfiles setup` - Interactive first-time setup guide
- `/dotfiles add <app>` - Add new config

## How the System Works

**Symlink-based**: `~/.dotfiles/symlink_map.txt` defines source → destination mappings.

```
shared/git/.gitconfig:$HOME/.gitconfig
shared/nvim/.config/nvim:$HOME/.config/nvim
shared/iterm2/dotfiles-profile.json:$HOME/Library/Application Support/iTerm2/DynamicProfiles/dotfiles-profile.json
```

**Scripts**:
- `install.sh` - Full install with conflict detection, backups
- `update.sh` - Pull, re-link, update Homebrew
- `health.sh` - Diagnose issues, `--fix` to auto-repair
- `uninstall.sh` - Clean removal

**Multi-machine**: `~/.dotfiles/.machine` contains `home` or `work`
- `shared/` configs apply everywhere
- `home/Brewfile` only on home machines

## To Show Status (`/dotfiles`)
1. Read `~/.dotfiles/.machine` for machine type
2. Check key symlinks exist (from symlink_map.txt)
3. Show available commands

## To Add New Config (`/dotfiles add <app>`)
1. Create directory: `~/.dotfiles/shared/<app>/`
2. Add config files mirroring target structure
3. Add entry to `symlink_map.txt`: `shared/<app>/config:$HOME/.config/<app>/config`
4. Run `./update.sh --links-only`

## First-Time Setup (`/dotfiles setup`)
Run `~/.dotfiles/health.sh --setup` for interactive walkthrough:
1. Shell reload
2. Neovim plugin installation
3. iTerm2 profile selection
4. API key configuration (home only)
5. Git identity setup

## Troubleshooting
- **Symlink conflicts**: `./install.sh --dry-run` shows state
- **Broken links**: `./health.sh --fix` repairs them
- **Changes not applied**: Run `./update.sh --links-only`
- **First-time issues**: Run `./health.sh --setup` for guided help