dotfile-sync

name	dotfile-sync
description	Manage dotfiles with symlinks from a central git repository. Use when tracking config files, syncing dotfiles between machines, or bootstrapping a new machine. Triggers include "dotfiles", "sync config", "dfs", "track dotfiles", "symlink config", "new machine setup".

dotfile-sync

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

Quick Start

# Initialize dotfiles repo (new)
dfs init --remote [e-mail]: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 [e-mail]:user/dotfiles.git
dfs link

Track Files

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

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

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

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:

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

# Clone existing dotfiles repo
dfs init --clone [e-mail]:user/dotfiles.git

# Apply a specific profile
dfs link
# or
dfs init --clone [e-mail]:user/dotfiles.git --profile home-linux

Remove Tracking

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