homectl - Simple Package Management for ~

Table of Contents

• Introduction
• Prerequisites
• Quick-Start
  • Installation
  • Uninstallation
• Further Reading

Introduction

homectl is an easy way to keep your various dot-files, configuration files, custom shell scripts or add-on packages in your home directory version-controlled and organized across multiple machines and in different environments.

Features

• Split your config files, scripts, etc. into "packages":

  • Post the common stuff to the Internet

  • Keep a private package for your work-related config and scripts.

  • Make another package for your open-source development or hobbies.

  • Only enable what you need, where you need it.

• It automatically conforms to your environment:

  • Different shells (bash, zsh).

  • Different platforms (Linux, Darwin, probably others).

  • Different values of $HOME (no absolute paths, one hard-coded path: $HOME/.homectl).

• Keep it all version-controlled inside git.

  • A single git clone copies your whole environment anywhere you like.

  • Use git submodules for 3rd-party packages like oh-my-zsh or obscure Emacs modes.

  • Private packages can stay safely outside your homectl git repository.

Prerequisites

• You must be using the bash or zsh shell.

• You need recent versions of Python and Git.

• You should already be familiar with Git, since you will be using it to track your own homectl setup.

Quick-Start

Installation

# Get a copy of the latest stable homectl.
$ git clone git://github.com/josh-berry/homectl.git

# Create your own homectl setup.
$ ./homectl/setup.sh ~/homectl-setup

# Move your existing .rc files into homectl
mv .bashrc bashrc.old
mv .zshenv zshenv.old
# etc...

# Link your setup into your home directory.
$ ~/homectl-setup/deploy.sh

Next Steps:

• Read doc/customization.asciidoc to learn how to create your own homectl packages.

• Create packages to hold your personal configuration.

• Restart your shell, and use the hc command to enable and disable packages.

Uninstallation

This will disable homectl entirely, removing any dot-files in your home directory that point to homectl packages.

$ homectl uninstall

Further Reading

We suggest you read these in order.

doc/customization.asciidoc

The anatomy of a homectl package, and how to create your own.

doc/hacking.asciidoc

A quick guide to hacking on homectl itself. Covers high-level design principles and submitting your own improvements.