diff --git a/README.md b/README.md index 5aa43bc..b01deb0 100644 --- a/README.md +++ b/README.md @@ -14,20 +14,61 @@ The established standard Nix formatting differs considerably from the original o For more details, see the [RFC implementation tracking issue](https://github.com/NixOS/nixfmt/issues/153). -## Installation +## Installation And Usage Instructions -- `nixfmt` is in nixpkgs master as of 2019-09-04: +### nixpkgs/NixOS - nix-env -iA nixpkgs.nixfmt +`nixfmt` was used as the basis for the official Nix formatter with a standardized formatting. +The new formatting differs considerably from the original one. +This is why two packages are in nixpkgs: `nixfmt-classic` with the non-standardized formatting and `nixfmt-rfc-style`. -- To get the most recent version, install from master: +So installing this `nixfmt` is as simple as adding to the system packages: - nix-env -f https://github.com/NixOS/nixfmt/archive/master.tar.gz -i +```nix +{ pkgs, ... }: -- Nix with flakes +{ + environment.systemPackages = [ pkgs.nixfmt-rfc-style ]; +} +``` - nix profile install github:NixOS/nixfmt +### From the repository +It's also possible to install `nixfmt` directly from the repository using `nix-env`. +This allows the newest changes to be used, which may not be equal to the `nixfmt` version used to format nixpkgs, so this should be done with care! +Also, updates are not done automatically (as with the system packages). + +``` +nix-env -f https://github.com/NixOS/nixfmt/archive/master.tar.gz -i +``` + +### treefmt + +[treefmt](https://github.com/numtide/treefmt) can be used to format repositories consisting of different languages with one command. +A possible configuration for `nixfmt` in `.treefmt.toml` looks like this: +```toml +[formatter.nixfmt-rfc-style] +command = "nixfmt" +includes = ["*.nix"] +``` + +This only works when `nixfmt-rfc-style` is installed (see above for installation instructions). + +`treefmt` can be integrated into text editors and CI to ensure consistent formatting for all filetypes. + +### treefmt-nix + +[treefmt-nix](https://github.com/numtide/treefmt-nix) automatically configures the correct packages and formatters using a Nix configuration and has native support for `nixfmt`: + +```nix +# ... +treefmt-nix.mkWrapper nixpkgs { + # ... other options ... + programs.nixfmt-rfc-style.enable = true; +} +``` + +More information about configuration can be found in [the official README](https://github.com/numtide/treefmt-nix?tab=readme-ov-file#integration-into-nix). ## Development ### With Nix