A house that does not have one warm, comfy chair in it is soulless.—May Sarton
When you live in a command line, configurations are a deeply personal thing. They are often crafted over years of experience, battles lost, lessons learned, advice followed, and ingenuity rewarded. When you are away from your own configurations, you are an orphaned refugee in unfamiliar and hostile surroundings. You feel clumsy and out of sorts. You are filled with a sense of longing to be back in a place you know. A place you built. A place where all the short-cuts have been worn bare by your own travels. A place you proudly call...
Home is an invention on which no one has yet improved.—Ann Douglas
As so many others, I started out with a repository of dotfiles and a few scripts to symbolically link them around my home directory. This quickly became inadequate and I looked for solutions elsewhere. I've used two excellent tools; homeschick, and vcsh. These tools are great, and you should check them out to understand their strengths. However, I didn't find all of the features I personally wished for in a single tool. yadm was written with the following goals:
- Use a single repository
- Few dependencies
- Ability to use alternate files based on OS or host
- Ability to encrypt and track confidential files
- Stay out of the way and let Git do what it's good at
Seek home for rest, for home is best.—Thomas Tusser
yadm can be installed using Homebrew.
brew tap TheLocehiliosan/yadm && brew install yadm
Several yum repositories are on Copr. Follow this link for repositories and installation instructions.
yadm is available in the Arch User Repos and can be installed with AUR helper or Makepkg
yaourt -S yadm
yadm is not yet available in the main gentoo portage tree, however an ebuild is available for you to use
mkdir -p /usr/local/portage/app-admin/yadm
curl -O 'https://raw.githubusercontent.com/TheLocehiliosan/yadm/master/gentoo/yadm-1.04.ebuild' -O 'https://raw.githubusercontent.com/TheLocehiliosan/yadm/master/gentoo/Manifest'
emerge -atv app-admin/yadm
If you have not configured portage to use
/usr/local/portage as your local
repository, you also need to add this to the portage
echo 'PORTDIR_OVERLAY="/usr/local/portage"' >> /etc/portage/make.conf
You can simply download the yadm script and put it into your
$PATH. Something like this:
curl -fLo /usr/local/bin/yadm https://github.com/TheLocehiliosan/yadm/raw/master/yadm && chmod a+x /usr/local/bin/yadm
I would not change my blest estate for all the world calls good or great.—Isaac Watts
If you know how to use Git, then you already know how to use yadm. See the man page for a comprehensive explanation of commands and options.
If you don't currently have a repository
Start out with an empty local repository
yadm add <important file>
Eventually you will want to push the local repo to a remote.
yadm remote add origin <url>
yadm push -u origin master
If you have an existing remote repository
clone will attempt to merge your existing repository, but if it fails, it will do a reset instead and you'll have to decide best on how resolve the differences.
yadm clone <url>
Strategies for alternate files on different systems
To feel at home, stay at home.—Clifton Fadiman
Where possible, you should try to use the same file on every system. Here are a few examples:
let OS=substitute(system('uname -s'),"\n","","")
if (OS == "Darwin")
" do something that only makes sense on a Mac
# use reattach-to-user-namespace as the default command on OSX
if-shell "test -f /usr/local/bin/reattach-to-user-namespace" 'set -g default-command "reattach-to-user-namespace -l bash"'
if [ "$system_type" = "Darwin" ]; then
eval $(gdircolors $HOME/.dir_colors)
eval $(dircolors -b $HOME/.dir_colors)
However, sometimes the type of file you are using doesn't allow for this type of logic. If a configuration can do an "include", you can include a specific alternate version using yadm. Consider these three files:
#---- .gitconfig -----------------
decorate = short
abbrevCommit = true
path = .gitconfig.local
#---- .gitconfig.local##Darwin ---
name = Tim Byrne
email = firstname.lastname@example.org
#---- .gitconfig.local##Linux ----
name = Dr. Tim Byrne
email = email@example.com
Configuring Git this way includes
.gitconfig.local in the standard
.gitconfig. yadm will automatically link the correct version based on the operation system. The bulk of your configurations can go in a single file, and you just put the exceptions in OS-specific files.
Of course, you can use yadm to manage completely separate files for different systems as well.
Sent from my MacBook
Dr. Tim Byrne
yadm will link the appropriate version for the current host, or use the default
Example of managing SSH configurations
We shape our dwellings, and afterwards our dwellings shape us.—Winston Churchill
Below is an example of how yadm can be used to manage SSH configurations. The example demonstrates yadm directly managing the
config file, managing a host-specific
authorized_keys file, and storing the private SSH key as part of its encrypted files. This example assumes a typical working SSH configuration exists, and walks through the steps to bring it under yadm's management.
yadm add ~/.ssh/config
mv ~/.ssh/authorized_keys ~/.ssh/authorized_keys##Linux.myhost
yadm add ~/.ssh/authorized_keys##Linux.myhost
echo '.ssh/id_rsa' >> ~/.yadm/encrypt
yadm add ~/.yadm/encrypt
Changes to be committed:
(use "git rm --cached <file>..." to unstage)
new file: .ssh/authorized_keys##Linux.myhost
new file: .ssh/config
new file: .yadm/encrypt
new file: .yadm/files.gpg
authorized_keys -> ~/.ssh/authorized_keys##Linux.myhost
config file is simply added. This will cause the same
config file to be used on other yadm managed hosts. The
authorized_keys file needs to be host specific, so rename the file using the OS and hostname. After adding the renamed
authorized_keys##Linux.myhost, yadm will automatically create the symlink for it. Last, the private key should be maintained in yadm's encrypted files. Add a pattern to the
.yadm/encrypt file which matches the private key. Then instruct yadm to encrypt all files matching the patterns found in
.yadm/encrypt. Notice that the yadm repository is not tracking the private key directly, rather it tracks the collection of encrypted files
.yadm/files.gpg. When these changes are brought onto another host, using the
yadm decrypt command will extract the files stored.