[Readme] Add readme

.config/alacritty/alacritty.toml

@@ -1,9 +1,5 @@
 # Alacritty configuration written in TOML
 
-[general]
-live_config_reload = true
-ipc_socket = true
-
 [window]
 opacity = 0.95
 blur = true

.ssh/config

@@ -0,0 +1,3 @@
+Host git.pumppi.dev
+    HostName git.pumppi.dev
+    Port 2222

.stow-local-ignore

@@ -0,0 +1,21 @@
+# This file replaces stow's built-in ignore list, so the defaults are repeated here
+RCS
+.+,v
+CVS
+\.\#.+
+\.cvsignore
+\.svn
+_darcs
+\.hg
+\.git
+\.gitignore
+\.gitmodules
+.+~
+\#.*\#
+^/README.*
+^/LICENSE.*
+^/COPYING
+
+# Repository files that do not belong in $HOME
+^/\.stow-local-ignore
+^/\.gitconfig\.local\.example

README.md

@@ -1,7 +1,49 @@
 # My dotfiles
-These are my most important dotfiles. These include only the most important configurations that are
-not limited to one device or coding project. At the moment this config is used by one Debian machine
-and one Fedora machine.
+These are my most important dotfiles. They include only the configurations that are not limited to
+one device or coding project. At the moment this config is used by one Debian machine and one Fedora
+machine.
+
+## Intended use
+The repository mirrors the layout of `$HOME`: every file here lives at the same relative path it
+should have in the home directory (`.bashrc` → `~/.bashrc`, `.config/nvim` → `~/.config/nvim`, ...).
+The whole repository is a single [GNU Stow](https://www.gnu.org/software/stow/) package, so
+installing the dotfiles is just a matter of symlinking it into `$HOME`. Files that belong to the
+repository rather than to `$HOME` are listed in `.stow-local-ignore`.
+
+Machine-specific settings are kept out of the repository and loaded from local files instead, e.g.
+`~/.gitconfig.local` (see `.gitconfig.local.example`) and `.config/sway/config.local`.
+
+## Installation
+```sh
+# Install stow (Debian / Fedora)
+sudo apt install stow   # or: sudo dnf install stow
+
+# Clone into your home directory, including submodules (kitty themes, i3blocks-contrib)
+git clone --recurse-submodules <repo-url> ~/dotfiles
+cd ~/dotfiles
+
+# Symlink everything into $HOME
+stow -t ~ .
+
+# Local git settings, e.g. commit signing key
+cp .gitconfig.local.example ~/.gitconfig.local
+```
+
+Stow refuses to overwrite existing files. If a config already exists in `$HOME`, remove or back it
+up first, or use `stow --adopt -t ~ .` to move the existing file into the repository and review the
+result with `git diff`.
+
+### Updating
+Pull the changes and restow to pick up new or removed files:
+```sh
+git pull --recurse-submodules
+stow -R -t ~ .
+```
+
+### Uninstalling
+```sh
+stow -D -t ~ .
+```
 
 ## Problems?
 ### Rootless Docker