Introduction

When you live in the command line, your configurations become deeply personal. They evolve over years of experience, lessons learned, and ingenuity rewarded. But what happens when you’re away from your familiar setup? You feel like an orphaned refugee in unfamiliar territory. Enter yadm, the Yet Another Dotfiles Manager. With yadm, you can maintain a single repository of your dotfiles while keeping them where they belong—in your $HOME directory. Let’s dive into setting up yadm step by step.

1. Installation

Ubuntu/Debian

If you’re using Ubuntu or Debian, you’re in luck. yadm is available via standard package repositories. Open your terminal and run:

sudo apt update
sudo apt install yadm

MacOS

On macOS, you can use MacPorts to install yadm. In your terminal, execute:

brew install yadm

2. Basic Setup

Initialize yadm

Once installed, initialize yadm in your home directory:

yadm init

This creates a .yadm directory where your dotfiles will reside.

Add Your Dotfiles

Place your existing dotfiles (e.g., .bashrc, .vimrc, etc.) into the .yadm directory. Track them using:

yadm add <filename>

Commit and Push

Commit your changes:

yadm commit -m "Initial dotfiles setup"

Push to your remote repository (e.g., GitHub):

yadm remote add origin <repository_url>
yadm push -u origin master

Clone your existing repo on another device.

The clone command will attempt to check out all files that exist in the repository. If a file already exists locally and has content that differs from the one in the repository, the local file will be left unmodified and you’ll have to review and resolve the differences.

yadm clone <url>
yadm status

3. Alternate Files

• OS-Specific Files

  Sometimes you need different configurations on different systems. Create files like example.txt##os.Darwin (for macOS) or example.txt##os.Linux (for Linux). yadm will automatically symlink the appropriate version based on the OS.

• Hostname-Specific Files

  Use example.txt##os.Darwin,hostname.myhost for specific hostnames.

4. Encryption

Add Sensitive Files

Place sensitive files in $HOME/.yadm/encrypt. yadm will manage an encrypted archive alongside your other configurations.

5. Customization

Bootstrap Instructions

Define custom instructions for your dotfiles installation. yadm can execute your program after a successful clone.

Hooks

Perform custom operations before or after any yadm command.