DotState

A modern, secure, and user-friendly dotfile manager built with Rust

DotState is a terminal-based tool 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.

Demo

https://github.com/user-attachments/assets/9be0df5e-87ce-4b61-ae0f-1c8ffe94cb36

Why DotState?

Managing dotfiles can be a pain. You want your .zshrc, .vimrc, 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
🔒 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

What Makes DotState Different?

Traditional Dotfile Managers

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

DotState

Zero Git knowledge required - We handle everything
Automatic symlink management - Files are linked automatically
Built-in backups - Your files are safe before any operation
One-command setup - Get started in seconds
Profile support - Separate configs for work, personal, Mac, Linux, etc.
Package management - Track and install CLI tools per profile
Beautiful TUI - Visual interface with mouse support

Features

🎯 Core Features

Profile Management: Create separate profiles for different contexts (work, personal, Mac, Linux, etc.)
Common Files Support: Share dotfiles (like .gitconfig or .tmux.conf) across all profiles automatically.
Flexible Git Sync: Automatic sync with GitHub, GitLab, Bitbucket, or any git host
Two Setup Modes: Let DotState create a GitHub repo for you, or use your own repository
Smart File Detection: Automatically finds common dotfiles in your home directory
Safe Operations: Automatic backups before any file modification
Symlink Management: Automatic creation and management of symlinks
Custom Files: Add any file or directory, not just dotfiles

📦 Package Management

CLI Tool Tracking: Define and track CLI tools and dependencies per profile
Multi-Manager Support: Works with Homebrew, Cargo, npm, pip, and more
Installation Flow: Check what's missing and install with one command
Custom Packages: Support for custom installation scripts

🎨 User Experience

Beautiful TUI: Modern terminal interface built with Ratatui
Mouse Support: Click to navigate and interact
Real-time Feedback: See what's happening as it happens
Error Recovery: Clear error messages with actionable guidance
CLI & TUI: Full-featured CLI for automation, beautiful TUI for interactive use
Customizable Keymaps: Configurable keyboard shortcuts with preset support (Standard, Vim, Emacs) and custom overrides

🔒 Security

No Shell Injection: Direct command execution, no shell interpretation
Safe File Operations: Validates paths, prevents dangerous operations
Secure GitHub Integration: Token-based authentication
Backup System: Automatic backups before any destructive operation

Installation

Prebuilt from website (Recommended)

Installation Guide

curl -fsSL https://dotstate.serkan.dev/install.sh | bash

Using Cargo

cargo install dotstate

Using Homebrew

brew tap serkanyersen/dotstate
brew install dotstate

Or use the direct install:

brew install serkanyersen/dotstate/dotstate

Quick Start

Launch DotState:
```
dotstate
```
First-time Setup:
- Choose how to set up your repository:
  - Option A: Create for me (GitHub) - DotState creates a repo on GitHub
    - Enter your GitHub token (create one at github.com/settings/tokens)
    - Tip: You can also set the DOTSTATE_GITHUB_TOKEN environment variable
    - Choose repository name and visibility (private/public)
  - Option B: Use my own repository - Bring your own git repo
    - Create a repo on any git host (GitHub, GitLab, Bitbucket, etc.)
    - Clone it locally and set up your credentials
    - Point DotState to your local repo path
