# tuck

The modern dotfiles manager

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


Website · Install · Quick Start · Commands

---

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), 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 backups before every operation, never overwrites without asking
- Git-native — Uses Git under the hood but hides the complexity
- Cross-platform — Works on macOS, Linux, and Windows

Installation

``bash


npm (all platforms)

`bash


Interactive setup - scans your system, pick what to track, syncs to GitHub

That's it! tuck init does everything:

1. Asks where to store — GitHub, GitLab, local-only, or custom remote
2. Creates ~/.tuck repository
3. Scans your system for dotfiles
4. Lets you select which to track
5. Creates a remote repo (if using GitHub/GitLab)
6. Commits and pushes

$3

`bash


Detect changes, find new dotfiles, commit, and push - all in one

`bash


Apply dotfiles from any GitHub user

| Command | Description |
| ------------- | ----------------------------------------------------------------------- |
| tuck init | Set up tuck - scans for dotfiles, select what to track, syncs to GitHub |
| tuck sync | Detect changes + new files, commit, and push (pulls first if behind) |
| tuck status | See what's tracked, what's changed, and sync status |

$3

| Command | Description |
| --------------------- | ---------------------------------- |
| tuck add | Manually track specific files |
| tuck remove | Stop tracking files |
| tuck scan | Discover dotfiles without syncing |
| tuck list | List all tracked files by category |
| tuck diff [file] | Show what's changed |

$3

| Command | Description |
| ----------- | ---------------- |
| tuck push | Push to remote |
| tuck pull | Pull from remote |

$3

| Command | Description |
| ------------------- | ------------------------------------------------------ |
| tuck apply | Apply dotfiles from a GitHub user (with smart merging) |
| tuck restore | Restore dotfiles from repo to system |
| tuck undo | Restore from Time Machine backup snapshots |

$3

| Command | Description |
| -------------------- | -------------------------------------------- |
| tuck config | View/edit configuration |
| tuck config remote | Configure git provider (GitHub/GitLab/local) |
| tuck config wizard | Interactive configuration setup |

How It Works

tuck stores your dotfiles in ~/.tuck, organized by category:

`
~/.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 keys!)
│ └── misc/ # everything else
├── .tuckmanifest.json
└── .tuckrc.json
`

The flow:

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

Run tuck sync anytime to detect changes and push. On a new machine, run tuck apply username to grab anyone's dotfiles.

Git Providers

tuck supports multiple git hosting providers, detected automatically during setup:

| Provider | CLI Required | Features |
|----------|--------------|----------|
| GitHub | gh | Auto-create repos, full integration |
| GitLab | glab | Auto-create repos, self-hosted support |
| Local | None | No remote sync, local git only |
| Custom | None | Any git URL (Bitbucket, Gitea, etc.) |

$3

`bash


Change provider anytime

`bash
tuck init


→ Select GitLab

Configure tuck via ~/.tuck/.tuckrc.json or tuck config wizard:

`json
{
"repository": {
"autoCommit": true,
"autoPush": false
},
"files": {
"strategy": "copy",
"backupOnRestore": true
},
"remote": {
"mode": "github",
"username": "your-username"
}
}
`

$3

- copy (default) — Files are copied. Run tuck sync to update the repo.
- symlink — Files are symlinked. Changes are instant but require more care.

Windows Support

tuck fully supports Windows with platform-specific handling:

$3

| Category | Files |
|----------|-------|
| Shell | PowerShell profiles (Microsoft.PowerShell_profile.ps1) |
| Terminal | Windows Terminal settings, ConEmu/Cmder configs |
| Editors | VS Code, Cursor, Neovim (in %LOCALAPPDATA%) |
| Git | .gitconfig, .gitignore_global |
| SSH | SSH config in %USERPROFILE%\.ssh |
| Misc | WSL config (.wslconfig), Docker, Kubernetes |

$3

- Symlinks: On Windows, tuck uses directory junctions (don't require admin privileges) or falls back to copying files
- Permissions: Unix-style file permissions (chmod) don't apply on Windows; tuck handles this gracefully
- Paths: Windows environment variables (%APPDATA%, %LOCALAPPDATA%, %USERPROFILE%) are automatically expanded
- Hooks: tuck uses PowerShell Core (pwsh) or Windows PowerShell for hook execution

$3

tuck supports smart merging for PowerShell profiles with preserve markers:

`powershell


In your PowerShell profile, mark local-only sections:

- Never tracks private keys — SSH keys, .env files, and credentials are blocked by default
- Secret scanning — Warns if files contain API keys or tokens
- Placeholder support — Replace secrets with {{PLACEHOLDER}} syntax
- Local secrets — Store actual values in secrets.local.json (never committed)

`bash


Scan tracked files for secrets

`json
{
"hooks": {
"postRestore": "source ~/.zshrc"
}
}
`

Development

`bash
git clone https://github.com/Pranav-Karra-3301/tuck.git
cd tuck
pnpm install
pnpm build
pnpm test
`

Contributing

Contributions are welcome! Please read our contributing guidelines and submit PRs to the main` branch.

License

MIT — see LICENSE

---