files

In-repository file generation flake-parts module

As Nix users, we naturally want the source of all truth to reside within Nix files 📜 and other files that include that truth to be generated ⚡.

For example, who didn’t want to dynamically include various facts about their project in the readme and make sure those are up-to-date?

but

1. project repositories are expected to include tracked readmes 📄

2. Git tracked or not, .gitignore files must sometimes exist 🤷

3. .github/workflows/* must be Git tracked (don’t get me started on these)

4. and the list goes on

You may be thinking

Wait 🤔, so what if they must be tracked—I can still generate them from Nix and then check that my repository is clean.

And you’d be right! …except that checking that your repository is clean cannot be a flake check.

Okay, so I’ll make a flake check for each generated file.

Well, yes, you could. …or you could use this project—if you’re using flake-parts, that is (sorry).

Installation

To use these options, add to your flake inputs:

files.url = "github:mightyiam/files";

and inside the mkFlake:

imports = [
  inputs.files.flakeModules.default
];

Run nix flake lock and you’re set.

Options

perSystem.files.file

Files to be written and checked for. The attribute name is the file path relative to Git top-level. Use slashes for subdirectories (e.g. "diagrams/overview.md").

Type: lazy attribute set of (submodule)

Default:

{ }

Example:

{
  "README.md".text = "# My Project";
  ".gitignore".source = ./gitignore;
  "docs/guide.md".text = "...";
}

Declared by:

• files/flake-module.nix

perSystem.files.file.<name>.source

Path or derivation to use as the file content. Is set automatically when text is provided.

Type: absolute path

Declared by:

• files/flake-module.nix

perSystem.files.file.<name>.text

Text content of the file. Sets source automatically via pkgs.writeText.

Type: null or strings concatenated with “\n”

Default:

null

Declared by:

• files/flake-module.nix

perSystem.files.gitToplevel

Each check is performed by copying the existing file into the store and comparing its contents with the configured contents.

For that purpose a path to the file must be provided to Nix. Configured file paths are relative to the Git top-level. But Nix is oblivious to the Git top-level. So file paths are resolved relative to the value of this option.

The default value is correct when the flake is at the Git top-level. Otherwise the correct Git top-level must be provided.

Type: absolute path

Default:

self

Example:

../.

Declared by:

• files/flake-module.nix

perSystem.files.writer.app

Whether to enable setting up as a flake app.

Type: boolean

Default:

false

Example:

true

Declared by:

• files/flake-module.nix

perSystem.files.writer.drv

Provides an executable that writes each configured file’s contents to its path. Missing parent directories are created.

Consider including this in the project’s development shell.

Type: package (read only)

Declared by:

• files/flake-module.nix

perSystem.files.writer.exeFilename

The writer executable filename.

Type: (optionally newline-terminated) single-line string

Default:

"write-files"

Example:

"files-write"

Declared by:

• files/flake-module.nix