homesick: git-backed dotfile management for Ruby developers

What problem homesick solves, and who it is for

Dotfiles are the small set of hidden files in a home directory that configure shells, editors and tools. Keeping them in git is common; getting them back onto a new machine is where the friction is. You clone the repository somewhere, then copy or symlink each file by hand, and the copies drift from the repository the moment you edit them. homesick addresses that middle step. It clones a dotfiles repository into ~/.homesick/repos, treats it as a castle, and symlinks its contents into your home directory with one command. The README describes the model directly: a castle is a repository that contains a home directory, and home contains files and directories whose names begin with a dot. That naming rule is the whole contract. There is no manifest, no ignore file format to learn, and no per-file configuration. The audience is narrow on purpose. homesick is a Ruby gem, tested on Ruby 3.2, 3.3 and 3.4, so it assumes a Ruby toolchain on the machine. If your dotfiles are already in git and you are comfortable installing a gem, the workflow is short. If you want a single binary with no interpreter, this is the wrong starting point, and the README says so by pointing readers to homeshick.

How castles, linking and .homesick_subdir actually work

The data flow has three stages. First, homesick clone fetches the repository into ~/.homesick/repos, using a full git URL or the shorter owner/repo form for GitHub. Second, homesick link walks castle/home and creates symlinks in your home directory, so edits to ~/.vimrc land in the castle working tree rather than in a copy. Third, homesick commit, pull and push operate on that working tree, which means the castle is an ordinary git repository and nothing about the remote changes. The default linking depth is the interesting constraint. The README states that homesick link basically makes a symlink to only the first depth in castle/home. A directory like castle/home/.config is therefore linked as a whole, which breaks when you already have your own ~/.config with unrelated applications. The .homesick_subdir file in the castle root solves this. You list the directories whose subdirectories should be linked individually instead of wholesale. With .config in that file, homesick links castle/home/.config/fooapp to ~/.config/fooapp and leaves ~/.config/barapp alone. homesick track updates the file for you: tracking a nested path such as .emacs.d/elisp appends the parent directory to .homesick_subdir automatically. That automatic edit is convenient and also the part most likely to surprise, because the file changes as a side effect of tracking rather than through an explicit command.

Installing homesick and linking your first castle

homesick ships as a Ruby gem, so installation is a single gem command. The README gives this as the first step, and the gem requires one of the supported Ruby versions (3.2, 3.3 or 3.4).

The .homesickrc hook and its Ruby eval boundary

Some dotfiles need more than a symlink. A castle can include a .homesickrc file in its root, and homesick rc CASTLE runs it. The README is explicit about the mechanism: the file must be valid Ruby code because it is executed with Ruby's eval construct, and the current homesick object is passed in and available as self. That design has two consequences worth stating plainly. First, installing a castle is not a passive operation if its .homesickrc does something destructive; the README acknowledges this by noting that the rc operation normally asks for confirmation and that --force bypasses the prompt. Second, it couples castles to Ruby. A castle whose .homesickrc uses Ruby syntax cannot be consumed by homeshick, the shell alternative the README recommends for people who want to avoid the Ruby dependency. If you maintain castles for a mixed team, keeping .homesickrc either absent or trivial is what keeps the repository portable across both tools. The README documents no sandboxing, no dry-run flag for rc, and no list of what a castle's .homesickrc is permitted to touch, so reviewing that file before running the command is the only check available.

Where homesick gets in the way

The first-depth linking rule is the limitation most users will hit, and .homesick_subdir is a workaround rather than a fix: you must know in advance which parent directories need to be split, and you maintain that list inside the castle. A castle that links .config wholesale will collide with any application that writes to ~/.config independently. The second constraint is the Ruby dependency. homesick is tested only against Ruby 3.2, 3.3 and 3.4, so a machine with an older system Ruby, or one where you would rather not install a gem at all, is outside the supported path. The README addresses this directly by recommending homeshick for people who need homesick without the Ruby dependency. The third is the rc mechanism itself: executing castle-provided Ruby with eval means a cloned castle is code, not just configuration, and the only guard is a confirmation prompt that --force removes. There is no documented rollback for a link operation that created the wrong symlinks, and the README does not describe an unlink-all flag; homesick unlink takes a castle name. Finally, the project is a CLI with no daemon and no automatic sync, so push and pull are manual steps you schedule yourself.

homeshick, the shell alternative the README names

The difference between homesick and homeshick is not features but runtime. homeshick is a shell implementation of the same castle concept, and the README recommends it for anyone who needs homesick without the Ruby dependency. That single sentence defines the trade-off. With homeshick, a machine needs only a POSIX shell and git, which matters on minimal containers, routers or servers where installing Ruby is a real cost. With homesick, you get a Ruby implementation tested on three Ruby versions and a .homesickrc hook that runs Ruby code. The castle layout is compatible in the direction that matters: a repository with a home directory and dot-prefixed entries works with both. The .homesickrc file is where compatibility ends, since it is evaluated as Ruby. If your castles are plain symlink targets, choosing between the two comes down to whether Ruby is already present on your machines. If it is, homesick's track command and its commit, push and pull wrappers are the reason to pick it over writing your own symlink loop.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-07-17. The most recent release is v2.0.0, dated 2026-03-22, so the version line is current rather than stale. The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are included; the README states the copyright as Joshua Nichols, 2010, and points to the LICENSE file for details. This is a description of the licence text, not legal advice. Upgrade cost is low by design. homesick is a CLI that shells out to git and manipulates symlinks; the repository layout shows a lib directory, a bin directory and an rspec spec directory, so the surface area is a command set rather than a service. The main upgrade risk is environmental rather than behavioural: the supported Ruby versions are 3.2, 3.3 and 3.4, so a host pinned to an older Ruby needs a version manager before it can install the gem. Castles themselves do not need migration between homesick versions as far as the README documents, because the format is a directory named home with dot-prefixed entries.

Editorial conclusion

Adopt homesick if your dotfiles already live in git and you want symlink management, tracking and castle-level push and pull from one Ruby CLI. Skip it if you want zero runtime dependencies (homeshick is the shell alternative the README points to) or if you need nested linking without a .homesick_subdir file. Before committing, verify that your castle has a home directory and that Ruby 3.2, 3.3 or 3.4 is available, then run homesick generate or homesick clone and homesick link on a throwaway account to see exactly which paths get symlinked.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. technicalpickles/homesick on GitHub