From f22075aa2572018a29776e7a02d2d0dab96394cf Mon Sep 17 00:00:00 2001
From: Adam Gausmann <agausmann@fastmail.com>
Date: Mon, 17 Dec 2018 00:37:44 -0600
Subject: [PATCH] Update README

---
 README.md             | 72 ++++++++++++++++++++++++++++++++++---------
 install.sh => install |  0
 2 files changed, 58 insertions(+), 14 deletions(-)
 rename install.sh => install (100%)

diff --git a/README.md b/README.md
index 6deff90..320791c 100644
--- a/README.md
+++ b/README.md
@@ -2,21 +2,65 @@
 
 My personal dotfiles and configurations.
 
-## The Contents
+## Contents
 
-- `common` - A set of configuration files common to every system.
-- `$hostname` - Configuration files specific to the system with the given hostname.
-- `$x` - Additional (optional) configurations that can also be added.
+- `common/` - A set of configuration files common to every system.
 
-## The System
+- `$hostname/` - Configuration files specific to the system with the given
+  hostname.
 
-Each subdirectory of this repository is a collection of files to install
-relative to the current user's home directory (assumed to be `$HOME`)
-which are merged into the home directory by the `install.sh` script.
-The script chooses specific subdirectories and merges them in the following
-order, with precedence given to the more recently-listed subdirectory if two or
-more contain a file at the same path:
+- `$x/` - Additional (optional) configurations that can also be added.
 
-- Command-line arguments (precedence given first-to-last)
-- System hostname
-- The `common` directory
+- `install` - A file-copying utility script.
+
+## Configuration
+
+Each subdirectory in this repository is a collection of configuration files
+relative to the user's home directory. For example, adding the file
+`common/.config/x` will install it to `$HOME/.config/x` when the `install`
+script chooses the `common` subdirectory.
+
+Files are chosen from these subdirectories in order, with precedence given to
+the subdirectory listed first if multiple have a file in the same location:
+
+- Custom subdirectories passed by command line (from left to right).
+
+- The subdirectory that is the same as the system's hostname.
+
+- The `common` subdirectory.
+
+Note that any files existing in the subdirectory will be created, but the
+script cannot detect when files are removed and will not attempt to remove
+anything from the home directory.
+
+## Installation
+
+Made easy by the `install` script.
+
+### Requirements
+
+- `rsync`, used as the smart file copy utility.
+
+### Environment
+
+- `HOME` - The home directory of the user running this script.
+
+- `HOSTNAME` - The hostname of this system. If not present, defaults to the
+  value of `hostname`.
+
+- `DOTFILES` - The repository root. If not present, the directory containing
+  the `install` script is used.
+
+### Steps
+
+```
+# Fetch the repository (if you haven't already):
+git clone git@gitlab.com:agausmann/dotfiles.git ~/.dotfiles
+cd ~/.dotfiles
+
+# Make sure submodules are up to date (thinks like third-party Vim plugins):
+git submodule update --init
+
+# Run the script:
+./install [ custom_targets ... ]
+```
diff --git a/install.sh b/install
similarity index 100%
rename from install.sh
rename to install