# `nix-freeze-tree`
[](https://builds.sr.ht/~jack/nix-freeze-tree?)
[](https://www.gnu.org/licenses/agpl-3.0.html)
`nix-freeze-tree` is a utility that walks a directory tree, and writes
out [Nix](https://nixos.org/nix/) expressions which rebuild that
tree. The generated expressions have two important properties:
1. Each file in the tree is built by a separate fixed-output
derivation, and
2. Directories are built by derivations that symlink their contents
recursively.
If you are using `nix copy` to ship a derivation between nix stores,
copying the derivation built by evaluating the output of
`nix-freeze-tree` can reuse existing files in the destination store,
as fixed-output derivations can be checked against a hash before
copying.
I use this to speed up deploys to my personal website. Running
`nix-freeze-tree` on the output from [my site
generator](https://git.sr.ht/~jack/jackkelly-name) and importing the
result means that `nix copy` only uploads new files, instead of
copying a single giant derivation containing every image on the site.
## Installation
### Nix
If you use Nix, you can install the command into your local
environment by running `nix-env -f
https://git.sr.ht/~jack/nix-freeze-tree/archive/master.tar.gz -iA
command`.
### Cabal
If you have GHC installed, you can also build and install the binary
by running `cabal v2-install nix-freeze-tree`. You can also run the
binary from the build directory with `cabal v2-run nix-freeze-tree --
ARGS`.
## Usage
```
Usage: nix-freeze-tree [--version] [-f|--force] [-v|--verbose]
[-o|--out-root OUT_ROOT] [IN_DIR]
Write a tree of nix expressions to OUT_ROOT that build a derivation,
symlinking every file in IN_DIR as a separate fixed-output derivation.
Available options:
--version Display version information and exit.
-h,--help Show this help text
-f,--force If any default.nix exist in the output directory,
remove them and generate anyway
-v,--verbose Display messages while working.
-o,--out-root OUT_ROOT Where to write the nix files (default: IN_DIR)
IN_DIR Directory to freeze (default: .)
```
## Calling from Nix
This repository's `default.nix` gives access to a function `freeze`,
which can be used to freeze the output of an existing derivation.
You can use it with Nix code that looks a bit like:
```nix
let
# Some nixpkgs from somewhere
nixpkgs = ...;
# Whether you get it from a channel, a local checkout,
# builtins.fetchTarball or builtins.fetchgit is up to you
nix-freeze-tree-repo = builtins.fetchTarball { ... };
# Derivation to freeze
drv = mkDerivation { ... };
# Evaluate default.nix from nix-freeze-tree-repo and hold onto the
# freeze function
freeze = (import nix-freeze-tree-repo { inherit nixpkgs; }).freeze;
in
freeze drv
```
## FAQ
Q: Why didn't you use
[`symlinkJoin`](https://nixos.org/nixpkgs/manual/#chap-trivial-builders)
to tie all the subtrees together?
A: I had the program mostly working before I remembered that
`symlinkJoin` existed. I thought about making each file's derivation
contain the directories leading up to it and then `symlinkJoin`ing
them all together, but decided against it for three reasons:
1. You can easily build subtrees using the Nix expressions generated
by `nix-freeze-tree`;
2. Building the output of `nix-freeze-tree` will correctly create
empty directories present in the input; and
3. Files are hashed based on their content alone, not their position
in the tree-to-be-frozen (reducing duplication).
## Other Resources
* Questions should go to the
[nix-freeze-tree-discuss](https://lists.sr.ht/~jack/nix-freeze-tree-discuss)
mailing list.
* Bug reports should go to the [bug
tracker](https://todo.sr.ht/~jack/nix-freeze-tree).