om init

The om init command provides a better nix flake init experience. Specifically, it provides:

  1. a registry of flake templates that you can choose from
  2. support for template paramters that can be filled in by the user

To get started, run:

om init -o ~/myproject

This will prompt you to choose a template from the builtin registry (see below section), and then initialize it in the myproject directory.

Builtin registry

The builtin registry (stored in a flake) contains the following templates:

Initializing your own project templates

If your flake provides a om.templates output (see below section), then om init will recognize it. For example:

om init -o ~/myproject github:srid/haskell-flake

Because haskell-flake has a om.templates output, om init will prompt you to fill in the parameters defined in the template and initialize it.

You can also explicitly specify the template to choose from the flake:

om init -o ~/myproject github:srid/haskell-flake#haskell-flake

If there are multiple templates in the flake (as is the case with the builtin registry), omnix will the prompt the user to choose from them.

Configuration spec

Omnix templates can be defined by adding a om.template flake output. This should be an attrset of templates. The value should contain the keys template (referring to original flake template) as well as params, defined as follows:

There are two kinds of params. String params are defined as follows:

{
  name = "package-name";
  description = "Name of the Rust package";
  placeholder = "rust-nix-template";
}

Here, when prompting for this param, the user-provided value if any will replace the given placeholder text across all files in the template.

Boolean params are defined as follows:

{
  name = "vscode";
  description = "Include the VSCode settings folder (./.vscode)";
  paths = [ ".vscode" ];
  value = true;
}

Here, if the user enables this param, the path globs specified in paths will be retained in the template. Otherwise, the paths will be deleted. The value key provides a default value; which key is supported for string params as well.

Both parameter types are distinguished by the presence of the relevant keys (placeholder for string, paths for boolean).

Testing templates

The configuration can also include a tests key that defines a list of tests to run on the template. Each test is an attrset with params and asserts keys that indicates the parameter values to test along with the path existance assertions. For example:

{
  tests = {
    default = {
      # systems = [ ]; # Optional whitelist of systems to limit this test to
      params = {
        username = "john";
        git-email = "[email protected]";
        git-name = "John Doe";
        neovim = true;
      };
      asserts = {
        # Path assertion tests under template output
        source = {
          # true means the path must exist; false means it must not exist
          "modules/home/neovim/default.nix" = true;
          ".github/workflows" = false;
        };
        # Path assertion tests under the output of a Nix package
        packages."homeConfigurations.john.activationPackage" = {
          "home-path/bin/nvim" = true;
        };
      };
    };
  };
}