Documentation tweaks

projects/cram/README.md

@@ -4,23 +4,20 @@
 
 An alternative to GNU Stow, more some notion of packages with dependencies and install scripts.
 
-## Usage
+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 -
 
 ```
-# cram [--dry-run | --execute] <configdir> <destdir>
+/REQUIRES      # A list of other packages this one requires.
-$ cram ~/conf ~/  # --dry-run is the default
+/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.
-Cram operates in terms of packages, which are directories with the following structure -
+               #    This supercedes the default copying of files.
-
-```
-/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
 /POST_INSTALL  # 4. Any cleanup or other tasks following installation
-
+...            # Any other files are treated as package contents.
-...            # Any other files are treated as package contents
 
 ```
 
@@ -34,3 +31,34 @@ Cram reads a config dir with three groups of packages
 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.

projects/cram/src/python/cram/__main__.py

@@ -201,7 +201,7 @@ def cli():
 
 @cli.command()
 @click.option("--execute/--dry-run", default=False)
-@click.option("--state-file", default=".cram.log")
+@click.option("--state-file", default=".cram.log", type=Path)
 @click.option("--optimize/--no-optimize", default=False)
 @click.argument("confdir", type=Path)
 @click.argument("destdir", type=Path)
@@ -211,10 +211,11 @@ def apply(confdir, destdir, state_file, execute, optimize):
     # Resolve the two input paths to absolutes
     root = confdir.resolve()
     dest = destdir.resolve()
-    statef = root / state_file
+    if not state_file.is_absolute():
+        state_file = root / state_file
 
     new_fs = build_fs(root, dest)
-    old_fs = load_fs(statef)
+    old_fs = load_fs(state_file)
 
     # Middleware processing of the resulting filesystem(s)
     executable_fs = scrub(old_fs, new_fs)
@@ -226,7 +227,7 @@ def apply(confdir, destdir, state_file, execute, optimize):
     if execute:
         executable_fs.execute()
 
-        with open(statef, "wb") as fp:
+        with open(state_file, "wb") as fp:
             pickle.dump(new_fs._log, fp)
 
     else:
@@ -235,12 +236,14 @@ def apply(confdir, destdir, state_file, execute, optimize):
 
 
 @cli.command()
-@click.option("--state-file", default=".cram.log")
+@click.option("--state-file", default=".cram.log", type=Path)
 @click.argument("confdir", type=Path)
 def show(confdir, state_file):
+    """List out the last `apply` state in the <confdir>/.cram.log or --state-file."""
     root = confdir.resolve()
-    statef = root / state_file
+    if not state_file.is_absolute():
-    fs = load_fs(statef)
+        state_file = root / state_file
+    fs = load_fs(state_file)
     for e in fs._log:
         print(*e)
 
@@ -248,6 +251,7 @@ def show(confdir, state_file):
 @cli.command()
 @click.argument("confdir", type=Path)
 def list(confdir):
+    """List out packages, profiles, hosts and subpackages in the <confdir>."""
     packages = load_config(confdir)
     for pname in sorted(packages.keys()):
         p = packages[pname]
@@ -255,6 +259,7 @@ def list(confdir):
         for d in p.requires():
             print(f"- {d}")
 
+
 if __name__ == "__main__" or 1:
     logging.basicConfig(
         level=logging.DEBUG,