From f080f29292817e5be2caac4e9e0c0e2def36b07e Mon Sep 17 00:00:00 2001
From: Robert Helgesson <robert@rycee.net>
Date: Sun, 22 Mar 2020 13:13:09 +0100
Subject: [PATCH] faq: outline how to override packages

Fixes #1107
---
 FAQ.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/FAQ.md b/FAQ.md
index a83a90f6..eebbad81 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -149,3 +149,50 @@ in
 should work provided you have a Nix channel called `nixpkgs-unstable`.
 Note, the package will not be affected by any package overrides,
 overlays, etc.
+
+How do I override the package used by a module?
+-----------------------------------------------
+
+By default Home Manager will install the package provided by your
+chosen `nixpkgs` channel but occasionally you might end up needing to
+change this package. This can typically be done in two ways.
+
+1. If the module provides a `package` option, such as
+   `programs.beets.package`, then this is the recommended way to
+   perform the override. For example,
+
+   ```
+   programs.beets.package = pkgs.beets.override { enableCheck = true; };
+   ```
+
+2. If no `package` option is available, then you can typically
+   override the relevant package using an [overlay][nixpkgs-overlays].
+
+   For example, if you want to use the `programs.skim` module but use
+   the `skim` package from Nixpkgs unstable, then a configuration like
+
+   ```nix
+   { pkgs, config, ... }:
+
+   let
+
+     pkgsUnstable = import <nixpkgs-unstable> {};
+
+   in
+
+   {
+     programs.skim.enable = true;
+
+     nixpkgs.overlays = [
+       (self: super: {
+         skim = pkgsUnstable.skim;
+       })
+     ];
+
+     # …
+   }
+   ```
+
+   should work OK.
+
+[nixpkgs-overlays]: https://nixos.org/nixpkgs/manual/#chap-overlays