source/projects/cram/README.md

# Cram

> To force (people or things) into a place or container that is or appears to be too small to contain them.

An alternative to GNU Stow, more some notion of packages with dependencies and install scripts.

Think an Ansible or Puppet but anyarch and lite enough to check in with your dotfiles.

## Overview

Somewhat like Stow, Cram operates in terms of packages, which are directories with the following structure -

```
/REQUIRES      # A list of other packages this one requires.
/BUILD         # 1. Perform any compile or package management tasks.
/PRE_INSTALL   # 2. Any other tasks required before installation occurs.
/INSTALL       # 3. Do whatever constitutes installation.
               #    This supercedes the default copying of files.
/POST_INSTALL  # 4. Any cleanup or other tasks following installation
...            # Any other files are treated as package contents.

```

Cram reads a config dir with three groups of packages
- `packages.d/<packagename>` contains a package that installs but probably shouldn't configure a given tool, package or group of files.
  Configuration should be left to profiles.
- `profiles.d/<profilename>` contains a profile; a group of related profiles and packages that should be installed together.
- `hosts.d/<hostname>` contains one package for each host, and should pull in a list of profiles.
- Both profiles and hosts entries may specify their own "inline" packages as a convenience.

The intent of this tool is to keep GNU Stow's intuitive model of deploying configs via symlinks, and augment it with a useful pattern for talking about "layers" / "packages" of related configs.

Cram installs the package `hosts.d/$(hostname)`, and `profiles.d/default` by default.

## Usage

```
$ cram apply [--dry-run|--execute] [--optimize] <configdir> <destdir>
```

The `apply` task applies a configuration to a destination directory.
The most common uses of this would be `--dry-run`, which functions as a `diff` or `--execute ~/conf ~/` for emulating Stow and installing dotfiles.

Cram always reads the `.cram.log` state file and diffs the current state against the configured state.
Files and directories no longer defined by the configured state are cleaned up automatically.

```
$ cram show <configdir>
```

The `list` task loads up and prints the `.cram.log` state file generated by any previous `cram apply --execute` so you can read a manifest of what cram thinks it did.

```
$ cram list <configdir>
```

The `show` task lists out all available packages (eg. packages, profiles, hosts, and subpackages) as a dependency graph.

## License

Copyright Reid 'arrdem' McKenzie, 31/10/2021.

Published under the terms of the MIT license.
See the included `LICENSE` file for more.