What is DotState? - Modern Dotfile Manager for Developers

DotState is a terminal-based dotfile manager that helps you manage your dotfiles effortlessly. Whether you're syncing your configuration across multiple machines or setting up a new development environment, DotState makes it simple, safe, and fast.

/bin/bash -c "$(curl -fsSL https://dotstate.serkan.dev/install.sh)"
brew tap serkanyersen/dotstate
brew install dotstate
cargo install dotstate

For more installation options, see the Installation page.

Why Use a Dotfile Manager?

Managing dotfiles can be a pain. You want your .zshrc, .vimrc, .gitconfig, .bashrc, and other config files synced across machines, but traditional solutions are either too complex, insecure, or require too much manual work.

DotState solves this by being:

  • 🦀 Built with Rust - Fast, memory-safe, and reliable dotfile management
  • 🔒 Secure by design - No shell injection vulnerabilities, safe file operations
  • 🎨 Beautiful TUI - Intuitive interface that doesn't require learning Git
  • ⚡ Lightning fast - Non-blocking operations, instant feedback
  • 🛡️ Safe - Automatic backups before any file operations
  • 🔄 Git-powered - Store dotfiles in GitHub, GitLab, Bitbucket, or any git host

Traditional Dotfile Managers

  • ❌ Require Git knowledge
  • ❌ Manual symlink management
  • ❌ No built-in backup system
  • ❌ Complex setup process

DotState - Best Dotfile Manager

  • ✅ Zero Git knowledge required
  • ✅ Automatic symlink management
  • ✅ Built-in backups
  • ✅ One-command setup

Perfect For

  • Developers who work on multiple machines
  • Teams sharing configuration files
  • Anyone who wants to backup their dotfiles
  • Users switching between macOS and Linux
  • Developers who want a modern Rust-based solution
Tip: When you select a file, it's automatically copied to your repository and a symlink is created in its place. This means your files are safely backed up and version controlled.

Status

Synced Files: 8
Profiles: 2 (Active: Personal)
Repository: dotstate-storage

DotState Features - Complete Dotfile Management Solution

DotState provides everything you need for dotfile management, configuration sync, and profile organization. Here's what makes it the best dotfile manager:

🎯 Core Features

Profile Management

Create separate profiles for different contexts (work, personal, Mac, Linux, etc.). Perfect for managing multiple dotfile sets.

Flexible Git Sync

Sync with any git host: GitHub, GitLab, Bitbucket, or self-hosted. Use DotState-managed repos or bring your own.

Smart File Detection

Automatically finds common dotfiles in your home directory (.zshrc, .vimrc, .gitconfig, etc.).

Safe Operations

Automatic backups before any file modification. Your files are always safe.

Symlink Management

Automatic creation and management of symlinks. No manual linking required.

Custom Files

Add any file or directory, not just dotfiles. Full control over what you sync.

📦 Package Management

DotState includes built-in package management to track and install CLI tools per profile:

CLI Tool Tracking

Define and track CLI tools and dependencies per profile. Know what's installed where.

Multi-Manager Support

Works with Homebrew, Cargo, npm, pip, and more. One tool for all package managers.

Installation Flow

Check what's missing and install with one command. Never lose track of dependencies.

Custom Packages

Support for custom installation scripts. Full flexibility for your workflow.

🎨 User Experience

Beautiful TUI

Modern terminal interface built with Ratatui. The best terminal UI for dotfile management.

Mouse Support

Click to navigate and interact. Not just keyboard-only like other terminal tools.

Real-time Feedback

See what's happening as it happens. No more waiting for operations to complete.

CLI & TUI

Full-featured CLI for automation, beautiful TUI for interactive use. Best of both worlds.

Customizable Keymaps

Configurable keyboard shortcuts with preset support (Standard, Vim, Emacs) and custom overrides. Use your preferred keyboard layout.

Install DotState - Installation Guide