Add Your Files:
- Navigate to "Manage Files"
- Select files to sync (they're automatically added)
- Files are moved to the repo and symlinked automatically
Sync with Remote:
- 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.

CLI Usage

DotState also provides a powerful CLI for automation:

# List all synced files
dotstate list

# Add a file to sync
dotstate add ~/.myconfig

# Sync with remote (commit, pull, push)
dotstate sync

# Sync with custom commit message
dotstate sync -m "My custom commit message"

# Activate symlinks (useful after cloning on a new machine)
dotstate activate

# Deactivate symlinks (restore original files)
dotstate deactivate

# Package management
dotstate packages list                    # List packages with status
dotstate packages add -n ripgrep -m brew -b rg  # Add a package
dotstate packages check                   # Check what's installed
dotstate packages install                 # Install missing packages

# Check for updates and upgrade
dotstate upgrade

# Show help
dotstate help

Shell Completions

Generate completions for your shell:

# Bash
source <(dotstate completions bash)

# Fish
dotstate completions fish | source

# Zsh
source <(dotstate completions zsh)

Using oh-my-zsh, antigen, or prezto? These frameworks require the fpath approach:

  mkdir -p ~/.zsh/completions
  dotstate completions zsh > ~/.zsh/completions/_dotstate

Then add fpath=(~/.zsh/completions $fpath) to your .zshrc before your framework loads.

How It Works

Storage: Your dotfiles are stored in a Git repository (default: ~/.config/dotstate/storage)
Symlinks: Original files are replaced with symlinks pointing to the repo
Profiles: Different profiles can have different sets of files
Common Files: Files that are shared across all profiles are stored in the common section and linked regardless of the active profile
Sync: Changes are committed and synced with GitHub automatically

Working with Profiles

Profiles are how DotState organizes your dotfiles for different machines or contexts. Each profile has its own set of files, while Common Files are shared across all profiles automatically.

               ┌────────────────────┐
               │ Common Files       │
               ├────────────────────┤
               │ .tmux.conf         │
               │ .gitconfig         │       ┌────────────────────┐
               │ .vimrc             │       │ Server             │
               │                    │       ├────────────────────┤
               │                    ├──────►│ .bashrc            │
               │                    │       │ .profile           │
               └─┬─────────────────┬┘       │ .config.toml       │
                 │                 │        └────────────────────┘
                 │                 │
                 ▼                 ▼
┌────────────────────┐           ┌────────────────────┐
│ Personal           │           │ Work               │
├────────────────────┤           ├────────────────────┤
│ .zshrc             │           │ .zshrc             │
│ .sshconfig         │  Copy     │ .sshconfig         │
│ ...                ├──────────►│ ...                │
│                    │           │ workfile.sh        │
└────────────────────┘           └────────────────────┘

Creating Profiles

In the TUI, go to Manage Profiles and press C to create a new profile. You can:

Start blank for a completely new setup
Copy from an existing profile to carry over files and packages — great for setting up a similar machine quickly

Switching Profiles

Select a profile and press Enter to switch. DotState will remove symlinks for the old profile and create symlinks for the new one automatically. Common files stay linked regardless of which profile is active.

Common Files

You decide which files are shared. Move any file to Common and it will be symlinked in every profile. Common files stay linked when you switch profiles. To move a file between profile-specific and common:

Go to Manage Files
Select a file
Press M to move it to Common (or back to the active profile)

Use Cases

Multi-machine: Use a Personal profile on your laptop, Work on your work machine, and Server for headless setups. Keep shared configs (.gitconfig, .tmux.conf) in Common.
Same computer, different contexts: Create profiles like day, night, or focus with different terminal themes and defaults, and switch between them instantly.
Quick duplication: When setting up a second machine, create a new profile by copying from an existing one, then tweak what's different.

Configuration

Repository Setup Modes

DotState supports two repository setup modes:

GitHub Mode (Automatic)

Let DotState create and manage a GitHub repository for you. Requires a GitHub Personal Access Token.

GitHub Token Options:

DotSta

Dotstate

Install / Use

README

DotState

Demo

Why DotState?

What Makes DotState Different?

Traditional Dotfile Managers

DotState

Features

🎯 Core Features

📦 Package Management

🎨 User Experience

🔒 Security

Installation

Prebuilt from website (Recommended)

Using Cargo

Using Homebrew

Quick Start

CLI Usage

Shell Completions

How It Works

Working with Profiles

Creating Profiles

Switching Profiles

Common Files

Use Cases

Configuration

Repository Setup Modes

GitHub Mode (Automatic)