Madam, I’m yadm

I recently got a new laptop (see Making the M1 leap if you’re curious how that journey went), and in so doing, got lots of great advice about how other developers set up their machines. The award for biggest game-changer, though, has to go to Patrick Schratz who introduced me to yadm (Yet Another Dotfiles Manager). Here, I’ll give you a quick rundown of what yadm is, how to get started with it, and why I think it’s so darn cool.

For more Pat Schratz wisdom, see Transitioning from x86 to arm64 on macOS - experiences of an R user.

.dotfiles 101

Dotfiles (so named because they usually start with a .) are plain-text configuration files that store your settings for various programs on your computer. For example, your Git settings/credentials are probably stored in a .gitconfig file. If you’ve never seen such a thing, that’s probably because they’re hidden by default on Unix-based systems. If that’s you (which is totally fine), you might want to check out a quick primer on viewing/creating dotfiles, e.g. What is a Dotfile and How to Create it in Mac and Linux (Lemonaki 2021), before continuing here.

Want to learn a lot more about dotfiles? See the Dotfiles post/lecture from MIT’s ./missing-semester series.

It’s pretty safe to say that the general consensus is that it’s worth managing your dotfiles with version control somehow, there are a range of opinions when it comes to the mechanics of dotfile management (see the Tools section of Awesome dotfiles). I tried all the tools out there, so I can’t really pass judgement. Prior to yadm, I was using GNU Stow, which takes a “symlinking” approach to dotfile management—essentially, you hoodwink your computer into thinking all your dotfiles are stored in a single directory. If Stow or symlinks were inherently bad, no one would use them (which isn’t the case). That said, I happen to like yadm’s approach a bit better.

yadm

There’s no way I’m going to outdo yadm’s own overview, so I’m not even going to try:

If you know how to use Git, you already know how to use yadm. yadm helps you maintain a single repository of dotfiles, while keeping them where they belong—in $HOME.

That’s right, with yadm, your dotfiles can stay where they are! You’ll point them out to yadm (once you’ve installed it), and BOOM you’re keeping track of them (OK, there are a couple of other set-up steps, but it’s still pretty amazing).

How you install yadm depends on your operating system. I’m on a Mac (and a die-hard Homebrew fan), so I installed it with:

Terminal

brew install yadm

If you’re embarking on this journey, you should probably just follow yadm’s Getting Started (much of which I’ll regurgitate here, but I can’t promise it’ll be the latest and greatest). The gist of it is as follows: you’ll start out by initializing yadm in an empty local repo¹ with yadm init.

Get used to the format of yadm <git command>, it’s how yadm rolls.

To add a file, you’re going to use yadm add <file> with the full path to the file (you’re not moving your dotfiles anywhere—yadm doesn’t need a directory, just a repository). For example, here is how I added .zshrc:

Terminal

yadm add ~/.zshrc

The file doesn’t have to be right in your home directory (though that’s where most dotfiles reside). If I wanted to add my RStudio-preferences JSON file, for example, I’d write:

Terminal

yadm add ~/.config/rstudio/rstudio-prefs.json

Since yadm wraps Git, the subsequent steps won’t be surprising. You’ll want to: commit your changes, add a remote, and push your local repo to said remote:

Terminal

# commit changes
yadm commit -m "Message if I want to write one"

# add remote named origin
yadm remote add origin <url>

# push your changes to main branch of remote
yadm push -u origin main

If you peek at yadm’s Common Commands, you’ll see lots of familiar Git commands. The one with the most surprising output coming from Git is probably yadm status, since yadm kind of flips Git’s default ignoring behaviour on its head by ignoring untracked files (i.e. any file that hasn’t explicitly been added won’t show up). Like Git, though, yadm status will let you know if you’ve got any changes to the files you are tracking.

You can print a list of all the files managed by yadm from anywhere with yadm list -a. My results look something like the following (I’ve commented the output out):

Terminal

yadm list -a
# .Renviron
# .Rprofile
# .gitconfig
# .gitignore
# .you-get-the-idea

yadm bonus features

Got confidential files you want to manage, but don’t want to put them in a public repo? (Good! You shouldn’t put them there.) Enter yadm’s encryption features. Want to use alternate files on different systems? Templates? Hooks? yadm’s got you covered for those things, too.

But how does yadm differ from <insert tool here>?

Answer: Unless it’s Stow, I’m probably not the best person to ask. There is a lovely Comparisons section in the yadm FAQs, though.

All in all, I’m well pleased with yadm. So, major thanks to its author, Tim Byrne, and to Pat Schratz for introducing me to it.

References

Lemonaki, Dionysia. 2021. “Dotfiles – What Is a Dotfile and How to Create It in Mac and Linux.” freeCodeCamp.org. https://www.freecodecamp.org/news/dotfiles-what-is-a-dot-file-and-how-to-create-it-in-mac-and-linux/.

Footnotes

1. Unless you have an existing remote you want to clone, in which case you clone it.