Install DotState, the best Rust dotfile manager, using one of these methods:

From Cargo (Recommended)

The easiest way to install DotState is via Cargo, the Rust package manager:

cargo install dotstate

From Source

Build DotState from source for the latest features:

git clone https://github.com/serkanyersen/dotstate.git
cd dotstate
cargo install --path .

Using Homebrew (macOS)

Install DotState via Homebrew on macOS:

brew tap serkanyersen/dotstate
brew install dotstate

Or use the direct install: brew install serkanyersen/dotstate/dotstate

System Requirements

  • Rust: Latest stable version (for building from source)
  • Git: For repository operations
  • Git Host Account: GitHub, GitLab, Bitbucket, or any git host (optional)
  • Operating System: Linux, macOS, or Windows
  • (Recommended) Nerd Fonts: For the best visual experience, we recommend using a Nerd Font to see all icons correctly.

Quick Start Guide - Get Started with DotState in Minutes

Get started with DotState, the fastest way to manage your dotfiles. Follow these simple steps:

1

Launch DotState

Start the DotState terminal UI:

dotstate
2

First-time Setup

Choose how to manage your dotfiles repository:

  • Option A: Create for me (GitHub)
    • DotState creates a repository on your GitHub account
    • Requires a GitHub token (github.com/settings/tokens)
    • Tip: You can set DOTSTATE_GITHUB_TOKEN environment variable
  • Option B: Use my own repository
    • Create a repo on any git host (GitHub, GitLab, Bitbucket, etc.)
    • Clone it locally and set up your git credentials
    • Provide the local path to DotState - no token required!
3

Add Your Files

