dotfile-sync

# dotfile-sync

CLI tool for tracking and syncing dotfiles via a git-backed symlink repository.

## Quick Start

```bash
# Initialize dotfiles repo (new)
dfs init --remote git@github.com:user/dotfiles.git

# Track a file
dfs add ~/.zshrc
dfs add ~/.gitconfig

# Push to remote
dfs push

# On a new machine: clone and link everything
dfs init --clone git@github.com:user/dotfiles.git
dfs link
```

## Track Files

```bash
dfs add ~/.zshrc                               # track file
dfs add ~/.config/nvim/init.lua                # nested path supported
dfs add ~/.config/work/config --profile work-mac  # add to specific profile
```

## List and Status

```bash
dfs list                    # all tracked files with symlink status
dfs status                  # overall health: linked count, git status
```

Status symbols:
- `ok` - file is correctly symlinked
- `*` - file needs linking (unlinked)
- `x` - conflict (file exists but is not a repo symlink)
- `?` - missing (symlink target not in repo)

## Link and Unlink

```bash
dfs link                    # create all missing symlinks
dfs link --force            # overwrite conflicting files
dfs link ~/.zshrc           # link specific file
dfs unlink                  # remove all symlinks (files remain tracked)
```

## Sync with Remote

```bash
dfs push                    # git add + commit + push
dfs push --message "add nvim config"   # custom commit message
dfs pull                    # git pull + re-link new files
dfs diff                    # show uncommitted changes
dfs diff ~/.zshrc           # diff specific file
```

## Machine Profiles

Profiles group files for specific machines:

```bash
dfs profile list                            # all profiles
dfs profile create work-mac                 # create profile
dfs profile add work-mac ~/.config/work     # add file to profile
dfs profile apply work-mac                  # link only this profile's files
```

The `common` profile includes all files with no profile assignment (linked on all machines).

## Bootstrap New Machine

```bash
# Clone existing dotfiles repo
dfs init --clone git@github.com:user/dotfiles.git

# Apply a specific profile
dfs link
# or
dfs init --clone git@github.com:user/dotfiles.git --profile home-linux
```

## Remove Tracking

```bash
dfs remove ~/.zshrc         # stop tracking, restore original file
```

## CLI Reference

| Command | Description |
|---|---|
| `init` | Initialize dotfiles repo |
| `add <file>` | Track a file |
| `remove <file>` | Stop tracking a file |
| `list` | List tracked files with status |
| `status` | Overall sync status |
| `link [file]` | Create symlinks |
| `unlink [file]` | Remove symlinks |
| `push` | Commit and push changes |
| `pull` | Pull and re-link |
| `diff [file]` | Show uncommitted changes |
| `profile` | Manage machine profiles |

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `DFS_REPO_PATH` | `~/dotfiles` | Dotfiles repository path |
| `DFS_NO_COLOR` | `0` | Disable ANSI color (1 to disable) |
| `DFS_DEBUG` | `0` | Enable debug logging (1 to enable) |

## Exit Codes

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | File not tracked |
| 2 | Conflict (file exists, not a symlink) |
| 3 | Runtime error |