ralph

"Me fail dotfiles? That's unpossible."

A dotfiles manager written in Go. Declare your setup in a TOML file -- symlinks, copies, aliases, functions, repos, build hooks, packages -- and ralph apply makes it happen. Idempotent, repeatable, no surprises.

Install

# With Go 1.21+
go install github.com/mad01/ralph/cmd/ralph@latest

# Or build from source
git clone https://github.com/mad01/ralph.git
cd ralph && make build

Pre-built binaries are available on the Releases page.

Quick start

# Create a config file at ~/.config/ralph/config.toml
ralph init

# Set up a dotfiles repo
mkdir -p ~/.dotfiles
cp ~/.bashrc ~/.dotfiles/.bashrc

Add entries to your config:

dotfiles_repo_path = "~/.dotfiles"

[dotfiles.bashrc]
source = ".bashrc"
target = "~/.bashrc"

[shell.aliases.ll]
command = "ls -alhF"

[shell.aliases.g]
command = "git"

Apply it:

ralph apply

Run it again and nothing changes. Run it after editing your config and only the diff gets applied.

What ralph manages

• Dotfiles -- symlink, copy, or template files from a source repo to their targets
• Directories -- create directories before other operations
• Git repositories -- clone, pull, pin to branch or commit
• Shell config -- aliases, functions, and environment variables injected into your rc file
• Build hooks -- run commands during apply (always, once, or manual)
• Packages -- clone remote tools or track local projects; ralph sync pulls, ralph apply rebuilds on changes
• Tool checks -- verify tools are installed, show install hints
• Recipes -- split config into modular recipe.toml files alongside source files

Documentation

Guide	Description
Getting Started	Zero to working setup
Commands	All commands with flags and examples
Configuration	Full config.toml schema reference
Recipes	Modular configuration with auto-discovery
Packages	Package management (ralph sync + ralph apply)
Workflows	Daily usage patterns
Templating	Go template system for dotfiles
Migration	Symlink migration after reorganization
pipeutil	pkg/pipeutil for custom shell tools

Examples

Example	Description
minimal	Simplest setup -- 3 dotfiles, 2 aliases
recipe-based	Modular config with auto-discovery
with-packages	Local and remote package builds
dotfiles-repo	Full dotfiles repository structure

Contributing

Contributions welcome. Open an issue or PR on GitHub.

License

See LICENSE file.