feat: add bats tests, docs (#139)

* fix(test): ensure bats file list uses xargs

* docs(readme): use yarn for testing instructions

* fix(test): ensure pipelines fail properly

* docs(alias): fix table header

---------

Signed-off-by: Ismo Vuorinen <ismo@ivuorinen.net>

.github/README.md

@@ -43,6 +43,12 @@ see what interesting stuff you've done with it. Sharing is caring.
 | `local/bin`         | Helper scripts that I've collected or wrote. |
 | `scripts`           | Setup scripts.                               |
 
+### Host specific configuration
+
+Configurations under `hosts/<hostname>` are applied only when running on the
+matching machine. Each host folder contains its own `install.conf.yaml` that
+is processed by Dotbot during installation.
+
 ### dotfile folders
 
 | Repo      | Destination | Description                                 |
@@ -58,6 +64,21 @@ see what interesting stuff you've done with it. Sharing is caring.
 
 Running `dfm` gives you a list of available commands.
 
+#### Documentation generation
+
+`dfm docs` generates Markdown documentation under the `docs/` directory. The
+subcommands are:
+
+```bash
+dfm docs alias        # regenerate alias table
+dfm docs folders      # document interesting folders
+dfm docs keybindings  # update keybinding docs for tmux, nvim and others
+dfm docs all          # run every docs task
+```
+
+The `docs/` folder contains generated cheat sheets, keybindings and other
+reference files. New documentation can be added without modifying this README.
+
 ## Configuration
 
 The folder structure follows [XDG Base Directory Specification][xdg] where possible.
@@ -73,6 +94,31 @@ The folder structure follows [XDG Base Directory Specification][xdg] where possi
 
 Please see [docs/folders.md][docs-folders] for more information.
 
+## Managing submodules
+
+This repository uses Git submodules for external dependencies. After cloning,
+run:
+
+```bash
+git submodule update --init --recursive
+```
+
+To pull submodule updates later use:
+
+```bash
+git submodule update --remote --merge
+```
+
+The helper script `add-submodules.sh` documents how each submodule is added and
+configured. Submodules are automatically updated by the
+[update-submodules.yml](.github/workflows/update-submodules.yml) workflow.
+
+## Testing
+
+Shell scripts under `local/bin` are validated with [Bats](https://github.com/bats-core/bats-core).
+Run `yarn test` to execute every test file. Bats is installed as a development
+dependency, so run `yarn install` first if needed.
+
 [dfm]: https://github.com/ivuorinen/dotfiles/blob/main/local/bin/dfm
 [docs-folders]: https://github.com/ivuorinen/dotfiles/blob/main/docs/folders.md
 [xdg]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html