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
  • 🔄 GitHub-powered - Your dotfiles stored securely in a private or public repo

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.

GitHub Sync

Automatic sync with GitHub (private or public repos). Keep your dotfiles backed up and accessible from anywhere.

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.

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
  • GitHub Account: For cloud sync (optional, but recommended)
  • Operating System: Linux, macOS, or Windows

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

Configure DotState for the first time:

  • Enter your GitHub token (create one at github.com/settings/tokens)
  • Choose repository name and location
  • Select repository visibility (private/public)
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 to GitHub

Push your dotfiles to GitHub:

  • Go to "Sync with Remote"
  • Your files are committed, pulled, and pushed automatically
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.

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 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. Enter your GitHub token
  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

# 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 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 tokens are stored securely in config files. Use tokens with minimal required permissions (only repo scope).

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.