Open-source project
technicalpickles/homesick avatar
technicalpickles/homesick

technicalpickles/homesick: dotfiles as a git repo, and the eval in .homesickrc

Your home directory is your castle. Don't leave your dotfiles behind.

2,455 stars128 forksRubyMIT

At a glance

What is it?
Homesick clones a dotfiles repository, calls it a castle, and symlinks its home directory into place. It also executes whatever Ruby a castle carries, which is the part worth reading before you clone someone else's.
Who is it for?
Homesick is a good fit if you already keep dotfiles in git and want one command to wire them into place, and a poor fit if you intend to run castles you did not write without reading them first. The mechanics are small and legible: generate or clone, link, commit, push.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 121 days ago.
What is it written in?
Mainly Ruby, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 13, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • technicalpickles/homesick2,455 ★ · +2
Star history
Repository2026-09-302026-11-13
technicalpickles/homesick2.5k2.5k

2 Stars in the last 44 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

A castle's .homesickrc is executed with Ruby's eval construct

This is the part of homesick to read twice. A castle may carry a file called .homesickrc in its root, and the contents of that file must be valid Ruby, because homesick executes it with Ruby's eval construct. The file is also handed the current homesick object while it runs, available inside the file as the self variable, so the script has access to the tool's own state rather than only to the Ruby standard library. The README is explicit that the operation can be destructive and that the command normally asks for confirmation before proceeding.

code
homesick rc CASTLE
homesick rc --force CASTLE

Put those two facts together and the shape of the risk is clear. The unit of trust here is a git repository, not a file. Cloning a castle is safe in itself, because a clone copies files and makes a directory under ~/.homesick. Running homesick rc on it is the step that hands the repository's contents to the Ruby interpreter. The confirmation prompt is the only barrier between those two states, and --force removes it. A castle you wrote is a script you have already read. A castle you cloned from a stranger is a script you have not, and nothing in the command's output tells you which one you are about to run.

link replaces dotfiles with symlinks, and unlink is the way back

The everyday commands are short enough to take in one screen.

code
gem install homesick
homesick generate ~/.homesick/repos/my-dotfiles
homesick track ~/.vimrc my-dotfiles
homesick clone git://github.com/technicalpickles/pickled-vim.git
homesick clone technicalpickles/pickled-vim
homesick link pickled-vim
homesick unlink pickled-vim

link is the step that touches your home directory. It symlinks the contents of the castle's home directory into place, which means the files that were there become links pointing into ~/.homesick. Anything you had at those paths is no longer the file you were editing, it is a pointer, and editing through the link edits the clone. unlink reverses that and the README says you can remove symlinks at any time. The cast of characters is small enough to state plainly: list shows what is cloned, pull --all|CASTLE fetches one or every castle, commit and push manage the repository, cd opens a shell in its root, open starts your $EDITOR there, and exec CASTLE COMMAND plus exec_all COMMAND run a shell command inside one castle or inside every one. That last pair is the second place a cloned repository gets to run something, and unlike rc it takes the command from you rather than from the castle.

link stops at the first level, which is what .homesick_subdir exists for

homesick link basically makes a symlink to only the first depth inside castle/home, and that single design decision explains most of the friction the tool has. The README works through the case with a directory tree: a castle holding .config/fooapp with three files, and a home directory that already has .config/barapp with three files of the same names. Because link only descends one level, it links .config itself and would collide with the barapp configuration you already keep there. The escape hatch is a file called .homesick_subdir at the root of the castle, listing the directories you want it to descend into instead of stopping at.

code
castle/.homesick_subdir

    .config

You can write that file yourself, or let homesick write the line for you with homesick track NESTED_FILE CASTLE. The two examples in the README differ in a small way worth copying exactly: the hand written file holds .config alone, while the file homesick adds for you holds .config and then .emacs.d on a line indented with a tab. The generated file and the hand written one are not formatted the same way, which is a hint that the subdir file is meant to be machine maintained once you start tracking nested paths.

The long clone example uses git:// and the short one does not

Two clone forms appear a few lines apart, and the difference between them is the transport. The first is a full URL built on the git:// protocol, which is the unauthenticated one: no key, no token, nothing to configure, and nothing that identifies who is cloning. The second drops the protocol and the path and gives homesick just owner and repository, with the README calling it a slightly shorter way for something hosted on GitHub. The README does not say why both exist or whether they differ in anything but spelling, which leaves a reader to guess that the short form is a GitHub convenience layered on top of the general one. Elsewhere the same convenience appears: homesick generate will add a GitHub remote automatically if you have a github.user set in your git config. So the tool leans on your git configuration in two separate places, the remote it creates and the shorthand it accepts, and neither behaviour is optional once the setting is present.

One tag, v2.0.0, and four months of commits after it

