⚙️ dotf ⚡

Modern Dotfiles Manager

Sync your environment / configurations across machines in seconds

🚀 Alpha Version - Core functionality implemented. Ready for testing and feedback. Some advanced features may still be in development.

cargo install dotf

One command to rule them all ⚡

Dotf transforms how you manage dotfiles. Install and synchronize your development environment from remote repositories with intelligent conflict resolution, automatic dependency management, and beautiful CLI feedback. From zero to configured in minutes.

✨ Features

🚀 Modern CLI - Beautiful, intuitive command-line interface with animations and progress indicators
🌿 Branch Selection - Choose any branch during initialization with validation
🔗 Smart Symlink Management - Automatic symbolic link creation with conflict resolution
📦 Dependency Management - Cross-platform system dependency installation
🔄 Git Integration - Seamless sync with remote repositories
🎯 Configuration Validation - Comprehensive dotf.toml syntax and structure validation
📋 Template Generation - Auto-generate dotf.toml templates for new repositories
💾 Backup System - Safe backup and restore of existing configurations
🎨 Beautiful Output - Progress bars, animations, and colored terminal output
⚙️ TOML Configuration - Modern configuration format for better readability

🚀 Quick Start

Installation

# Install via cargo
cargo install dotf

# Or use the one-liner installer without requiring Cargo / Rust dependencies
curl -sSL dotf-install.sh | sh

Initialize from Remote Repository

# Initialize dotf with a remote repository (with interactive branch selection)
dotf init --repo https://github.com/username/dotfiles.git

# Or initialize without specifying URL (will prompt for URL and branch)
dotf init

# Install system dependencies
dotf install deps

# Install configuration symlinks
dotf install config

Check Status

# Check current status and sync information
dotf status

# View symlink status
dotf symlinks

# Sync with remote repository
dotf sync

📖 Usage

Commands

Command	Description
`dotf init`	Initialize dotf with a remote repository
`dotf install deps`	Install system dependencies
`dotf install config`	Create configuration symlinks
`dotf install <custom>`	Run custom installation scripts
`dotf status`	Show repository sync status
`dotf symlinks`	List symlinks and their status
`dotf symlinks restore`	Restore files from backup
`dotf sync`	Sync with remote repository
`dotf config`	View dotf configuration
`dotf schema init`	Generate dotf.toml template file
`dotf schema test`	Validate dotf.toml syntax and structure

Workflow

1. Repository Initialization

# Initialize with remote repository
dotf init --repo https://github.com/username/dotfiles.git

This command:

Detects and displays the repository's default branch
Prompts for branch selection with validation
Validates the remote repository structure and configuration
Creates ~/.dotf/ directory
Clones the specified branch to ~/.dotf/repo/
Creates ~/.dotf/settings.toml for local configuration

2. Dependency Installation

# Install system dependencies (languages, tools, etc.)
dotf install deps

Executes dependency installation scripts based on your platform.

3. Configuration Installation

# Install configuration symlinks
dotf install config

Creates symbolic links according to your configuration. If conflicts exist:

Prompts to backup existing files to ~/.dotf/backups/
Option to abort installation
Safe conflict resolution

4. Custom Installations

# Run custom installation scripts
dotf install vim-plugins
dotf install zsh-setup

Execute custom installation scripts defined in your configuration.

🔧 Repository Configuration

Your dotfiles repository should contain a dotf.toml configuration file:

[symlinks]
# Source (in repo) -> Target (on system)
"nvim" = "~/.config/nvim"
"tmux/tmux.conf" = "~/.tmux.conf"
"zsh/zshrc" = "~/.zshrc"
"git/gitconfig" = "~/.gitconfig"
"alacritty/alacritty.yml" = "~/.config/alacritty/alacritty.yml"

[scripts.deps]
# Dependency installation scripts
macos = "scripts/install-deps-macos.sh"
linux = "scripts/install-deps-linux.sh"
windows = "scripts/install-deps-windows.ps1"

[scripts.custom]
# Custom installation scripts
vim-plugins = "scripts/install-vim-plugins.sh"
zsh-setup = "scripts/setup-zsh.sh"
font-install = "scripts/install-fonts.sh"

Example Repository Structure

my-dotfiles/
├── dotf.toml              # Configuration file
├── README.md
├── nvim/                  # Neovim configuration
│   ├── init.vim
│   └── plugins/
├── tmux/                  # Tmux configuration
│   └── tmux.conf
├── zsh/                   # Zsh configuration
│   ├── zshrc
│   └── aliases.zsh
├── git/                   # Git configuration
│   └── gitconfig
├── alacritty/            # Terminal configuration
│   └── alacritty.yml
├── macos/                # macOS specific configs
│   ├── yabai/
│   └── skhd/
├── linux/                # Linux specific configs
│   ├── i3/
│   └── rofi/
└── scripts/              # Installation scripts
    ├── install-deps-macos.sh
    ├── install-deps-linux.sh
    ├── install-vim-plugins.sh
    └── setup-zsh.sh

🔧 Local Configuration

Dotf creates ~/.dotf/settings.toml for local configuration:

last_sync = 2024-01-15T10:30:00Z
initialized_at = 2024-01-15T09:00:00Z

[repository]
remote = "https://github.com/username/dotfiles.git"
branch = "main"
local = "/home/user/.dotf/repo"

🎯 Status and Monitoring

