Tutorials

Contents

• Bootstrapping
• Adding other machines
• Refreshing
• Updating your castle
• Dealing with automated config files

Bootstrapping

In the installation section, you added a homeshick alias to your .bashrc file (substitute .cshrc for .bashrc if you are a csh or tcsh user).

Let's create your first castle to hold this file. You use the generate command to do that:

homeshick generate dotfiles

This creates an empty castle, which you can now populate.

Put the .bashrc file into your dotfiles castle with:

homeshick track dotfiles .bashrc

Be aware that your file has now been moved into the castle and a symlink to it has been created in its stead. So any modifications to your dotfiles repo will directly affect your dotfiles.

Let's now enter the castle, commit the changes, add your github remote and push to it.

homeshick cd dotfiles
git commit -m "Initial commit, add .bashrc"
git remote add origin git@github.com:username/dotfiles.git
git push -u origin master
cd -

Note: The .homesick/ folder is not a typo, it is named as such because of compatibility with homesick, the ruby tool that inspired homeshick

Adding other machines

To get your custom .bashrc file onto other machines you install homeshick and clone your castle with:

$HOME/.homesick/repos/homeshick/bin/homeshick clone username/dotfiles

homeshick will ask you immediately whether you want to symlink the newly cloned castle. If you agree to that and also agree to it overwriting the existing .bashrc you can run source $HOME/.bashrc to get your homeshick alias running.

Refreshing

You can run check to see whether your castles are up to date or need pushing/pulling. This is a task that is easy to forget, which is why homeshick has the refresh subcommand. It examines your castles to see when they were pulled the last time and prompts you to pull any castles that have not been pulled over the last week. You can put this into your .bashrc file to run the check everytime you start up the shell: printf '\nhomeshick --quiet refresh' >> $HOME/.bashrc. (The --quiet flag makes sure your terminal is not spammed with status info on every startup)

If you prefer to update your dotfiles every other day, simply run homeshick refresh 2 instead.

Updating your castle

To make changes to one of your castles you simply use git. For example, if you want to update your dotfiles castle on a machine where you have a nice tmux configuration:

homeshick track dotfiles .tmux.conf
homeshick cd dotfiles
git commit -m "Added awesome tmux configuration"
git push origin master
cd -

Dealing with automated config files

There are times when some programs attempt to auto generate / save config files and in so doing will overwrite the symbolic link that homeshick creates. This means files that were tracked become untracked and attempts to re-link result in either overwriting your changes or staying untracked. The most common culprit are programs that offer an internal method for making and saving config changes.

I'll show you how to diagnose such a situation and then how to fix it. For this tutorial I will use the tin news reader as the sample program. Tin uses the following directory structure for its config:

~/.tin
├── attributes
├── filter
├── news.example.com
│   ├── newsgroups
│   └── serverrc
├── posted
└── tinrc

The actual configuration variables are stored in tinrc and the rest are caches and other runtime files. So we need homeshick to track ~/.tin/tinrc. If you run a homeshick track myCastle ~/.tin/tinrc then it will create the following:

~/.homesick/repos/myCastle/home
└── .tin
    └── tinrc

~/.tin
├── attributes
├── filter
├── news.example.com
│   ├── newsgroups
│   └── serverrc
├── posted
└── tinrc@ -> ../.homesick/repos/myCastle/home/.tin/tinrc

Normally this is what we want but the next time we quit tin it will delete ~/.tin/tinrc and recreate it losing the symlink. To verify this is the case do an ls -la ~/.tin and you'll see the symlink missing. You will also experience homeshick complaining next time you do a link command.

To fix this we have to use the shallow symlink trick. However we need to prevent homeshick from tracking all the caches and temp files.

1. Remove the bad tracking file/directory.
2. Move the original config directory (temp files and all) into a custom directory in the myCastle repo.
3. Add a .gitignore file to ignore everything but the wanted files.
4. Add a symlink from home to the custom directory in the same repo.
5. Save to git.
6. Run homeshick link to finish the setup.

~ $ homeshick cd myCastle
~/.homesick/repos/myCastle $ git rm -r home/.tin             # Step 1
~/.homesick/repos/myCastle $ mkdir dotdirs
~/.homesick/repos/myCastle $ mv ~/.tin dotdirs/              # Step 2
~/.homesick/repos/myCastle $ nano dotdirs/.tin/.gitignore    # Step 3

# .gitignore contents:
*            # Ignore everything...
!.gitignore  # Except .gitignore
!tinrc       # Except tinrc

~/.homesick/repos/myCastle $ ln -s dotdirs/.tin home/.tin # Step 4
~/.homesick/repos/myCastle $ git add dotdirs/.tin home/.tin
~/.homesick/repos/myCastle $ git commit                      # Step 5
~/.homesick/repos/myCastle $ homeshick link                  # Step 6