Start syncing your dotfiles:

  • Navigate to "Manage Files"
  • Select files to sync (they're automatically added)
  • Files are moved to the repo and symlinked automatically
4

Sync with Remote

Push your dotfiles to your git remote:

  • Go to "Sync with Remote"
  • Your files are committed, pulled, and pushed automatically
  • Works with GitHub, GitLab, Bitbucket, or any git host
That's it! Your dotfiles are now synced and ready to use on any machine. DotState makes dotfile management effortless.

DotState CLI Commands - Complete Command Reference

DotState provides a powerful CLI for automation and scripting. Here's the complete command reference:

dotstate sync

Sync with remote: commit, pull (with rebase), and push. This is the main sync command for keeping your dotfiles up to date. Use -m "message" to provide a custom commit message, otherwise an automatic message is generated from changed files.

dotstate list

List all synced files. Shows the full path of symlink location and storage repo location.

--verbose Show detailed information including file status
dotstate add <path>

Add a file to sync. Moves the file directly to the repo and creates a symlink automatically.

Example: dotstate add ~/.myconfig or dotstate add ~/.zshrc
dotstate activate

Activate the symlinks, restores app state after deactivation. Use this after cloning your dotfiles on a new machine.

Essential for setting up a new machine with your existing dotfiles.

dotstate deactivate

Deactivate symlinks. This might be useful if you are going to uninstall dotstate or you need the original files.

--completely Completely remove symlinks without restoring files
dotstate logs

Shows logs location and how to view them. Useful for debugging issues.

dotstate config

Configuration file location. Shows where DotState stores its configuration.

dotstate repository

Repository location. Shows where your dotfiles are stored locally.

dotstate upgrade

Check for updates and optionally upgrade DotState. Shows available update options including install script, cargo, and homebrew.

--check Check for updates without prompting to install
dotstate help

Show help for a specific command. Get detailed information about any DotState command.

Example: dotstate help sync or dotstate help add

DotState Examples - Common Use Cases and Workflows

Learn how to use DotState with these practical examples and common workflows:

Common Workflows

Setting up a new machine

When you get a new computer, use DotState to quickly set up all your dotfiles:

  1. Install DotState: cargo install dotstate
  2. Launch TUI: dotstate
  3. Choose your setup mode:
    • GitHub mode: Enter your GitHub token
    • Local mode: Clone your existing repo and provide the path
  4. Select your profile
  5. Activate symlinks: dotstate activate

Your entire development environment is now configured!

Adding a new dotfile

Add new configuration files to your dotfile collection:

# Using CLI
dotstate add ~/.mynewconfig

# Or using TUI
dotstate
# Navigate to "Manage Files" → Select file

Both methods automatically move the file to the repo and create a symlink.

Syncing changes across machines

Keep your dotfiles synchronized across all your machines:

# Using CLI
dotstate sync
dotstate sync -m "Custom commit message"

# Or using TUI
dotstate
# Navigate to "Sync with Remote"

The sync command commits, pulls, and pushes automatically.

Managing multiple profiles

Create separate profiles for different contexts:

  • Personal: Your personal dotfiles (.zshrc, .vimrc, etc.)
  • Work: Work-specific configurations
  • Mac: macOS-specific settings
  • Linux: Linux-specific settings

Switch between profiles easily in the TUI or activate them via CLI. Perfect for managing different dotfile sets.

Package management per profile

Track and install CLI tools per profile:

  1. Navigate to "Manage Packages"
  2. Add packages (Homebrew, Cargo, npm, etc.)
  3. Check what's installed: Press S to check selected
  4. Install missing packages: Press I

Never lose track of what tools you need for each environment.

DotState Configuration - Repository Modes and Settings

DotState supports two repository modes, giving you flexibility in how you manage your dotfiles.

Repository Modes

🌐 GitHub Mode (DotState-managed)

DotState creates and manages a repository on your GitHub account. Requires a GitHub Personal Access Token.

Best for: Users who want a simple, automated setup.

Token options:

  • Environment variable: export DOTSTATE_GITHUB_TOKEN=ghp_your_token
  • Config file (set during first-time setup)

📁 Local Mode (User-provided)

Use your own pre-existing git repository. Works with any git host (GitHub, GitLab, Bitbucket, self-hosted, etc.).

Best for: Users with existing dotfiles repos, enterprise environments, or non-GitHub users.

Requirements:

  • A locally cloned git repository with an "origin" remote
  • Git credentials configured (SSH keys, git credential manager, etc.)

No token required! DotState uses your system's git credentials for push/pull operations.

Configuration File

DotState stores configuration at:

~/.config/dotstate/config.toml

Update Notifications

DotState automatically checks for updates and shows a notification in the main menu when a new version is available.

Check for Updates Manually

dotstate upgrade

This command checks for updates and provides interactive options to upgrade.

Disable Update Checks

Add this to your config.toml to disable automatic update checks:

[updates]
check_enabled = false

You can also configure the check interval (default: 24 hours):

[updates]
check_enabled = true
check_interval_hours = 48

Keymap Configuration

DotState supports customizable keyboard shortcuts with preset keymaps (Standard, Vim, Emacs) and custom key binding overrides. The keymap system allows you to use your preferred keyboard layout and override any action with any key combination.

Available Presets

  • Standard: Arrow keys (↑↓), Enter, Esc, standard navigation
  • Vim: Vim-style navigation (hjkl for movement, q to quit, etc.)
  • Emacs: Emacs-style navigation (Ctrl+N/P for up/down, Ctrl+G to quit, etc.)

Changing the Preset

Edit ~/.config/dotstate/config.toml and set the preset option:

[keymap]
preset = "vim" # Options: "standard", "vim", "emacs"

Custom Key Binding Overrides

You can override any key binding with custom keys. Overrides take precedence over preset bindings and shadow preset bindings for the same action.

[keymap]
preset = "vim"

# Override 'x' to quit instead of 'q'
[[keymap.overrides]]
key = "x"
action = "quit"

# Override 'w' to move up instead of 'k'
[[keymap.overrides]]
key = "w"
action = "move_up"

# Use Ctrl+H for help
[[keymap.overrides]]
key = "ctrl+h"
action = "help"

Available Actions (all in snake_case):

  • Navigation: move_up, move_down, move_left, move_right, page_up, page_down, go_to_top, go_to_end, home, end
  • Selection: confirm, cancel, toggle_select, select_all, deselect_all
  • Global: quit, help
  • Actions: delete, edit, create, search, refresh, sync, check_status, install
  • Text editing: backspace, delete_char
  • Navigation: next_tab, prev_tab
  • Scroll: scroll_up, scroll_down
  • Prompts: yes, no
  • Forms: save, toggle_backup

Key Format Examples:

  • Single keys: "j", "k", "q", "x"
  • Special keys: "up", "down", "enter", "esc", "tab", "space"
  • Function keys: "f1", "f2", etc.
  • Modifier combinations: "ctrl+n", "ctrl+shift+j", "ctrl+h"

How Overrides Work

  • Overrides take precedence over preset bindings
  • When you override an action (e.g., move_up), all preset bindings for that action are shadowed/removed
  • If you override move_up with "w", the original preset key (e.g., "k" in vim preset) will no longer work for that action
  • Display functions (footer hints) automatically reflect your actual key bindings, including overrides
  • Press ? in the TUI to see all current key bindings in the help overlay

Theme Configuration

DotState supports both light and dark themes that automatically adapt to your terminal background.

Changing the Theme

Edit ~/.config/dotstate/config.toml and set the theme option:

theme = "dark" # For dark terminal backgrounds (default)
theme = "light" # For light terminal backgrounds
theme = "nocolor" # Disable all UI colors (same as NO_COLOR=1 / --no-colors)
Tip: For CI/CD and automation with GitHub mode, use the DOTSTATE_GITHUB_TOKEN environment variable. For Local mode, ensure your git credentials are properly configured. Press ? in the TUI to see all current key bindings based on your configuration.

DotState Security - Secure Dotfile Management

Security is a top priority for DotState. Here's how we keep your dotfiles safe:

Security Features

🛡️ No Shell Injection

All commands use direct execution, not shell interpretation. This prevents shell injection vulnerabilities that plague other dotfile managers.

✅ Path Validation

Dangerous paths (like home directory root) are blocked. The app validates all paths before operations to prevent accidental data loss.

🔍 Git Repository Detection

Prevents nested Git repositories. You can't have a Git repo inside a Git repo, protecting you from configuration conflicts.

💾 Backup System

Automatic backups before any file operation. Your files are safe even if something goes wrong during sync or file operations.

🔐 Token Security

GitHub Mode: Tokens can be provided via the DOTSTATE_GITHUB_TOKEN environment variable or stored in config files. Use tokens with minimal required permissions (only repo scope).

Local Mode: No tokens stored by DotState. Uses your system's git credentials (SSH keys, git credential manager).

Security Best Practices

  • Use GitHub tokens with minimal required permissions (only repo scope)
  • Rotate tokens regularly for enhanced security
  • Never commit tokens to version control
  • Review files before syncing (especially custom files)
  • Keep backups enabled (default: enabled)
  • Use private repositories for sensitive configurations

Contributing to DotState - Open Source Dotfile Manager

We welcome contributions! DotState is an open-source project built with ❤️ and Rust. Help us make it the best dotfile manager available.

How to Contribute

  1. Fork the repository on GitHub
  2. Create a branch from main
  3. Make your changes
  4. Test thoroughly
  5. Submit a pull request

Areas for Contribution

📝 Documentation

Improving README, adding examples, writing guides

🧪 Testing

Adding tests, improving test coverage

🎨 UI/UX

Improving the TUI interface, adding features

⚡ Performance

Optimizing operations, reducing memory usage

🌐 Platform Support

Improving cross-platform compatibility

📦 Package Managers

Adding support for more package managers

Read More: See CONTRIBUTING.md for detailed guidelines.