@okirmio-create/dotfile-sync-cli

Dotfiles synchronization tool. Manages symlinks between a dotfiles repository and your home directory.

Install

npm install -g @okirmio-create/dotfile-sync-cli

Or run directly after building:

npm install && npm run build
node dist/index.js --help

Usage

Initialize

Point the tool at your dotfiles repository. It will auto-discover dotfiles (files starting with .) in the root of the repo.

dotfile-sync init ~/dotfiles

This creates a .dotfile-sync.json config in the current directory.

Link

Create symlinks from the repo to your home directory. Existing files are backed up with a .dotfile-backup suffix.

dotfile-sync link

Unlink

Remove all managed symlinks. If a .dotfile-backup file exists, it is restored.

dotfile-sync unlink

Status

Show the state of every tracked dotfile:

dotfile-sync status

Output statuses:

• LINKED — symlink points to the repo file
• UNLINKED — target does not exist
• MISSING — source file missing from repo
• MODIFIED — a real (non-symlink) file exists at the target
• CONFLICT — symlink exists but points elsewhere

Add

Move an existing file into the repo and create a symlink back. Registers it in the config.

dotfile-sync add ~/.bashrc
dotfile-sync add ~/.vimrc

List

List all tracked dotfiles and their mappings:

dotfile-sync list

Config file

.dotfile-sync.json supports custom mappings:

{
  "repoDir": "/home/user/dotfiles",
  "mappings": [
    { "source": ".bashrc", "target": "~/.bashrc" },
    { "source": ".vimrc",  "target": "~/.vimrc"  },
    { "source": ".tmux.conf", "target": "~/.tmux.conf" }
  ]
}

You can add entries manually for files outside your home directory by using absolute paths in target.

Workflow example

# 1. Create / clone your dotfiles repo
mkdir ~/dotfiles
cp ~/.bashrc ~/dotfiles/

# 2. Initialize tracking
cd ~/projects
dotfile-sync init ~/dotfiles

# 3. Link everything
dotfile-sync link

# 4. Check status
dotfile-sync status

# 5. Add a new file any time
dotfile-sync add ~/.gitconfig

License

MIT