Hoards and Piles

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:

The condition string with the most environments wins.
If multiple conditions tie for most environments, the exclusivity list is used to determine if one takes precedence.
If multiple conditions have the same precedence, an error is printed and hoard exits.
If no conditions match, the pile is skipped and a warning is printed.

[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"

Environment Variables

Paths may contain environment variables. Environment variables must be written as ${ENVVAR}, where ENVVAR is the environment variable. As an example, the following hoard could be used to back up a user's Documents folder on Linux and Windows.

[hoards.documents]
    "linux" = "${HOME}/Documents"
    "windows" = "${USERPROFILE}/Documents"

For the user myuser, this expands to the following:

[hoards.documents]
    "linux" = "/home/myuser/Documents"
    "windows" = "C:/Users/myuser/Documents"

If the environment variable does not exist (i.e. is not defined), an error is returned and the operation is canceled.

Limitations

There is no support for default values, i.e. ${MYVAR:-"/some/default"}

Pile Configuration

Pile configuration can be defined at three different levels:

Globally
Per-Hoard
Per-Pile

For a given Pile, any/all three of the levels of configuration are "layered" together, as appropriate for each configuration item:

Hashing algorithms use the most-specific layer, or the default if not specified.
Ignore patterns are merged and deduplicated.
Encryption settings will use the most-specific settings.

Hashing Algorithms

Set hash_algorithm to one of the below strings to manually set which hashing algorithm is used when recording Hoard operations.

"sha256" (default): SHA-256 is an older but unbroken algorithm.
"md5": MD5 is a quick algorithm but also cryptographically broken. Supported for compatibility with an older operation log format and should be avoided.

Ignore Patterns

Set ignore to a list of glob patterns indicating files and folders to ignore. These lists will be merged across all levels of configuration.

# ... 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"

File Permissions

For a general discussion of file/folder permission support in Hoard, including Windows-specific limitations, see this page.

Hoard supports setting permissions separately for files and folders, using file_permissions and folder_permissions, respectively. These can be specified in two different ways: a "mode" and boolean flags.

Mode

A "mode" is an octal (base 8) integer representing read, write, and execute permissions for the owning user, users in the owning "group", and all other users. See the Wikipedia article for more.

You can specify a "mode" in TOML by prefixing the number with 0o. For example, a common file mode is 0o644 (read/write for the owner user, readonly for everyone else).

[config]
    file_permissions = 0o644

If using a "mode" is too confusing, you can also use a set of boolean flags: just set these to true or false:

Flags

Note: only is_writable is supported on Windows. All other flags are ignored. Note 2: "others" in the context of these boolean flags are a combination of the "group" and "other" values from a file "mode".

is_readable: the owning user can read the contents of the file or folder. This should not be set to false and is provided for completeness' sake.
is_writable: the owning user can modify and delete the file or folder.
is_executable: this has different meanings depending on whether it applies to files or folders:
- true for files means that the user can run the file as an executable program.
- true for folders means that the user can list the contents of the folder.
- In short, this should always be true for folders.
others_can_read: like is_readable but for non-owner users.
others_can_write: like is_writable but for non-owner users.
others_can_execute: like is_executable but for non-owner users.

# ... snip env definitions of "foo" and "bar" ...

# Top-level config, applies to all hoards
[config]
    # These represent the current defaults used by Hoard:
    # owner-only access.
    file_permissions = 0o600
    folder_permissions = 0o700

[hoards]
[hoards.anon_hoard]
    "foo" = "/some/path"
    "bar" = "/some/other/path"
[hoards.anon_hoard.config.file_permissions]
    # Equivalent to a 0o644 mode
    is_readable = true
    is_writable = true
    others_can_read = true
[hoards.anon_hoard.config.folder_permissions]
    # Equivalent to a 0o755 mode
    is_readable = true
    is_writable = true
    is_executable = true
    others_can_read = true
    others_can_execute = true

The Hoard Book