From 13f0af428ebce3411faa1eac184c3032ef423239 Mon Sep 17 00:00:00 2001
From: Silvan Mosberger <silvan.mosberger@tweag.io>
Date: Sun, 19 Nov 2023 00:57:21 +0100
Subject: [PATCH] lib.fileset: Add overview section to reference docs

---
 lib/fileset/default.nix | 46 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 44 insertions(+), 2 deletions(-)

diff --git a/lib/fileset/default.nix b/lib/fileset/default.nix
index ca2ab9a35740..7d7bf86ab8a5 100644
--- a/lib/fileset/default.nix
+++ b/lib/fileset/default.nix
@@ -3,10 +3,52 @@
   []{#sec-fileset}
 
   The [`lib.fileset`](#sec-functions-library-fileset) library allows you to work with _file sets_.
-  A file set is a mathematical set of local files that can be added to the Nix store for use in Nix derivations.
+  A file set is a (mathematical) set of local files that can be added to the Nix store for use in Nix derivations.
   File sets are easy and safe to use, providing obvious and composable semantics with good error messages to prevent mistakes.
 
-  See the [function reference](#sec-functions-library-fileset) for function-specific documentation.
+  ## Overview {#sec-fileset-overview}
+
+  Basics:
+  - [Implicit coercion from paths to file sets](#sec-fileset-path-coercion)
+
+  - [`lib.fileset.trace`](#function-library-lib.fileset.trace)/[`lib.fileset.traceVal`](#function-library-lib.fileset.trace):
+
+    Pretty-print file sets for debugging.
+
+  - [`lib.fileset.toSource`](#function-library-lib.fileset.toSource):
+
+    Add files in file sets to the store to use as derivation sources.
+
+  Combinators:
+  - [`lib.fileset.union`](#function-library-lib.fileset.union)/[`lib.fileset.unions`](#function-library-lib.fileset.unions):
+
+    Create a larger file set from all the files in multiple file sets.
+
+  - [`lib.fileset.intersection`](#function-library-lib.fileset.intersection):
+
+    Create a smaller file set from only the files in both file sets.
+
+  - [`lib.fileset.difference`](#function-library-lib.fileset.difference):
+
+    Create a smaller file set containing all files that are in one file set, but not another one.
+
+  Filtering:
+  - [`lib.fileset.fileFilter`](#function-library-lib.fileset.fileFilter):
+
+    Create a file set from all files that satisisfy a predicate in a directory.
+
+  Utilities:
+  - [`lib.fileset.fromSource`](#function-library-lib.fileset.fromSource):
+
+    Create a file set from a `lib.sources`-based value.
+
+  - [`lib.fileset.gitTracked`](#function-library-lib.fileset.gitTracked)/[`lib.fileset.gitTrackedWith`](#function-library-lib.fileset.gitTrackedWith):
+
+    Create a file set from all tracked files in a local Git repository.
+
+  If you need more file set functions,
+  see [this issue](https://github.com/NixOS/nixpkgs/issues/266356) to request it.
+
 
   ## Implicit coercion from paths to file sets {#sec-fileset-path-coercion}