Flake Refs
Flakes do not have to reside on disk - you can use flakes published in git repositories too! This makes it possible to deliver package scripts, development environments and more directly from github repositories. This is somewhat akin to having a custom homebrew tap or debian package mirror.
.
- the flake in the local directory
github:nix4noobs/first-flake
- flake in repo
first-flake
in the github organizationnix4noobs
. github:<user|organization>/<repo>
- flake in repo
git+https://github.com/nix4noobs/first-flake
- same flake as above - but this approach works non-GH repos too
github:nix4noobs/first-flake/master
- Use the
master
branch of thefirst-flake
repo owned bynix4noobs
- Use the
github:nix4noobs/first-flake/6a7b8f9f009e3185c5e5ffb31d9ec9383ab97e4d
- Use the specified commit
github:nix4noobs/first-flake?dir=nix
- Use flake in
nix
dir of the repofirst-flake
- (Note: this directory does not exist in the actual repository, this is just a example)
- Use flake in
Note
When first referencing a remote flake, nix will fetch it and place
it in its store.
If the flake later changes then you can add --refresh
to your
nix flake
command to refresh the store's copy.
Not getting the latest from a flake can seem confusing to newcomers - so consider making "release" branches which don't change.
Warning
Flakes are typically shared as git repositories, though it is possible to serve a flake as a tarball over HTTP or a file path on a networked drive.
:imp:When a flake is part of a git repository, then only the changes
which are staged are considered
- remember to git add
your
changes, otherwise the flake command won't take your changes
into account!
This can seem confusing, but nix strongly favors hermetic builds. By only considering what is staged, it makes it less likely that you push your repo only for a user to discover that some changes were not committed.
Referencing flake outputs
.. _sec-flake-ref-cli:
Listing available outputs
The nix flake show <flake-ref>
provides a quick way to see what a flake
provides. Below is an example listing the outputs of
refs4noobs:
$ nix flake show github:nix4noobs/refs4noobs
github:nix4noobs/refs4noobs/274c89fc508b5e5c927b44bc92caa215b51f9b97
├───devShells
│ ├───aarch64-darwin
│ │ ├───blue: development environment 'blue'
│ │ └───yellow: development environment 'yellow'
│ ├───aarch64-linux
│ │ ├───blue: development environment 'blue'
│ │ └───yellow: development environment 'yellow'
│ └───x86_64-linux
│ ├───blue: development environment 'blue'
│ └───yellow: development environment 'yellow'
├───formatter
│ ├───aarch64-darwin: package 'nixfmt-0.5.0'
│ ├───aarch64-linux: package 'nixfmt-0.5.0'
│ └───x86_64-linux: package 'nixfmt-0.5.0'
├───packages
│ ├───aarch64-darwin
│ │ ├───cowsay: package 'cowsay-3.04'
│ │ └───hello: package 'hello-2.12.1'
│ ├───aarch64-linux
│ │ ├───cowsay: package 'cowsay-3.04'
│ │ └───hello: package 'hello-2.12.1'
│ └───x86_64-linux
│ ├───cowsay: package 'cowsay-3.04'
│ └───hello: package 'hello-2.12.1'
└───templates
└───starter-22-11: template: starter for 22.11
In this flake we see the following outputs:
- Two development shells,
blue
andyellow
- A formatter entry (which tool to use when formatting .nix files using
nix fmt
) - two packages,
hello
andcowsay
- a template,
starter-22-11
Using outputs
Note
We have not yet introduced packages, development shells or templates.
However, focus on the point that each command refers to the output by the
form <flake-ref>#<output-name>
and that the type of output used is
implied by the command. So nix develop
only looks as devShell
outputs while nix build
looks at package outputs.
Using a development shell
Dev shells are launched via nix develop
, for
example, to launch the dev shell named yellow
in the refs4noobs
flake
whose outputs we listed above, run:
nix develop github:nix4noobs/refs4noobs#yellow
Using a package
Packages are a collection of files, typically
a software program, which can be installed into the Nix store. Packages can
sometimes be "run" - that is, the principal program in a package, e.g. emacs
in the emacs package, can be executed directly from your shell.
In refs4noobs, there are two packages defined in the
flake, cowsay
and hello
, to run cowsay, try:
nix run github:nix4noobs/refs4noobs#cowsay -- "hello"
.
Note that --
separates input args for nix
with arguments intended for
the program, this is a common convention for Linux CLI tools.
Using a template
In our hello world flake, we created our first
flake from scratch using the nix flake init
command.
Flakes created this way are made from a very basic template which leaves a bit
to be desired.
However, we can ask to create a flake from a template which we or others have
made in advance. To create a new flake from the starter-22-11
template in
refs4noobs, run the following command: