From b65233d5f9736cf8d8fe9d4652e1faf610b574bc Mon Sep 17 00:00:00 2001 From: saygo-png Date: Fri, 5 Dec 2025 17:25:09 +0100 Subject: [PATCH] docs: discourage use of `follows` Signed-off-by: saygo-png --- docs/user-guide/faq.md | 10 +++------- docs/user-guide/install.md | 5 +++-- 2 files changed, 6 insertions(+), 9 deletions(-) diff --git a/docs/user-guide/faq.md b/docs/user-guide/faq.md index d2625876..22761adb 100644 --- a/docs/user-guide/faq.md +++ b/docs/user-guide/faq.md @@ -83,18 +83,14 @@ When using Nixvim, it is possible to encounter errors about something not being error: cannot be found in pkgs ``` -This usually means one of two things: +This usually means one of few things: +- You are using `follows` on `inputs.nixvim` causing Nixvim to have an unexpected version of Nixpkgs. - The nixpkgs version is not in line with Nixvim (for example nixpkgs nixos-25.11 is used with Nixvim master) - The nixpkgs unstable version used with Nixvim is not recent enough. -When building Nixvim using flakes and our ["standalone mode"][standalone], we usually recommend _not_ declaring a "follows" for `inputs.nixvim`. +When building Nixvim using flakes, we usually recommend _not_ declaring a `follows` for `inputs.nixvim`. This is so that Nixvim is built against the same nixpkgs revision we're using in our test suite. -If you are building Nixvim using the NixOS, Home Manager, or nix-darwin modules then we advise that you keep your nixpkgs lock as close as possible to ours. - -> [!TIP] -> Once [#1784](https://github.com/nix-community/nixvim/issues/1784) is implemented, there will be alternative ways to achieve this using the module system. - [standalone]: ../platforms/standalone.md ## How do I create multiple aliases for a single keymap diff --git a/docs/user-guide/install.md b/docs/user-guide/install.md index 0ca29870..a9c12f4c 100644 --- a/docs/user-guide/install.md +++ b/docs/user-guide/install.md @@ -35,13 +35,15 @@ When using flakes you can simply add `nixvim` to the inputs: inputs.nixvim = { url = "github:nix-community/nixvim"; # If using a stable channel you can use `url = "github:nix-community/nixvim/nixos-"` - inputs.nixpkgs.follows = "nixpkgs"; }; # outputs... } ``` +We recommend against using `inputs.nixpkgs.follows = "nixpkgs";` on the `nixvim` input as we test Nixvim against our Nixpkgs revision. +When you use `follows` you opt out of guarantees provided by these tests. +If you choose to use it anyway, removing `follows` should be one of the first debugging steps when encountering issues. ## Usage @@ -51,7 +53,6 @@ When used standalone, a custom Nixvim derivation is produced that can be used li When used as a module, Nixvim can be enabled though `programs.nixvim.enable`. - ### Usage as a module (NixOS, Home Manager, nix-darwin) When using Nixvim as a module you must import the Nixvim module into your module system.