Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kamadorueda/alejandra

The Uncompromising Nix Code Formatter
https://github.com/kamadorueda/alejandra

fmt format formatter formatting nix rust style-guide styleguide

Last synced: 29 days ago
JSON representation

The Uncompromising Nix Code Formatter

Awesome Lists containing this project

README

        

Alejandra 💅

The Uncompromising Nix Code Formatter



CI/CD



Coverage



License: The Unlicense


style: Alejandra



Try it on your browser!

here

## Features

- ✔️ **Fast**

It's written in [Rust](https://www.rust-lang.org/)
and formats [Nixpkgs](https://github.com/NixOS/nixpkgs)
in just a few seconds.
[^benchmark-specs]

- ✔️ **Powerful**

We define a comprehensive style
for all possible combinations of the Nix expression language.

- ✔️ **Reliable**

High coverage, battle tested.

From Nix's eyes, code is _just_ the same.
[^semantic-changes]

- ✔️ **Beautiful**

Beauty is subjective, right?

We started from the original style of
[Nixpkgs](https://github.com/NixOS/nixpkgs),
and then we applied the feedback of developers
who have used [Nix](https://nixos.org) at scale
for several years,
producing a very **well-grounded** [**style guide**](./STYLE.md).

- ✔️ **Transparent**

You won't notice the formatter after a while.

Humans care about the content,
machines about the style!

- ✔️ **Native**

We integrate with common code editors and workflows:

- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=kamadorueda.alejandra)
- [Neovim](./integrations/neovim/README.md)
- [Vim](./integrations/vim/README.md)
- [GNU Emacs](./integrations/gnu-emacs/README.md)
- [Doom Emacs](./integrations/doom-emacs/README.md)
- [Pre-commit](./integrations/pre-commit/README.md)
- [Pre-commit-hooks.nix](./integrations/pre-commit-hooks-nix/README.md)

## Getting started

### On the web editor

Please visit:
[kamadorueda.github.io/alejandra](https://kamadorueda.github.io/alejandra/).

### Prebuilt binaries

You can download a binary for your platform:

- [aarch64-unknown-linux-musl](https://github.com/kamadorueda/alejandra/releases/download/3.0.0/alejandra-aarch64-unknown-linux-musl)
- [armv6l-unknown-linux-musleabihf](https://github.com/kamadorueda/alejandra/releases/download/3.0.0/alejandra-armv6l-unknown-linux-musleabihf)
- [armv7l-unknown-linux-musleabihf](https://github.com/kamadorueda/alejandra/releases/download/3.0.0/alejandra-armv7l-unknown-linux-musleabihf)
- [i686-unknown-linux-musl](https://github.com/kamadorueda/alejandra/releases/download/3.0.0/alejandra-i686-unknown-linux-musl)
- [x86_64-unknown-linux-musl](https://github.com/kamadorueda/alejandra/releases/download/3.0.0/alejandra-x86_64-unknown-linux-musl)

Make it executable (`$ chmod +x`)
and run Alejandra with:

```bash
$ ./alejandra --help
```

or:

```bash
$ /path/to/alejandra --help
```

### From [Nixpkgs](https://github.com/nixos/nixpkgs)

Please visit: [search.nixos.org/packages?query=alejandra](https://search.nixos.org/packages?channel=unstable&show=alejandra&from=0&size=50&sort=relevance&type=packages&query=alejandra).

### Nix installation

- Nix stable:

```bash
$ nix-env -ivf https://github.com/kamadorueda/alejandra/tarball/3.0.0
```

- Nix with [Flakes](https://wiki.nixos.org/wiki/Flakes):

```bash
$ nix profile install github:kamadorueda/alejandra/3.0.0
```

Then run Alejandra with:

```bash
$ alejandra --help
```

### NixOS installation

- Nix stable:

```nix
let
alejandra =
(import (builtins.fetchTarball {
url = "https://github.com/kamadorueda/alejandra/tarball/3.0.0";
sha256 = "0000000000000000000000000000000000000000000000000000";
}) {})
.outPath;
in {
environment.systemPackages = [alejandra];
}
```

- Nix with [Flakes](https://wiki.nixos.org/wiki/Flakes):

```nix
{
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";

alejandra.url = "github:kamadorueda/alejandra/3.0.0";
alejandra.inputs.nixpkgs.follows = "nixpkgs";
};

outputs = {alejandra, nixpkgs, ...}: {
nixosConfigurations = {
example = nixpkgs.lib.nixosSystem rec {
# We support: aarch64-darwin, aarch64-linux, i686-linux, x86_64-darwin, x86_64-linux
system = "x86_64-linux";

modules = [
{
environment.systemPackages = [alejandra.defaultPackage.${system}];
}
# Import your other modules here
# ./path/to/my/module.nix
# ...
];
};
};
};
}
```

## Do I need to configure anything?

- No.

## Discussion

- [RFC 0101 - Nix formatting](https://github.com/NixOS/rfcs/pull/101)

## Cool libraries

- [NixEL](https://github.com/kamadorueda/nixel)
- [Santiago](https://github.com/kamadorueda/santiago)
- [rnix-parser](https://github.com/nix-community/rnix-parser)

## Alternatives

- [nixpkgs-fmt](https://github.com/nix-community/nixpkgs-fmt)
- [nixfmt](https://github.com/serokell/nixfmt)

See why Alejandra was created
and a comparison between alternatives
[here](https://discourse.nixos.org/t/the-uncompromising-nix-code-formatter/17385/3?u=kamadorueda).

Alternatively, checkout the code examples of the different formatters [here](https://github.com/kamadorueda/rfc-0101).

## Versioning

We use [semver](https://semver.org/) to version Alejandra.

Our public API consists of:

- The formatting rules (a.k.a. the style).
- The CLI tool (`$ alejandra`),
command line flags,
positional arguments,
exit codes,
and stdout.

## Changelog

Please read: [CHANGELOG](./CHANGELOG.md).

## Contributors

The following people have helped improving Alejandra.

Thank you ❤️

- [Kevin Amado](https://github.com/kamadorueda) ~
[Email](mailto:[email protected]),
[LinkedIn](https://www.linkedin.com/in/kamadorueda).
- [Thomas Bereknyei](https://github.com/tomberek).
- [Piegames](https://github.com/piegamesde).
- [Joachim Ernst](https://github.com/0x4A6F).
- [David Arnold](https://github.com/blaggacao).
- [David Hauer](https://github.com/DavHau).
- [Ryan Mulligan](https://github.com/ryantm).
- [Fabian Möller](https://github.com/B4dM4n).
- [Rok Garbas](https://github.com/garbas).
- [Yorick van Pelt](https://github.com/yorickvP).
- [Rehno Lindeque](https://github.com/rehno-lindeque).
- [Rebecca Turner](https://github.com/9999years).
- [Jörg Thalheim](https://github.com/Mic92).
- [Nathan Henrie](https://github.com/n8henrie).
- [Vincent Ambo](https://github.com/tazjin).
- [Jamie Quigley](https://github.com/Sciencentistguy).
- [Loïc Reynier](https://github.com/loicreynier).
- [Mr Hedgehog](https://github.com/ModdedGamers).
- [Tobias Bora](https://github.com/tobiasBora).
- [Tristan Maat](https://github.com/TLATER).
- [Victor Engmark](https://github.com/l0b0).
- [Norbert Melzer](https://github.com/NobbZ).
- [Patrick Stevens](https://github.com/Smaug123).
- [Connor Baker](https://github.com/ConnorBaker).
- [Matthew Kenigsberg](https://github.com/mkenigs).
- [Florian Finkernagel](https://github.com/TyberiusPrime).

## Footnotes

[^benchmark-specs]:
Running on a [machine](https://github.com/kamadorueda/machine) with:

- CPU: 4 physical, 4 logical, 11th Gen Intel(R) Core(TM) i7-1165G7 @ 2.80GHz
- MHz: from 400 to 4700 MHz
- BogoMips: 5606.40
- Cache L3: 12 MiB

Using:

```bash
# x86_64-unknown-linux-gnu
$ time alejandra --threads $threads /path/to/nixpkgs
```

Results:

| $threads | Seconds |
| :------: | :-----: |
| 1 | 45 |
| 2 | 25 |
| 4 | 14 |

[^semantic-changes]: The methodology to claim this is:

1. Checkout [Nixpkgs](https://github.com/nixos/nixpkgs) and run:

```bash
$ nix-env -qaf . --drv-path --xml > before
```

1. Now format with Alejandra and run:

```bash
$ nix-env -qaf . --drv-path --xml > after
```

As of 2022-06-22,
there are 41 differences in a set of 38109 derivations
because of things like this:

```
goDeps = ./deps.nix;
```

Since `./deps.nix` was also formatted
you get a semantical difference.

This is something that should be solved on Nixpkgs
and not a bug in Alejandra.
For example:

- https://github.com/NixOS/nixpkgs/pull/178378
- https://github.com/NixOS/nixpkgs/pull/157760