dotstate 0.1.14

A modern, secure, and user-friendly dotfile manager built with Rust
dotstate-0.1.14 is not a library.
Visit the last successful build: dotstate-0.2.3

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

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.)
  • GitHub Sync: Automatic sync with GitHub (private or public repos)
  • 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

🔒 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

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

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

  1. Launch DotState:

    dotstate

  2. First-time Setup:

    • 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:

    • 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:

    • 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

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

# Deactivate symlinks (restore original files)
dotstate deactivate

# Show help
dotstate help

How It Works

  1. Storage: Your dotfiles are stored in a Git repository (default: ~/.config/dotstate/storage)
  2. Symlinks: Original files are replaced with symlinks pointing to the repo
  3. Profiles: Different profiles can have different sets of files
  4. Sync: Changes are committed and synced with GitHub automatically

Security Considerations

  • No Shell Injection: All commands use direct execution, not shell interpretation
  • Path Validation: Dangerous paths (like home directory root) are blocked
  • Git Repository Detection: Prevents nested Git repositories
  • Backup System: Automatic backups before any file operation
  • Token Security: GitHub tokens are stored securely in config files

Requirements

  • Rust: Latest stable version (for building from source)
  • Git: For repository operations
  • GitHub Account: For cloud sync (optional, but recommended)

Project Status

DotState is actively developed and ready for use. The core features are stable, and we're continuously improving based on user feedback.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE file for details.

Acknowledgments

Built with:

  • Ratatui - Beautiful TUI framework
  • git2 - Git operations
  • clap - CLI parsing

Badges:

Support

Made with ❤️ and Rust