homeshick

Create a new castle

$ homeshick generate [castle_name]

$ homeshick track [castle_name] [path/to/file]

$ homeshick cd [castle_name]

$ homeshick clone [github_username]/[repository_name]

$ homeshick link [castle_name]

homeshick <command> [options] [arguments]

clone <repo_url> [<castle_name>]
    Clones a Git repository as a new 'castle' into homeshick's managed directory. If <castle_name> is omitted, it defaults to the repository's name.

pull [<castle> ...]
    Pulls the latest changes from the remote repository for the specified 'castle(s)'. If no 'castle' is specified, it pulls for all managed castles.

push [<castle> ...]
    Pushes local changes to the remote repository for the specified 'castle(s)'. If no 'castle' is specified, it pushes for all managed castles.

status [<castle> ...]
    Shows the Git status (e.g., uncommitted changes, untracked files) for the specified 'castle(s)'. If no 'castle' is specified, it shows status for all managed castles.

track <file> [<file> ...]
    Moves an existing file from your home directory into its respective 'castle' and creates a symbolic link back to the original location. This marks the file for homeshick management.

link [<castle> ...]
    Creates or re-establishes symbolic links from the specified 'castle(s)' to your home directory. If no 'castle' is specified, it links all managed castles.

list
    Lists all 'castles' currently managed by homeshick.

generate <castle_name>
    Creates a new, empty 'castle' (Git repository) ready for you to add dotfiles to it.

refresh
    Checks and re-establishes all symbolic links from all managed 'castles' to the home directory, ensuring consistency.

cd <castle>
    Changes the current directory into the specified 'castle's' repository.

shell <command>
    Executes an arbitrary shell command within each of your managed 'castles'.

-v, --verbose
    Enable verbose output, showing more details about operations.

-q, --quiet
    Suppress output, making operations quiet.

-f, --force
    Force operations, such as overwriting existing files during linking.

-n, --dry-run
    Perform a trial run with no changes made, showing what would happen.

--help
    Display help information for homeshick or a specific command.

--version
    Display the homeshick version.

Homeshick is a lightweight and easy-to-use dotfile manager built on Git. It helps you manage your configuration files (dotfiles like .bashrc, .vimrc, .gitconfig) by storing them in Git repositories, which it calls 'castles'. Instead of scattering your dotfiles directly in your home directory, homeshick clones them into a hidden directory (e.g., ~/.homesick/repos/) and then creates symbolic links from those 'castles' back to your home directory.

This approach allows you to keep your dotfiles version-controlled, synchronized across multiple machines, and easily shareable. It leverages Git for all the heavy lifting (pulling, pushing, branching, diffing), making it familiar for Git users. Being written purely in Bash, homeshick has minimal dependencies, making it highly portable and efficient for managing personal configurations.

Homeshick relies heavily on Git; therefore, Git must be installed and properly configured on your system. While it simplifies dotfile management, users should still have a basic understanding of Git commands for advanced operations or troubleshooting. It's primarily designed for Unix-like systems (Linux, macOS) and may not behave as expected on Windows environments without WSL or similar layers. Be cautious when using the --force option, as it can overwrite existing files in your home directory.

In homeshick terminology, a 'castle' refers to a Git repository that contains your dotfiles. These repositories are typically stored under ~/.homesick/repos/. Each 'castle' can contain a collection of related configuration files, allowing you to organize your dotfiles logically (e.g., one castle for general shell configs, another for Vim, etc.).

When you manage dotfiles with homeshick, the original files are moved into their respective 'castles' within the ~/.homesick/repos/ directory. Homeshick then creates symbolic links (symlinks) from these locations back to where the applications expect them to be (e.g., ~/.bashrc links to ~/.homesick/repos/my-shell-castle/bashrc). This ensures applications find their configuration files while keeping the actual files version-controlled and neatly organized within the 'castles'.

Homeshick was created by Lars H. Nielsen as a simple alternative for managing dotfiles, aiming for a tool that was easy to use, understood Git principles, and required minimal dependencies. It gained popularity for its straightforward Bash-based implementation, which makes it highly portable and robust for Unix-like systems. Its development has focused on maintaining simplicity and leveraging Git's power without over-complicating the user experience.

git(1), stow(1), rcm(1), ln(1)