Symlinking

Linking table

homeshick does not blindly symlink everything, instead it uses a carefully crafted linking strategy to achieve a high level of flexibility without resorting to configuration files.

The table below shows how homeshick decides what to do in different situations.

   $HOME\Castle       | directory | not directory

--------------------------|-----------|-------------- nonexistent | mkdir | link symlink to castle | rm!&mkdir | identical file/symlinked file | rm?&mkdir | rm?&link directory | identical | rm?&link directory (symlink) | identical | rm?&link

Explanation

homeshick traverses through all resources (files, folders and symlinks) of the home/ folder of a castle in a depth-first manner. Symlinks are not followed.
The table is consulted for each resource that is encountered. .git files and directories are ignored and not traversed.

The columns directory and not directory represent the resource in the castle. The rows represent what resource is found at the corresponding location in the actual $HOME directory.

In the castle, directory is a simple directory (and not a symlink to a directory), while not directory is everything that is not the former (so: files, symlinked files, and symlinked directories).

The resources that can be encounter in the $HOME directory are categorized as follows:

• nonexistent means that the corresponding resource in the $HOME folder does not exist.
• symlink to castle represents a symlink to the current resource
• file/symlinked file is a symlink to anything but the current resource
• directory is a regular directory
• directory (symlink) is a symlinked directory (but not to the castle)

The actions that can be taken always refer to the $HOME directory:

• identical: Do not perform any action, resources are identical
• mkdir: Create the directory
• link: Create a symlink to the resource in the castle
• rm!: Delete without prompting (this is only done for legacy directory symlinks)
• rm?: Prompt whether the user wants to overwrite the resource (--skip answers "no" to this, while --force does the opposite. --batch selects the default, which is "no")

Deep symlinking vs. flat symlinking

Files outside your home directory

Repos with no home directory

What do you do if you encounter a really cool repository that goes well with your existing setup, but it has no home/ folder and needs to be linked to a very specific place in your $HOME folder?

Let's say you want to add vundle to your Vim configuration. The documentation says it needs to be installed to ~/.vim/bundle/vundle, but you are not very interested in forking the repository solely for the purpose of changing the directory layout so that all files are placed four directories deeper in home/.vim/bundle/vundle/.

homeshick can solve this problem in two ways:

1. Add vundle as a submodule to your dotfiles. This is definitely the quick and easy way.

    homeshick cd dotfiles
    cd ..
    git submodule add https://github.com/gmarik/vundle.git home/.vim/bundle/vundle
   

2. Clone vundle with homeshick and symlink to the repo from the appropriate folder in your dotfiles:

    homeshick clone gmarik/vundle
    cd ~/.homeshick/repos/dotfiles/home
    mkdir .vim/bundle
    cd .vim/bundle
    ln -s ../../../../vundle vundle # symlink to the location of the cloned vundle repository
    homeshick link dotfiles
   

We use a relative path for the symlink in case we log in with different username on other machines.
When running the [[link|Commands#link]] command, homeshick will create a symlink at ~/.vim/bundle/vundle pointing at the symlink we just created. This means there will be a symlinked directory at ~/.vim/bundle/vundle, which contains the files of the cloned vundle repository
Note: You can see how homeshick decides what to do when encountering different symlink situations by looking at the linking table.

The advantage of the second option is that you have more finegrained control over your repositories and can manage each of them individually (e.g. you want to [[refresh|Commands#refresh]] your own dotfiles every week, but you don't want to wait for all the submodules in your repository to refresh as well).

The downside of not using submodules is that you will need to add the additional repositories with homeshick clone on every machine. However, you can use the automatic deployment script to avoid having to do this manually.