Add mdBook Documentation

.github/workflows/publish-mdbook.yml

@@ -0,0 +1,42 @@
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    paths: ["/book"]
+
+name: Publish mdBook
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install mdBook
+        uses: actions-rs/[email protected]
+        with:
+          crate: mdbook
+          version: latest
+          use-tool-cache: true
+      - name: Build mdBook
+        run: mdbook build book
+      - name: Publish to Netlify (Stable)
+        if: ${{ github.ref == 'refs/heads/main' }}
+        uses: nwtgck/[email protected]
+        with:
+          publish-dir: book/book
+          production-branch: main
+          production-deploy: true
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+      - name: Publish to Netlify (Preview)
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: nwtgck/[email protected]
+        with:
+          publish-dir: book/book
+          alias: ${{ github.head_ref }}
+          production-branch: main
+          production-deploy: false
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

README.md

@@ -1,202 +1,18 @@
 # Hoard
 
+[![Netlify Status](https://api.netlify.com/api/v1/badges/b91e71ce-673e-466c-a6ff-2b877ec0dd97/deploy-status)](https://app.netlify.com/sites/hoard-docs/deploys)
+
 `hoard` is a program for backing up files from across a filesystem into a single directory
 and restoring them later.
 
 Most people will know these programs as "dotfile managers," where dotfiles are configuration
 files on *nix (read: non-Windows) systems. Files on *nix systems are marked as hidden by
 starting the file name with a dot (`.`).
 
-## Terminology
-
-- "Environment": An identifiable system configuration consisting of zero or more each of:
-  operating system, hostname, environment variable, executables in `$PATH`, and/or existing
-  paths,
-- "Pile": A single file or directory with multiple possible paths where it can be found
-  depending on the environment(s).
-- "Hoard": One of:
-  - A single anonymous pile.
-  - One or more named, related piles.
-
-## Usage
-
-### Subcommands
-
-- Backup: `hoard [flags...] backup [name] [name] [...]`
-  - Back up the specified hoard(s). If no `name` is specified, all hoards are backed up.
-- Restore: `hoard [flags...] restore [name] [name] [...]`
-  - Restore the specified hoard(s). If no `name` is specified, all hoards are restored.
-- Validate: `hoard [flags...] validate`
-  - Attempt to parse the default configuration file (or the one provided via `--config-file`)
-    Exits with code `0` if the config is valid.
-
-### Flags
-
-- `--help`: View the program's help message.
-- `-V/--version`: Print the version of `hoard`.
-- `-c/--config-file`: Path to (non-default) configuration file.
-- `-h/--hoards-root`: Path to (non-default) hoards root directory.
-
-### Verbosity
-
-Output verbosity is controlled by the logging level. You can set the logging level with the
-`HOARD_LOG` environment variable. Valid values (in decreasing verbosity) are:
-
-- `trace`
-- `debug`
-- `info`
-- `warn`
-- `error`
+## Documentation
 
-The default logging level is `info` for release builds and `debug` for debugging builds.
-
-### Default file locations
-
-- Configuration file
-  - Linux: `$XDG_CONFIG_HOME/hoard/config.toml` or `/home/$USER/.config/hoard/config.toml`
-  - macos: `$HOME/Library/Application Support/com.shadow53.hoard/`
-  - Windows: `C:\Users\$USER\AppData\Roaming\shadow53\hoard\config.toml`
-- Hoards root
-  - Linux: `$XDG_DATA_HOME/hoard/hoards` or `/home/$USER/.local/share/hoard/hoards`
-  - macos: `$HOME/Library/Application Support/com.shadow53.hoard/hoards`
-  - Windows: `C:\Users\$USER\AppData\Roaming\shadow53\hoard\data\hoards`
-
-More specifically, `hoard` uses the [`directories`](https://docs.rs/directories) library,
-placing the configuration file in the `config_dir` and the hoards root in the `data_dir`.
+You can find all documentation at https://hoard.rs.
 
 ## Configuration
 
-See [`config.toml.sample`](config.toml.sample) for a documented example configuration
-file.
-
-### Environments
-
-Environments can be matched on one or more of five possible factors:
-
-- `os`: [Operating System](https://doc.rust-lang.org/stable/std/env/consts/constant.OS.html)
-- `env`: Environment variables
-  - Can match on just existence or also a specific value.
-- `hostname`: The system hostname.
-- `exe_exists`: Whether an executable file exists in `$PATH`.
-- `path_exists`: Whether something exists (one of) the given path(s).
-
-All the above factors can be written using two-dimensional array syntax. That is,
-`["foo", ["bar, "baz"]]` is interpreted as `(foo) OR (bar AND baz)`, in whatever way applies
-to that given factor.
-
-It is an error to include an `AND` condition for `os` or `hostname`, as a system can only have
-one of each.
-
-```toml
-[envs]
-[envs.example_env]
-    # Matching something *nix-y
-    os = ["linux", "freebsd"]
-    # Either sed and sh, or bash, must exist
-    exe_exists = ["bash", ["sh", "sed"]]
-    # Require both $HOME to exist and $HOARD_EXAMPLE_ENV to equal YES.
-    # Note the double square brackets that indicate AND instead of OR.
-    env = [[
-      { var = "HOME" },
-      { var = "HOARD_EXAMPLE_ENV", expected = "YES" },
-    ]]
-```
-
-### Exclusivity
-
-The exclusivity lists indicate names of environments that are considered mutually exclusive to
-each other -- that is, cannot appear in the same environment condition -- and the order indicates
-which one(s) have precedence when matching environments.
-
-See the [example config file](config.toml.sample) for a more thorough example.
-
-```toml
-exclusivity = [
-    # Assuming all else the same, an environment condition string with "neovim" will take
-    # precedence over one with "vim", which takes precedence over one with "emacs".
-    ["neovim", "vim", "emacs"]
-]
-```
-
-### Hoards
-
-Hoards consist of one or more piles, where each pile is a mapping of *environment condition
-strings* to paths on the filesystem.
-
-An *environment condition string* is one or more environment names separated by pipes. The
-system must match ALL environments in the string in order for the associated path to be
-considered.
-
-The following rules determine which path to use for a pile:
-
-1. The condition string with the most environments wins.
-2. If multiple conditions have the most environments, the exclusivity list is used to
-   determine if one takes precedence.
-3. If multiple conditions have the same precedence, an error is printed and `hoard` exits.
-4. If no conditions match, the pile is skipped and a warning is printed.
-
-```toml
-[hoards]
-# This hoard consists of a single anonymous pile
-[hoards.simple_hoard]
-    # This is "foo" and "bar" separated by a pipe character (`|`).
-    # It will use this path if the system matches both environments "foo" and "bar".
-    "foo|bar" = "/path/to/a/thing"
-    # This path is considered if the system matches the environment "baz".
-    # It will use this path if one of "foo" or "bar" doesn't match. Otherwise, "foo|bar"
-    # takes precedence because it is a longer condition (more environments to match).
-    "baz" = "/some/different/path"
-
-[hoards.complex_hoard]
-# This hoard consists of two named piles: "first" and "second".
-[hoards.complex_hoard.first]
-    "foo|bar" = "/some/path/first"
-    "baz" = "/some/different/path/first"
-[hoards.complex_hoard.second]
-    "foo|bar" = "/some/path/second"
-    "baz" = "/some/different/path/second"
-```
-
-### Pile Configuration
-
-Pile configuration can be defined at three different levels:
-
-1. Globally
-2. Per-Hoard
-3. Per-Pile
-
-For a given Pile, any/all three of the levels of configuration are "layered" together, as appropriate for each
-configuration item:
-
-- Ignore patterns are merged and deduplicated.
-- Encryption settings will use the most-specific settings.
-
-#### Ignore Patterns
-
-Set `ignore` to a list of [glob patterns](https://en.wikipedia.org/wiki/Glob_(programming)) indicating files and folders
-to ignore. These lists will be merged across all levels of configuration.
-
-```toml
-# ... snip env definitions of "foo" and "bar" ...
-
-# Top-level config, applies to all hoards
-[config]
-    # Ignore the .git folder at any depth
-    ignore = ["**/.git"]
-
-[hoards]
-[hoards.anon_hoard]
-    "foo" = "/some/path"
-    "bar" = "/some/other/path"
-[hoards.anon_hoard.config]
-    ignore = [
-        "**/.*", # Ignore all hidden files on Linux/macOS
-        "*.log", # Ignore all top-level log files
-    ]
-[hoards.named_hoard]
-[hoards.named_hoard.config]
-    ignore = ["ignore-in-named-only"]
-[hoards.named_hoard.pile1]
-    "foo" = "/some/named/path"
-    "bar" = "/another/named/path"
-```
+See [`config.toml.sample`](config.toml.sample) for a documented example configuration file.

book/.gitignore

@@ -0,0 +1 @@
+book

book/book.toml

@@ -0,0 +1,16 @@
+[book]
+authors = ["Michael Bryant"]
+language = "en"
+multilingual = false
+src = "src"
+title = "The Hoard Book"
+description = "The official documentation for the Hoard dotfile manager"
+
+[rust]
+edition = "2021"
+
+[output.html]
+preferred-dark-theme = "ayu"
+mathjax-support = false
+cname = "hoard.shadow53.dev"
+edit-url-template = "https://github.com/Shadow53/hoard/edit/master/{path}"

book/src/README.md

@@ -0,0 +1,19 @@
+# Welcome to Hoard!
+
+`hoard` is a program for backing up files from across a filesystem into a single directory
+and restoring them later.
+
+Most people will know these programs as "dotfile managers," where dotfiles are configuration
+files on *nix (read: non-Windows) systems. Files on *nix systems are marked as hidden by
+starting the file name with a dot (`.`).
+
+`hoard` aims to be a little more useful than other dotfile managers:
+
+1. Many dotfile managers store files in a structure based on their path relative to the user's home directory. This is
+   useful in most cases, but can cause problems when wanted to share files across systems that don't use the same paths,
+   e.g., Windows and Linux. `hoard` instead namespaces files based on the ["Hoard" and "Pile"](./terminology.md) they
+   are configured in, then relative to the root of the Pile. This makes it easy to backup and restore files to very
+   different locations.
+
+2. Most dotfile managers do not prevent you from accidentally destructive behavior. See [Checks](cli/checks.md) for more
+   information.

book/src/SUMMARY.md

@@ -0,0 +1,15 @@
+# Summary
+
+- [Introduction](./README.md)
+- [Terminology](./terminology.md)
+- [File Locations](./file-locations.md)
+
+- [Command-Line Tool](./cli/README.md)
+    - [Installation](./cli/installation.md)
+    - [Flags and Subcommands](./cli/flags-subcommands.md)
+    - [Logging](./cli/logging.md)
+    - [Checks](./cli/checks.md)
+
+- [Configuration File](./config/README.md)
+    - [Environments](./config/envs.md)
+    - [Hoards and Piles](./config/hoards-piles.md)

book/src/cli/README.md

@@ -0,0 +1,3 @@
+# Command-Line Tool
+
+This section describes the usage and behavior of the command-line tool `hoard`.

book/src/cli/checks.md

@@ -0,0 +1,18 @@
+# Pre-Operation Checks
+
+To help protect against accidentally overwriting or deleting files, `hoard` runs some consistency
+checks prior to running any operations.
+
+To skip running the checks, run `hoard` with the `--force` flag. There is not currently a way to disable
+individual checks.
+
+## Last Paths
+
+This check compares the paths used previously with a given hoard to the ones resolved for the current
+operation. If any of these paths differ, a warning is displayed and the operation(s) canceled.
+
+## Remote Operations
+
+By default, `hoard` logs information about successful operations to a directory that is intended to be
+synchronized with the main hoards directory. This information is used to determine if a given file was
+last modified by a remote system. If so, a warning is displayed and the operation(s) canceled.

book/src/cli/flags-subcommands.md

@@ -0,0 +1,18 @@
+# Flags
+
+Flags can be used with any subcommand and must be specified *before* any subcommand.
+
+- `--help`: View the program's help message.
+- `-V/--version`: Print the installed version of `hoard`.
+- `-c/--config-file`: Path to (non-default) configuration file.
+- `-h/--hoards-root`: Path to (non-default) hoards root directory.
+
+# Subcommands
+
+- Backup: `hoard [flags...] backup [name] [name] [...]`
+  - Back up the specified hoard(s). If no `name` is specified, all hoards are backed up.
+- Restore: `hoard [flags...] restore [name] [name] [...]`
+  - Restore the specified hoard(s). If no `name` is specified, all hoards are restored.
+- Validate: `hoard [flags...] validate`
+  - Attempt to parse the default configuration file (or the one provided via `--config-file`)
+    Exits with code `0` if the config is valid.

book/src/cli/installation.md

@@ -0,0 +1,11 @@
+# Installation
+
+This page lists the supported methods of installing `hoard`.
+
+## Cargo
+
+If you have `cargo` and the Rust toolchain installed, you can install `hoard` with the following command:
+
+```bash
+cargo install hoard
+```

book/src/cli/logging.md

@@ -0,0 +1,13 @@
+# Logging
+
+Output verbosity is controlled by the logging level. You can set the logging level with the
+`HOARD_LOG` environment variable. Valid values (in decreasing verbosity) are:
+
+- `trace`
+- `debug`
+- `info`
+- `warn`
+- `error`
+
+The default logging level is `info` for release builds and `debug` for debugging builds.
+

book/src/config/README.md

@@ -0,0 +1,3 @@
+# Configuration File
+
+This section describes the configuration file format, with examples.