Dots

Dots is a CLI tool that aims to be a "one-button" solution for linking, importing, and exporting dotfiles.

Rather than keeping dotfiles spread across various folders in your home directory, Dots lets you keep them all in a single version-controlled folder, and is able to link all of them into their correct places with a single command. It also provides automatic zip and unzip capabilities in that folder for effortless imports and exports.

Installation

Install Dots with the following steps:

1. Install Ruby
2. Install Bundler
3. Clone the repo with git clone git@github.com:samuelporter/dots.git
4. Run the install.sh script in the repo root, follow any instructions it gives you. You may need to run it multiple times until it succeeds.
5. Add the following alias to your .zshrc file (optional, also assumes you cloned Dots to your home directory - change the folder if not!): alias dots='~/dots/dots.rb'

Usage

Dotfile directory

To use Dots, you will first need to set up a dotfile directory to be compatible with GNU Stow.

The recommended layout of this directory is as follows: ("a" and "b" are example programs with configuration files)

~/
└─ dotfiles/
   └─ a/
   |  └─ .config/
   |     └─ a/
   |        └─ a.conf
   └─ b/
      └─ b_conf/
         └─ b.conf

From the above ~/dotfiles directory, running stow a and stow b will create symbolic links for each program in your home directory, like this:

~/
└─ .config/
|  └─ a/
|     └─ a.conf
└─ b_conf/
   └─ b.conf

Creating a separate folder for each program in your ~/dotfiles directory makes it simple to organize and selectively link multiple dotfiles for each.

First time setup

When using Dots for the first time, cd into the dotfiles directory you've set up above and run dots init.

You'll be prompted to select a number of subfolders in that directory to include in a "Stowfile". (See more about Stowfiles below, in the dots init documentation, or by running dots help init.)

Once you select and confirm those folders, your Stowfile will be created, and you'll be able to run other commands like dots link and dots export.

If you're importing dotfiles from a zip that already includes a Stowfile, you can skip the dots init step and instead run dots import to populate your dotfiles folder.

Commands

When in doubt, run dots help to get a list of available commands. It should print something like this:

Commands:
  dots.rb export from_directory to_zip  # Export dotfiles from a directory to a zip
  dots.rb help [COMMAND]                # Describe available commands or one specific command
  dots.rb import from_zip to_directory  # Import dotfiles from a zip into a directory
  dots.rb init directory                # Enable Dots in a directory by creating a Stowfile
  dots.rb link directory                # Link dotfiles

Each command also has a longer description available by running dots help {command}.

Those longer descriptions are also included below.

dots init

Initialize a Stowfile in a directory to enable running of Dots commands from that directory.

Dots relies on a custom file called a "Stowfile" to know where your dotfiles are. A Stowfile contains a list of subdirectories from the directory containing the Stowfile, each having a structure compatible with GNU Stow. For example, with a directory structure like this:

Stowfile
neofetch/
└─ .config/
|  └─ neofetch/
|     └─ config.conf
tmux/
└─ .config/
   └─ tmux/
      └─ tmux.conf

The "neofetch" and "tmux" directories above are both compatible with Stow, so the Stowfile could just contain two rows:

neofetch
tmux

This would tell Dots that both of these folders are able to be linked by running Stow, and register both of them to be linked when dots link is run.

dots link

Symbolically link dotfiles with GNU Stow, creating references to the original files in your home directory.

Linking files to the home directory instead of storing them there allows them to be stored and maintained in a safe central place. Combined with version control and a tool like Dots, linking makes it much easier to back up and share dotfiles.

dots import

Import dotfiles from a zip into a local folder.

Importing is most useful when moving between machines or sharing dotfiles with others. By default, it will not overwrite existing files in the target folder with anything extracted from the zip, and will prompt the user before continuing with an import when conflicts are found.

dots export

Export dotfiles from a directory to a zip file.

Exporting is the opposite of importing - it lets you convert dotfiles in a directory into a shareable or portable format. Files and folders can be excluded as needed.