tuck

The modern dotfiles manager

Simple, fast, and beautiful. Manage your dotfiles with Git, sync across machines, and never lose your configs again.

Website · Wiki · Install · Quick Start

---

Why tuck?

• One command to rule them all — tuck init scans your system, lets you pick what to track, and syncs to your remote
• Multi-provider support — GitHub, GitLab (including self-hosted), Gitea, local-only, or any custom git remote
• Smart detection — auto-categorizes dotfiles (shell, git, editors, terminal, ssh, etc.)
• Beautiful CLI — gorgeous prompts, spinners, and progress bars powered by @clack/prompts
• Safe by default — creates snapshots before every destructive operation, never overwrites without asking
• Git-native — uses Git under the hood but hides the complexity
• Cross-platform — works on macOS, Linux, and Windows

Install

# One-liner install script — auto-detects platform, verifies SHA256
curl -fsSL https://raw.githubusercontent.com/stanrc85/tuck/main/install.sh | bash

# Or install the latest release via npm (tarball ships pre-built)
npm install -g https://github.com/stanrc85/tuck/releases/latest/download/tuck.tgz

# Pin to a specific release
npm install -g https://github.com/stanrc85/tuck/releases/download/v1.0.2/tuck.tgz

# Prebuilt standalone binaries also live at
# https://github.com/stanrc85/tuck/releases

Quick Start

First time

# Interactive — scans your system, pick what to track, syncs to GitHub
tuck init

tuck init asks where to store the repo (GitHub / GitLab / local / custom), creates ~/.tuck/, scans for dotfiles, lets you pick, commits, and pushes. See the Getting Started guide for the full walkthrough.

Ongoing

tuck sync

Detects changes, pulls latest from the remote, commits, pushes — all in one loop.

On a new machine

tuck init --from github.com/you/dotfiles     # point tuck at your repo
tuck restore --all                           # write every tracked file back
tuck bootstrap --bundle <your-bundle>        # install the CLI tools they expect

Or apply someone else's public dotfiles: tuck apply <github-user>.

Top commands

Command	What it does
tuck init	First-time setup — scan, pick, sync
tuck sync	Detect + commit + push changes (pulls first)
tuck status	What's tracked, what's changed
tuck add <paths>	Start tracking files
tuck remove --push <paths>	Stop tracking + delete from remote
tuck diff	Preview changes (-s side-by-side, --stat bar graph)
tuck restore --all	Write repo → system
tuck undo	Roll back the last destructive op

Full list with flags and examples: Command Reference.

Where to go next

If you want to…	Read
Walk through your first sync	Getting Started
Find the exact flag for a command	Command Reference
Run one repo across several machines	Host Groups
Install your CLI tools on a fresh host	Bootstrapping Tools
Configure tuck (.tuckrc.json)	Configuration Reference
Roll back a mistake	Time Machine & Undo
Use self-hosted GitLab / Gitea / custom	Git Providers
Keep secrets out of your repo	Security & Secrets
Run code before/after sync/restore	Hooks
Solve a specific task	Recipes

The full wiki landing page: github.com/stanrc85/tuck/wiki.

How tuck stores your dotfiles

~/.tuck/
├── files/
│   ├── shell/       # .zshrc, .bashrc, .profile
│   ├── git/         # .gitconfig, .gitignore_global
│   ├── editors/     # .vimrc, nvim, VS Code settings
│   ├── terminal/    # .tmux.conf, alacritty, kitty
│   ├── ssh/         # ssh config (never private keys)
│   └── misc/        # everything else
├── .tuckmanifest.json
└── .tuckrc.json

~/.zshrc          →  ~/.tuck/files/shell/zshrc
~/.gitconfig      →  ~/.tuck/files/git/gitconfig
~/.config/nvim    →  ~/.tuck/files/editors/nvim

Development

git clone https://github.com/stanrc85/tuck.git
cd tuck
pnpm install
pnpm build
pnpm test

Deeper contributor docs: CLAUDE.md, AGENTS.md, and docs/ for testing, benchmarking, and error-code reference. Wiki content is edited under docs/wiki/ — see docs/wiki-sync.md for the editor's guide.

Contributing

Contributions welcome. Please read CONTRIBUTING.md and submit PRs against main.

License

MIT — see LICENSE.

---

_{Made with love in San Francisco and State College}