Status Output

$ dotf status

▶ Repository Status ──────────────────────────────
Branch: main
  ✅ Working tree is clean
  📥 2 commits behind

▶ Symlinks Summary ──────────────────────────────
  Total: 8
  Valid: 6 ✅
  Missing: 1 ❌
  Conflicts: 1 ⚠️

Symlinks Status

$ dotf symlinks

▶ Symlinks Summary ──────────────────────────────
  Total: 6
  Valid: 3 ✅
  Conflicts: 1 ⚠️
  Missing: 1 ❌
  Broken: 1 💔

▶ Symlinks Status ───────────────────────────────
  ⚠️ Conflict git/.gitconfig → ~/.gitconfig (file exists)
  ❌ Missing alacritty/alacritty.yml → ~/.config/alacritty/alacritty.yml (not created)
  💔 Broken vim/.vimrc → ~/.vimrc (target missing)
  ✅ Valid zsh/.zshrc → ~/.zshrc
  ✅ Valid tmux/.tmux.conf → ~/.tmux.conf
  ✅ Valid nvim → ~/.config/nvim

Shell Integration

Add to your shell configuration for sync monitoring:

# .zshrc or .bashrc
# Check dotf status on shell startup
if command -v dotf >/dev/null 2>&1; then
    dotf status --quiet
fi

🔄 Sync and Updates

Sync with Remote

# Check for updates
dotf status

# Sync with remote repository
dotf sync

# Force sync (override local changes)
dotf sync --force

Backup and Restore

# List available backups
dotf symlinks restore --list

# Restore specific file from backup
dotf symlinks restore ~/.gitconfig

# Restore all backed up files
dotf symlinks restore --all

🎨 Configuration Management

View Configuration

# View current dotf configuration
dotf config

# View repository configuration
dotf config --repo

# Edit local settings
dotf config --edit

Custom Installation Scripts

Create executable scripts for complex setup tasks:

# scripts/install-vim-plugins.sh
#!/bin/bash
echo "Installing Vim plugins..."
vim +PlugInstall +qall

# scripts/setup-zsh.sh
#!/bin/bash
echo "Setting up Zsh environment..."
if [ ! -d ~/.oh-my-zsh ]; then
    sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
fi

git clone https://github.com/zsh-users/zsh-autosuggestions ~/.oh-my-zsh/custom/plugins/zsh-autosuggestions

Run custom scripts:

dotf install vim-plugins
dotf install setup-zsh

📋 Common Workflows

Creating a New Dotfiles Repository

# 1. Create and initialize your dotfiles repository
mkdir my-dotfiles && cd my-dotfiles
git init

# 2. Generate dotf.toml template
dotf schema init

# 3. Edit the configuration to match your setup
vim dotf.toml

# 4. Validate your configuration
dotf schema test

# 5. Create your dotfiles structure and commit
mkdir -p zsh git nvim scripts
# ... add your configuration files ...
git add . && git commit -m "Initial dotfiles setup"

Initial Setup on New Machine

# 1. Initialize with your dotfiles repository (will prompt for branch selection)
dotf init --repo https://github.com/myuser/dotfiles.git

# 2. Install system dependencies
dotf install deps

# 3. Install configuration symlinks
dotf install config

# 4. Run custom setup scripts
dotf install vim-plugins
dotf install zsh-setup

# 5. Check final status
dotf status

The init process will:

Detect the repository's default branch (e.g., "main", "master")
Prompt you to select a branch with the default pre-filled
Validate that the selected branch exists
Clone from the chosen branch

Daily Sync Workflow

# Check for updates (add to shell startup)
dotf status

# Sync when updates available
dotf sync

# Check symlink health
dotf symlinks

Backup and Recovery

# Before major changes, ensure backups
dotf symlinks restore --list

# If something breaks, restore from backup
dotf symlinks restore ~/.zshrc

Creating and Managing dotf.toml

Generate Template for New Repository

# Create a new dotfiles repository
mkdir my-dotfiles && cd my-dotfiles
git init

# Generate dotf.toml template
dotf schema init

# Edit the generated template
vim dotf.toml

Validate Configuration

# Validate current dotf.toml
dotf schema test

# Validate specific file
dotf schema test --file /path/to/dotf.toml

# Validate with detailed output
dotf schema test --quiet

# Continue even if errors are found (useful for CI)
dotf schema test --ignore-errors

The dotf schema test command validates:

TOML Syntax: Proper TOML formatting and structure
Schema Compliance: Required sections and valid configuration
Symlink Configuration: Path validation and duplicate detection
Script Files: Existence of referenced script files
Source Files: Existence of source files in symlink mappings

🚧 Development

🚀 Alpha Version - Core functionality implemented and ready for testing. Feedback and contributions welcome!

Building from Source

git clone https://github.com/k1-c/dotf.git
cd dotf
cargo build --release

Running Tests

cargo test

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

📝 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Inspired by GNU Stow, Dotbot, and other dotfile management tools
Built with ❤️ using Rust

Made with 🦀 Rust

Name		Name	Last commit message	Last commit date
Latest commit History 100 Commits
.github		.github
docs		docs
src		src
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
deny.toml		deny.toml
dotf.toml		dotf.toml
install.sh		install.sh
lefthook.yml		lefthook.yml

License

k1-c/dotf

Folders and files

Latest commit

History

Repository files navigation