The release record is thin. There is exactly one GitHub release, v2.0.0, published 2026-03-22, and the last recorded push to the default branch master is 2026-07-17. So the branch carries roughly four months of work that no tag points at, and a reader who installs from the tag gets a March snapshot while the branch they cloned by default is a July one. The default branch is master rather than main, which is the older convention and means a plain clone lands on the working line instead of a stable one. The project also lists no homepage at all, so there is no site to read and the README's links are the whole surface. The supported Ruby versions are given as a short list, 3.2, 3.3 and 3.4, which is recent enough to rule out the older interpreters the tool was originally written for and narrow enough to state in three lines. Between the release gap and the branch name, pinning matters more here than it would in a project with a steady tag stream.

Test tooling is configured in three files, and contributors are told not to touch the Rakefile

The root is a conventional Ruby gem layout with more configuration than the README describes. There is a homesick.gemspec, a Rakefile, a Gemfile with a committed Gemfile.lock, bin/ for the executable, lib/ for the code and spec/ for the tests. Alongside them sit .rspec for the test runner, .rubocop.yml for style and .mutant.yml for mutation testing, which is the practice of rewriting the code under test to check that the suite actually notices. A Guardfile is there as well, for running checks while you edit, and a committed Gemfile.lock pins the development dependencies exactly. None of it is in the README, which instead gives its contribution rules in four bullets: fork, make the change, add tests, open a pull request, with bonus points for topic branches. The instruction that has teeth is the one about commits: do not touch the rakefile, version or history, and if you want your own version, bump it in a separate commit that can be ignored when merging. That is a maintainer protecting release mechanics, and it explains why the version bump is not part of a normal pull request.

homeshick is the named answer for anyone without Ruby, and the copyright line is from 2010

The last section of the README before the copyright notice answers a question the rest of the file never raises: what if you do not have Ruby. It points at homeshick, a separate project under a different owner, as the way to use the same idea without the Ruby dependency. That is the only alternative the project names, and it is named by link rather than compared, so no feature differences are given. Two older artifacts sit next to it. The copyright line reads Copyright (c) 2010 Joshua Nichols, sixteen years before the v2.0.0 tag, while the license recorded for the repository is MIT and a LICENSE file sits at the root, so the terms are clear even though the notice has not been touched. And the README is README.markdown next to a .document file, which is an rdoc convention for telling a documentation generator what to include, a leftover from a packaging era before Markdown READMEs became the norm. Neither detail affects behaviour. Both are the sort of thing you notice when you decide whether a tool still looks like something you would want to depend on.

Editorial conclusion

Homesick is a good fit if you already keep dotfiles in git and want one command to wire them into place, and a poor fit if you intend to run castles you did not write without reading them first. The mechanics are small and legible: generate or clone, link, commit, push. The exposure is in .homesickrc, which is executed with Ruby's eval construct, so read that file before running homesick rc on any castle, including one you just cloned. Check two smaller things while you are there. The supported versions are Ruby 3.2, 3.3 and 3.4, and the only tag is v2.0.0 from 2026-03-22, so the branch has moved well past the release you would install. And if Ruby is not available at all, the README names homeshick as the alternative rather than leaving you to find one.

Frequently asked questions

What is technicalpickles/homesick and what does it call a castle?

It is a Ruby gem that clones a git repository of dotfiles into ~/.homesick and symlinks the contents into your home directory. Such a repository is called a castle, and to qualify it must contain a home directory whose files and directories begin with a dot.

How do I install homesick, and is there an alternative?

The install command is gem install homesick. For anyone who does not want the Ruby dependency, the README points at homeshick, a separate project hosted at github.com/andsens/homeshick, without comparing the two.

What does homesick rc do with a .homesickrc file?

The contents must be valid Ruby, because the file is executed with Ruby's eval construct, and the homesick object is passed in as the self variable during execution. The command asks for confirmation before proceeding because the operation can be destructive, and homesick rc --force CASTLE skips that prompt.

Which Ruby versions does homesick support?

The README lists 3.2, 3.3 and 3.4. The repository ships a homesick.gemspec, a Rakefile, a bin/ directory and spec/ tests at the root, and its only release is v2.0.0 from 2026-03-22.

How do I link nested config directories with homesick?

homesick link only symlinks the first level inside castle/home. To descend further, list the directories you want traversed in a .homesick_subdir file at the root of the castle, or run homesick track NESTED_FILE CASTLE, which adds that line for you.

How do I remove homesick symlinks and manage a castle?

homesick unlink CASTLE removes the symlinks. The other commands are homesick list, homesick pull --all or homesick pull CASTLE, homesick commit CASTLE, homesick push CASTLE, homesick cd CASTLE, homesick open CASTLE, and homesick exec CASTLE COMMAND with homesick exec_all COMMAND.

Official sources

  1. Issues
  2. License: MIT
  3. README
  4. Releases
  5. technicalpickles/homesick on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/technicalpickles-homesick.svg)](https://hysenlabs.com/projects/technicalpickles-homesick)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/technicalpickles-homesick.svg)](https://hysenlabs.com/projects/technicalpickles-homesick)

Was this useful?