### Run Documentation Locally

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/contributing.md

Set up and run the documentation site locally. Navigate to the docs directory, install dependencies, and start the development server.

```sh
cd docs && pnpm install && pnpm run dev
```

--------------------------------

### Real-World Example: Module Distribution - Library Author

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/custom-api.mdx

A library author can ship a pre-configured import-tree with domain-specific methods. This example demonstrates defining helper functions and adding them to the import-tree.

```nix
# editor-distro flake module
{ inputs, lib, ... }:
let
  on = self: flag: self.filter (lib.hasInfix "+${flag}");
  off = self: flag: self.filterNot (lib.hasInfix "+${flag}");
  exclusive = self: onFlag: offFlag: (on self onFlag) |> (s: off s offFlag);
in {
  flake.lib.modules-tree = lib.pipe inputs.import-tree [
    (i: i.addPath ./modules)
    (i: i.addAPI { inherit on off exclusive; })
    (i: i.addAPI { ruby = self: self.on "ruby"; })
    (i: i.addAPI { python = self: self.on "python"; })
    (i: i.addAPI { old-school = self: self.off "copilot"; })
    (i: i.addAPI { vim-btw = self: self.exclusive "vim" "emacs"; })
  ];
}
```

--------------------------------

### Real-World Example: Module Distribution - Consumer

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/custom-api.mdx

Consumers can pick exactly the features they want from a distributed import-tree. This example shows how a consumer flake imports and uses specific features.

```nix
# consumer flake module
{ inputs, ... }:
let ed = inputs.editor-distro.lib.modules-tree;
in {
  imports = [ (ed.vim-btw.old-school.on "rust") ];
}
```

--------------------------------

### Directory structure example

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/overview.mdx

A sample directory tree demonstrating how import-tree organizes and discovers Nix modules.

```text
modules/
  networking.nix
  desktop/
    sway.nix
    waybar.nix
  _helpers/
    utils.nix
```

--------------------------------

### Install import-tree via Flake

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/getting-started/quick-start.mdx

Add the repository to your flake inputs.

```nix
{
  inputs.import-tree.url = "github:vic/import-tree";
}
```

--------------------------------

### Install import-tree as a Plain Import (Fetched Tarball)

Source: https://context7.com/vic/import-tree/llms.txt

Import the library from a fetched tarball URL, useful for specific versions or offline use.

```nix
let
  import-tree = import (builtins.fetchTarball {
    url = "https://github.com/vic/import-tree/archive/main.tar.gz";
  });
in
# use import-tree
```

--------------------------------

### Install import-tree without Flakes

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/getting-started/quick-start.mdx

Import via a pinned tarball or a local path.

```nix
let
  import-tree = import (builtins.fetchTarball {
    url = "https://github.com/vic/import-tree/archive/main.tar.gz";
  });
in
# use import-tree
```

```nix
let import-tree = import ./path-to/import-tree;
in
# use import-tree
```

--------------------------------

### Install import-tree as a Plain Import (Local Path)

Source: https://context7.com/vic/import-tree/llms.txt

Import the library directly from a local path in your Nix configuration.

```nix
let import-tree = import ./path-to/import-tree;
in
# use import-tree
```

--------------------------------

### Run Tests with checkmate

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/contributing.md

Execute the project's tests using the checkmate testing framework. Ensure you have Nix installed and configured.

```sh
nix flake check github:vic/checkmate --override-input target path:.
```

--------------------------------

### Install import-tree as a Flake Input

Source: https://context7.com/vic/import-tree/llms.txt

Add import-tree as a dependency in your flake.nix file for easy integration.

```nix
{ inputs.import-tree.url = "github:vic/import-tree"; }
```

--------------------------------

### Example Nix Module

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/dendritic.mdx

A typical Nix module file within the dendritic structure. It defines configuration for a specific service.

```nix
# modules/openssh.nix
{ ... }: {
  services.openssh.enable = true;
  services.openssh.settings.PasswordAuthentication = false;
}
```

--------------------------------

### Import Nix Modules Recursively

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/index.mdx

Import every .nix file under the ./modules directory in your flake.nix. Paths starting with an underscore are ignored by default.

```nix
{ inputs.import-tree.url = "github:vic/import-tree";
  inputs.flake-parts.url = "github:hercules-ci/flake-parts";

  outputs = inputs: inputs.flake-parts.lib.mkFlake { inherit inputs; } 
    (inputs.import-tree ./modules);
}
```

--------------------------------

### Example Dev Shell Module

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/dendritic.mdx

A Nix module defining a default development shell. It specifies packages available within the shell, such as nil and nixfmt.

```nix
# modules/dev-shell.nix
{
  inputs,
  ...
}: {
  perSystem = { pkgs, ... }: {
    devShells.default = pkgs.mkShell {
      packages = [ pkgs.nil pkgs.nixfmt-rfc-style ];
    };
  };
}
```

--------------------------------

### Get file lists with .leafs

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Configure import-tree to return a list of discovered files instead of Nix modules using `.leafs`.

```nix
(import-tree.withLib lib).leafs ./modules
# => [ ./modules/a.nix ./modules/b.nix ]
```

--------------------------------

### Get file lists using .files shorthand

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Use `.files` as a shorthand for `.leafs.result` to obtain a list of discovered files.

```nix
(import-tree.addPath ./modules).withLib lib |>.files
```

--------------------------------

### Read Markdown Files Using .map

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/mapping.mdx

Reads all .md files under a directory and transforms their paths into their content using builtins.readFile. This example shows how .map can transform paths into arbitrary values when used with .leafs.

```nix
# Read all .md files under a directory
lib.pipe import-tree [
  (i: i.initFilter (lib.hasSuffix ".md"))
  (i: i.map builtins.readFile)
  (i: i.withLib lib)
  (i: i.leafs ./docs)
]
# => [ "# Title\n..." "# Other\n..." ]
```

--------------------------------

### Replace default filter with custom logic

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/filtering.mdx

Use `import-tree.initFilter` to completely replace default filtering. This example finds `.nix` files but uses a custom directory ignore convention (`/ignored/`).

```nix
# Find .nix files but use /ignored/ instead of /_
import-tree.initFilter (p: lib.hasSuffix ".nix" p && !lib.hasInfix "/ignored/" p)
```

--------------------------------

### Evaluate import-tree or get a fresh instance with result/new

Source: https://context7.com/vic/import-tree/llms.txt

The `result` attribute evaluates a configured import-tree, useful when paths are already configured. The `new` function returns a fresh import-tree instance with an empty state.

```nix
# result evaluates with empty path list - useful when paths already configured
(import-tree.addPath ./modules).result
# equivalent to:
(import-tree.addPath ./modules) []
```

```nix
# new returns a fresh import-tree with empty state
configured-tree.new  # back to a clean slate
```

--------------------------------

### Initialize Starlight Project

Source: https://github.com/vic/import-tree/blob/main/docs/README.md

Use this command to scaffold a new Starlight project using the Astro CLI.

```bash
pnpm create astro@latest -- --template starlight
```

--------------------------------

### Using Helper Utilities in a Module

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/dendritic.mdx

Demonstrates how to import helper functions from a `_lib` directory within a Nix module. Files in `/_` prefixed directories are ignored by default and must be explicitly imported.

```nix
# modules/feature.nix
let helpers = import ./_lib/helpers.nix;
in { ... }: { /* use helpers */ }
```

--------------------------------

### Import from multiple directories

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/getting-started/quick-start.mdx

Pass a list of directories to import from multiple locations; lists are flattened automatically.

```nix
{ imports = [ (import-tree [ ./modules ./extra-modules ]) ]; }
```

--------------------------------

### Initialize withLib

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/outside-modules.mdx

Required initialization step to provide access to filesystem utilities before reading the tree.

```nix
import-tree.withLib lib
```

--------------------------------

### Using addPath and result

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/examples.mdx

Demonstrates adding paths to an import-tree and accessing the final result.

```nix
let
  tree = import-tree.addPath ./core;
  extended = tree.addPath ./extras;
in
extended.result
```

--------------------------------

### Pre-Configured Tree for Library Subsets

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/examples.mdx

Creates a reusable module tree with predefined subsets (desktop, server, all) using addPath and addAPI.

```nix
let
  my-tree = lib.pipe import-tree [
    (i: i.addPath ./modules)
    (i: i.addAPI {
      desktop = self: self.filter (lib.hasInfix "/desktop/");
      server  = self: self.filter (lib.hasInfix "/server/");
      all     = self: self;
    })
  ];
in {
  # Use the desktop subset
  imports = [ my-tree.desktop ];

  # Or import everything
  # imports = [ my-tree.all ];
}
```

--------------------------------

### Initialize Custom Filters with initFilter

Source: https://context7.com/vic/import-tree/llms.txt

Replace the default discovery filter with custom logic using `.initFilter`. Useful for non-Nix files or different ignore conventions.

```nix
# Find .txt files instead of .nix files
import-tree.initFilter (lib.hasSuffix ".txt") ./dir

# Find .nix files but use /ignored/ instead of /_
import-tree.initFilter (p: lib.hasSuffix ".nix" p && !lib.hasInfix "/ignored/" p) ./modules

# Find and parse JSON config files
lib.pipe import-tree [
  (i: i.initFilter (lib.hasSuffix ".json"))
  (i: i.map builtins.readFile)
  (i: i.map builtins.fromJSON)
  (i: i.withLib lib)
  (i: i.leafs ./config)
]
# => list of parsed JSON objects

```

--------------------------------

### Basic Usage with NixOS/nix-darwin/home-manager

Source: https://context7.com/vic/import-tree/llms.txt

Use import-tree within the `imports` list of NixOS, nix-darwin, or home-manager configurations.

```nix
# configuration.nix
{ import-tree, ... }: { 
  imports = [ (import-tree ./modules) ];
}

# Multiple directories - lists are flattened automatically
{ imports = [ (import-tree [ ./modules ./extra-modules ]) ]; }

# Mix with manual imports
{
  imports = [
    (import-tree ./auto-modules)   # auto-discovered
    ./manual/special-case.nix      # manual import
  ];
}

```

--------------------------------

### Initialize custom filter for .md files

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Replace the default filter with `.initFilter` to include only Markdown files.

```nix
import-tree.initFilter (lib.hasSuffix ".md") ./docs
```

--------------------------------

### Read all markdown files under a directory

Source: https://context7.com/vic/import-tree/llms.txt

This snippet demonstrates how to initialize an import-tree to read all markdown files within a specified directory.

```nix
lib.pipe import-tree [
  (i: i.initFilter (lib.hasSuffix ".md"))
  (i: i.map builtins.readFile)
  (i: i.withLib lib)
  (i: i.leafs ./docs)
]
```

--------------------------------

### Using import-tree as a File Lister

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/outside-modules.mdx

Demonstrates how to use import-tree to obtain a plain list of files instead of module imports.

```APIDOC
## Using import-tree as a File Lister

`import-tree` can be used to get a plain list of files:

```nix
(import-tree.withLib pkgs.lib).leafs ./modules
# => [ /path/to/modules/a.nix /path/to/modules/b.nix ]
```
```

--------------------------------

### Customizing import-tree with API

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/motivation.mdx

Shows how a library can extend import-tree with a custom API, providing pre-configured module sets like 'gaming' and 'minimal' based on filtering logic. Consumers can then use these curated sets in their own configurations.

```nix
# A library could expose:
lib.modules-tree = import-tree.addAPI {
  gaming = self: self.filter (lib.hasInfix "+gaming");
  minimal = self: self.filterNot (lib.hasInfix "+heavy");
};

# Consumers use it like:
{ imports = [ lib.modules-tree.gaming.minimal ]; }
```

--------------------------------

### Retrieve files via shortcut

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/outside-modules.mdx

Returns the list of files directly when paths have been pre-configured using addPath.

```nix
lib.pipe import-tree [
  (i: i.addPath ./modules)
  (i: i.withLib lib)
  (i: i.files)
]
```

--------------------------------

### Simplified Nix Imports with import-tree

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/motivation.mdx

Demonstrates the core functionality of import-tree, where a single call to `import-tree ./modules` automatically discovers and imports all Nix files within the specified directory. This eliminates the need for manual import lists and handles directory reorganizations seamlessly.

```nix
{
  imports = [ (import-tree ./modules) ];
}
```

--------------------------------

### Discover and Process Non-Nix Files

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/examples.mdx

Reads and parses JSON files from a directory, then applies library functions. Requires 'lib' to be available.

```nix
lib.pipe import-tree [
  (i: i.initFilter (lib.hasSuffix ".json"))
  (i: i.map builtins.readFile)
  (i: i.map builtins.fromJSON)
  (i: i.withLib lib)
  (i: i.leafs ./config)
]
# => list of parsed JSON objects
```

--------------------------------

### Use import-tree with NixOS, nix-darwin, or home-manager

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/getting-started/quick-start.mdx

Include the import-tree call within an imports list to recursively discover and import .nix files.

```nix
{ config, ... }: {
  imports = [ (import-tree ./modules) ];
}
```

--------------------------------

### List files with import-tree

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/outside-modules.mdx

Retrieve a flat list of files from a directory without importing them as modules.

```nix
(import-tree.withLib pkgs.lib).leafs ./modules
# => [ /path/to/modules/a.nix /path/to/modules/b.nix ]
```

--------------------------------

### Provide lib for filesystem operations

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Use `.withLib` to provide the Nixpkgs library, enabling functions like `lib.filesystem.listFilesRecursive` for use outside module evaluation.

```nix
import-tree.withLib pkgs.lib
```

--------------------------------

### Importing from Multiple Directories

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/examples.mdx

Imports modules from several directories simultaneously using import-tree.

```nix
import-tree [ ./base-modules ./host-specific ./shared ]
```

--------------------------------

### Discover .txt files instead of .nix

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/filtering.mdx

Replace default filtering by using `import-tree.initFilter` with a predicate that specifies the desired file suffix, like `.txt`.

```nix
# Find .txt files instead of .nix files
import-tree.initFilter (lib.hasSuffix ".txt") ./dir
```

--------------------------------

### Prepend a path for discovery

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Use `.addPath` to prepend a directory to the list of paths to be discovered.

```nix
(import-tree.addPath ./vendor).addPath ./modules
# discovers files in both directories
```

--------------------------------

### flake.nix with import-tree and flake-parts

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/dendritic.mdx

Integrates import-tree with flake-parts to manage Nix configurations organized in a dendritic pattern. Ensure import-tree and flake-parts are added as inputs.

```nix
# flake.nix
{
  inputs.import-tree.url = "github:vic/import-tree";
  inputs.flake-parts.url = "github:hercules-ci/flake-parts";

  outputs = inputs: inputs.flake-parts.lib.mkFlake { inherit inputs; }
    (inputs.import-tree ./modules);
}
```

--------------------------------

### Map paths to import expressions

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Transform each path into an import expression using `.map`.

```nix
import-tree.map import                         # actually import
```

--------------------------------

### Import Nix module directly

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Import the import-tree module directly from a local path.

```nix
let import-tree = import ./path-to/import-tree;

```

--------------------------------

### Compose Multiple Path Transformations

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/mapping.mdx

Demonstrates composing multiple .map operations using lib.pipe. Transformations are applied sequentially from left to right, allowing for complex path manipulation pipelines.

```nix
lib.pipe import-tree [
  (i: i.map import)             # import each .nix file
  (i: i.map builtins.stringLength) # get the length of each result
  (i: i.withLib lib)
  (i: i.leafs ./dir)
]
```

--------------------------------

### NixOS Configuration with import-tree

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/examples.mdx

Includes modules from a directory into a NixOS configuration using import-tree.

```nix
# configuration.nix
{ import-tree, ... }: { 
  imports = [ (import-tree ./modules) ];
}
```

--------------------------------

### initFilter API

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/filtering.mdx

Replaces the default file discovery logic entirely.

```APIDOC
## initFilter

### Description
Replaces the built-in default filter (which includes .nix files and ignores /_ paths) with a custom predicate.

### Parameters
- **predicate** (string -> bool) - Required - The new filter logic to apply to all discovered items.
- **path** (path) - Optional - The directory to scan.
```

--------------------------------

### Path Accumulation

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Explains how to use `.addPath` to prepend directories to the list of paths to be discovered.

```APIDOC
## Path Accumulation

### `.addPath <path>`

Prepend a path to the internal path list. Can be called multiple times:

```nix
(import-tree.addPath ./vendor).addPath ./modules
# discovers files in both directories
```
```

--------------------------------

### Initialize custom filter for Nix files excluding specific subdirectories

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Define a custom filter using `.initFilter` that includes Nix files while excluding those in '/skip/' directories.

```nix
import-tree.initFilter (p: lib.hasSuffix ".nix" p && !lib.hasInfix "/skip/" p)
```

--------------------------------

### Evaluate result

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/outside-modules.mdx

Evaluates the import-tree with pre-configured paths.

```nix
(import-tree.addPath ./modules).result
# equivalent to:
(import-tree.addPath ./modules) []
```

--------------------------------

### Call import-tree with multiple paths

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Provide multiple directory paths to import-tree to discover files from various locations.

```nix
import-tree [ ./modules ./extra ]
```

--------------------------------

### Compose import-tree filters

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/filtering.mdx

Combine multiple filters using `lib.pipe` for a logical AND operation. A file must satisfy all applied filters to be included.

```nix
lib.pipe import-tree [
  (i: i.filter (lib.hasInfix "/desktop/"))
  (i: i.filter (lib.hasSuffix "bar.nix"))
  (i: i ./modules)
]
```

--------------------------------

### Core: Calling import-tree

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Explains the primary usage of the import-tree function, which takes a path or a list of paths and returns a Nix module with discovered files.

```APIDOC
## Core: Calling import-tree

### `import-tree <path | [paths]>`

Takes a path or a (nested) list of paths. Returns a Nix module with `imports` set to all discovered files.

```nix
import-tree ./modules
import-tree [ ./modules ./extra ]
import-tree [ ./a [ ./b ] ]   # nested lists are flattened
```

Other import-tree objects can appear in the list as if they were paths.

<Aside>
When the argument is an attrset with an `options` attribute, import-tree assumes it is being evaluated as a module. This lets a pre-configured import-tree object appear directly in `imports`.
</Aside>

Anything with an `outPath` attribute (like flake inputs) is treated as a path:

```nix
import-tree [ { outPath = ./modules; } ]
```

Non-path values (like attrsets) are passed through the filter and included if they pass.
```

--------------------------------

### Basic Usage with flake-parts

Source: https://context7.com/vic/import-tree/llms.txt

Integrate import-tree with flake-parts to automatically import all modules from a specified directory.

```nix
# flake.nix
{
  inputs.import-tree.url = "github:vic/import-tree";
  inputs.flake-parts.url = "github:hercules-ci/flake-parts";

  outputs = inputs: inputs.flake-parts.lib.mkFlake { inherit inputs; }
    (inputs.import-tree ./modules);
}

# Given this tree:
# modules/
#   networking.nix
#   desktop/
#     sway.nix
#     waybar.nix
#   _helpers/       <-- ignored (underscore prefix)
#     utils.nix
#
# Result: imports networking.nix, desktop/sway.nix, desktop/waybar.nix

```

--------------------------------

### Use import-tree with flake-parts

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/getting-started/quick-start.mdx

Import all modules from a directory as flake-parts modules.

```nix
{
  inputs.import-tree.url = "github:vic/import-tree";
  inputs.flake-parts.url = "github:hercules-ci/flake-parts";

  outputs = inputs: inputs.flake-parts.lib.mkFlake { inherit inputs; }
    (inputs.import-tree ./modules);
}
```

--------------------------------

### Retrieve file list with leafs

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/outside-modules.mdx

Produces a flat list of discovered files from a specified path.

```nix
(import-tree.withLib lib).leafs ./src
# => [ ./src/main.nix ./src/utils.nix ]
```

--------------------------------

### Obtaining import-tree

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Demonstrates how to include the import-tree function in your Nix project, either as a flake input or a local import.

```APIDOC
## Obtaining import-tree

**As a flake input:**
```nix
inputs.import-tree.url = "github:vic/import-tree";
# Then use: inputs.import-tree
```

**As a plain import:**
```nix
let import-tree = import ./path-to/import-tree;
```

The resulting value is a callable attrset — the primary `import-tree` object.
```

--------------------------------

### View Project Structure

Source: https://github.com/vic/import-tree/blob/main/docs/README.md

The standard file layout for a Starlight project, where documentation content resides in src/content/docs/.

```text
.
├── public/
├── src/
│   ├── assets/
│   ├── content/
│   │   └── docs/
│   └── content.config.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json
```

--------------------------------

### Map paths to module structure

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Use `.map` to transform each path into a Nix module structure with an `imports` attribute.

```nix
import-tree.map (p: { imports = [ p ]; })      # wrap in module
```

--------------------------------

### Provide lib for filesystem access with withLib

Source: https://context7.com/vic/import-tree/llms.txt

Use `withLib` to provide `lib` for filesystem access when using import-tree outside module evaluation. `leafs` returns a flat list of discovered files, and `files` is a shortcut for `.leafs.result` when paths are added via `addPath`.

```nix
# withLib provides lib.filesystem.listFilesRecursive
import-tree.withLib pkgs.lib
```

```nix
# leafs returns a flat list of discovered files
(import-tree.withLib lib).leafs ./modules
# => [ /path/to/modules/a.nix /path/to/modules/b.nix ]
```

```nix
# files is shortcut for .leafs.result when paths added via addPath
lib.pipe import-tree [
  (i: i.addPath ./modules)
  (i: i.withLib lib)
  (i: i.files)
]
```

--------------------------------

### Reset import-tree state

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Create a fresh import-tree instance with no paths, filters, or extensions using `.new`.

```nix
configured-tree.new  # back to a clean slate
```

--------------------------------

### import-tree Core API

Source: https://context7.com/vic/import-tree/llms.txt

The primary entry point for discovering and importing Nix modules from a directory or list of directories.

```APIDOC
## import-tree(path)

### Description
Recursively discovers all .nix files in the provided path(s), excluding directories containing /_.

### Parameters
- **path** (string|list) - Required - A single directory path or a list of directory paths to scan.

### Request Example
import-tree ./modules

### Response
- **result** (list) - A list of discovered Nix modules ready for use in an imports list.
```

--------------------------------

### Call import-tree with a single path

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Invoke import-tree with a single directory path to discover and import Nix files.

```nix
import-tree ./modules
```

--------------------------------

### Import modules in non-flake Nix

Source: https://github.com/vic/import-tree/blob/main/README.md

Utilize import-tree in non-flake environments by integrating with with-inputs and npins.

```nix
# default.nix
let
  sources = import ./npins;
  with-inputs = import sources.with-inputs sources {};
  outputs = inputs:
   (inputs.nixpkgs.lib.evalModules {
      specialArgs.inputs = inputs;
      modules = [ (inputs.import-tree ./modules)  ];
   }).config;
in
with-inputs outputs
```

--------------------------------

### Match paths using regex

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Employ the `.match` method with a regular expression to include only paths that fully match the pattern.

```nix
import-tree.match ".*/[a-z]+_[a-z]+\.nix" ./modules
```

--------------------------------

### Import files matching a regex pattern

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/filtering.mdx

Use `import-tree.match` with a regular expression to include files whose full path matches the pattern. Ensure the regex covers the entire path.

```nix
# Only files named like "word_word.nix"
import-tree.match ".*/[a-z]+_[a-z]+\.nix" ./modules
```

--------------------------------

### Regex-Based Module Selection

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/examples.mdx

Uses a regular expression to import only files that match a specific pattern, like 'word_word.nix'.

```nix
# Only files named like: word_word.nix
import-tree.match ".*/[a-z]+_[a-z]+\.nix" ./modules
```

--------------------------------

### Extension

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Details how to extend the import-tree object with custom methods using `.addAPI`.

```APIDOC
## Extension

### `.addAPI <attrset>`

Extend the import-tree object with new methods. Each value is a function receiving `self` (the current import-tree):

```nix
import-tree.addAPI {
  maximal = self: self.addPath ./all-modules;
  feature = self: name: self.filter (lib.hasInfix name);
}
```

Methods are late-bound — you can reference methods added in later `.addAPI` calls.
```

--------------------------------

### Import Nix flake

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Use this method to include import-tree as a flake input in your Nix project.

```nix
inputs.import-tree.url = "github:vic/import-tree";
# Then use: inputs.import-tree
```

--------------------------------

### Import modules with flake-parts

Source: https://github.com/vic/import-tree/blob/main/README.md

Integrate import-tree into a flake-parts configuration to recursively import modules from a directory.

```nix
# flake.nix
{
  inputs.import-tree.url = "github:vic/import-tree";
  inputs.flake-parts.url = "github:hercules-ci/flake-parts";

  outputs = inputs: inputs.flake-parts.lib.mkFlake { inherit inputs; }
   (inputs.import-tree ./modules);
}
```

--------------------------------

### Add multiple directories incrementally with import-tree

Source: https://context7.com/vic/import-tree/llms.txt

Use `addPath` to incrementally add directories to the import-tree for multi-directory discovery. The `result` attribute can be used to access the final discovered files.

```nix
# Add multiple directories incrementally
(import-tree.addPath ./vendor).addPath ./modules
# discovers files in both directories
```

```nix
# Using with addPath and result
let
  tree = import-tree.addPath ./core;
  extended = tree.addPath ./extras;
in
extended.result
```

--------------------------------

### Import Nix files with '.mod.' in name

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/filtering.mdx

Use `import-tree.filter` with a predicate function to include only files that contain a specific substring in their name.

```nix
# Only import files containing ".mod." in their name
import-tree.filter (lib.hasInfix ".mod.") ./modules
```

--------------------------------

### Evaluate with an empty path list

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Use `.result` to evaluate import-tree with an empty list of paths, equivalent to calling it with `[]`.

```nix
(import-tree.addPath ./modules).result
```

--------------------------------

### Pipeline Style Module Import

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/examples.mdx

Applies a series of transformations to the imported modules using a pipeline style, including filtering and tracing values.

```nix
lib.pipe import-tree [
  (i: i.filter (lib.hasInfix "/desktop/"))
  (i: i.map lib.traceVal)
  (i: i ./modules)
]
```

--------------------------------

### Filter Modules by Convention

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/examples.mdx

Selects files within a directory that match a specific naming convention, such as containing '+feature'.

```nix
import-tree.filter (lib.hasInfix "+networking") ./modules
```

--------------------------------

### Traditional Nix Imports

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/motivation.mdx

Illustrates a common problem in Nix configurations where a large, manually managed 'imports' list becomes difficult to maintain as the configuration grows. This approach requires manual updates for every new file or directory reorganization.

```nix
# This doesn't scale.
{
  imports = [
    ./modules/networking.nix
    ./modules/desktop/sway.nix
    ./modules/desktop/waybar.nix
    ./modules/services/docker.nix
    ./modules/services/ssh.nix
    ./modules/users/alice.nix
    # ... dozens more
  ];
}
```

--------------------------------

### Trace Discovered Files for Debugging

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/mapping.mdx

Uses lib.traceVal to print each discovered path during evaluation. This is helpful for debugging import processes and understanding the flow of path discovery.

```nix
import-tree.map lib.traceVal ./modules
```

--------------------------------

### Mixing Auto-Discovered and Manual Imports

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/examples.mdx

Combines modules discovered by import-tree with manually specified Nix files in the 'imports' list.

```nix
{
  imports = [
    (import-tree ./auto-modules)   # auto-discovered
    ./manual/special-case.nix      # manual import
  ];
}
```

--------------------------------

### Mix regex matching and path filtering

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/filtering.mdx

Combine `import-tree.match` with `filter` to apply both regular expression matching and predicate-based filtering. Both conditions must be met.

```nix
(import-tree.match ".*_.*\.nix").filter (lib.hasInfix "/src/") ./tree
```

--------------------------------

### Import modules in a standard flake

Source: https://github.com/vic/import-tree/blob/main/README.md

Use import-tree within a standard Nix flake by passing it to the modules list in evalModules.

```nix
# flake.nix
{
  inputs.import-tree.url = "github:vic/import-tree";
  inputs.nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";

  outputs = inputs:
   (inputs.nixpkgs.lib.evalModules {
      specialArgs.inputs = inputs;
      modules = [ (inputs.import-tree ./modules)  ];
   }).config;
}
```

--------------------------------

### Format Code with checkmate

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/contributing.md

Format the project's code using the checkmate formatting tool. This command ensures code style consistency.

```sh
nix run github:vic/checkmate#fmt
```

--------------------------------

### Map paths to trace values

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Transform each discovered path using `.map` to trace its value during evaluation.

```nix
import-tree.map lib.traceVal ./modules        # trace each path
```

--------------------------------

### Access Extended API Methods

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/custom-api.mdx

After calling .addAPI, the new methods are available directly on the import-tree object for use.

```nix
extended.helloOption.files
extended.feature "networking" ./modules
extended.minimal ./src
```

--------------------------------

### Pipe file list through a function

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Use `.pipeTo` to process the list of discovered files with a given function, such as `builtins.length`.

```nix
(import-tree.withLib lib).pipeTo builtins.length ./modules
# => 3
```

--------------------------------

### Process file list with pipeTo

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/outside-modules.mdx

Passes the discovered file paths to a function for further processing.

```nix
(import-tree.withLib lib).pipeTo builtins.length ./modules
# => 5  (number of .nix files)
```

```nix
lib.pipe import-tree [
  (i: i.map import)
  (i: i.pipeTo lib.length)
  (i: i.withLib lib)
  (i: i ./modules)
]
```

--------------------------------

### pipeTo Function

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/outside-modules.mdx

Explains the `pipeTo` function, which accepts a function that processes the list of discovered paths, enabling powerful pipelines.

```APIDOC
### pipeTo

`.pipeTo` takes a function that receives the list of discovered paths, letting you process the results:

```nix
(import-tree.withLib lib).pipeTo builtins.length ./modules
# => 5  (number of .nix files)
```

Combine with `.map` for powerful pipelines:

```nix
lib.pipe import-tree [
  (i: i.map import)
  (i: i.pipeTo lib.length)
  (i: i.withLib lib)
  (i: i ./modules)
]
```
```

--------------------------------

### Extend import-tree API with new methods

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Add custom methods like `maximal` and `feature` to the import-tree object using `.addAPI`.

```nix
import-tree.addAPI {
  maximal = self: self.addPath ./all-modules;
  feature = self: name: self.filter (lib.hasInfix name);
}
```

--------------------------------

### Cumulative API Extensions

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/custom-api.mdx

Calling .addAPI multiple times is cumulative, preserving previous extensions. This allows for incremental API building.

```nix
let
  first = import-tree.addAPI { foo = self: self.addPath ./foo; };
  second = first.addAPI { bar = self: self.addPath ./bar; };
in
second.foo.files  # still works
```

--------------------------------

### Add Custom API Methods to import-tree

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/custom-api.mdx

Use .addAPI to extend the import-tree object with new named methods. Each method receives the import-tree instance and can call existing methods.

```nix
import-tree.addAPI {
  helloOption = self: self.addPath ./modules/hello-option;
  feature = self: infix: self.filter (lib.hasInfix infix);
  minimal = self: self.feature "minimal";
}
```

--------------------------------

### withLib Function

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/outside-modules.mdx

Explains the necessity and usage of the `withLib` function for outside module evaluation with import-tree.

```APIDOC
### withLib

Outside module evaluation, `import-tree` requires access to `lib` (specifically `lib.filesystem.listFilesRecursive`). You must call `.withLib` before `.leafs` or `.pipeTo`.

```nix
import-tree.withLib lib
```

Omitting `.withLib` when calling `.leafs` will result in an error: `"You need to call withLib before trying to read the tree."`
```

--------------------------------

### Wrap Paths in Custom Modules

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/mapping.mdx

Transforms each discovered path by wrapping it in a custom module structure. This is useful when you need to apply specific import logic to each discovered file.

```nix
import-tree.map (path: { imports = [ path ]; }) ./modules
```

--------------------------------

### Importing attrsets with outPath

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Treats attrsets with an `outPath` attribute as paths, enabling their inclusion in the import process.

```nix
import-tree [ { outPath = ./modules; } ]
```

--------------------------------

### Transform Discovered Paths with map

Source: https://context7.com/vic/import-tree/llms.txt

Use the `.map` function to apply a transformation to each discovered file path after filtering.

```nix
# Trace each discovered path during evaluation (debugging)
import-tree.map lib.traceVal ./modules

# Wrap each path in a custom module structure
import-tree.map (path: { imports = [ path ]; }) ./modules

# Multiple maps compose left-to-right (first map runs first)
lib.pipe import-tree [
  (i: i.map import)                   # import each .nix file
  (i: i.map builtins.stringLength)    # get the length of each result
  (i: i.withLib lib)
  (i: i.leafs ./dir)
]

```

--------------------------------

### Filtering and Matching API

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/filtering.mdx

Methods for narrowing down file discovery using predicates and regex patterns.

```APIDOC
## filter

### Description
Applies a predicate function to each file path to include only files that return true.

### Parameters
- **predicate** (string -> bool) - Required - A function applied to the file path.
- **path** (path) - Required - The directory to scan.

## filterNot

### Description
The inverse of filter; excludes files that match the provided predicate.

### Parameters
- **predicate** (string -> bool) - Required - A function applied to the file path.
- **path** (path) - Required - The directory to scan.

## match

### Description
Filters files based on a regular expression tested against the full path using `builtins.match`.

### Parameters
- **regex** (string) - Required - The regular expression to match against the full path.
- **path** (path) - Required - The directory to scan.

## matchNot

### Description
Excludes files that match the provided regular expression.

### Parameters
- **regex** (string) - Required - The regular expression to exclude.
- **path** (path) - Required - The directory to scan.
```

--------------------------------

### addAPI Method

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/custom-api.mdx

Extends the import-tree object with new named methods. Each method receives the current import-tree instance as 'self'.

```APIDOC
## addAPI

### Description
Extends the import-tree object with new named methods. Each method receives the current import-tree instance (self) and can call any existing method on it.

### Parameters
- **extensions** (Object) - Required - An object where keys are method names and values are functions receiving 'self' and returning the desired logic.

### Request Example
import-tree.addAPI {
  helloOption = self: self.addPath ./modules/hello-option;
  feature = self: infix: self.filter (lib.hasInfix infix);
}
```

--------------------------------

### Count Files in a Directory

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/examples.mdx

Counts the total number of files within a specified directory using import-tree and pipeTo with builtins.length.

```nix
(import-tree.withLib lib).pipeTo builtins.length ./modules
```

--------------------------------

### Filter Discovered Files with Regular Expressions

Source: https://context7.com/vic/import-tree/llms.txt

Use `.match` and `.matchNot` with regular expressions to filter files based on their full path.

```nix
# Only files named like: word_word.nix
import-tree.match ".*/[a-z]+_[a-z]+\.nix" ./modules

# Skip files with numeric names
import-tree.matchNot ".*/[0-9]+\.nix" ./modules

# Mixing filter and match - all filter types compose together
(import-tree.match ".*_.*\.nix").filter (lib.hasInfix "/src/") ./tree
# Finds files matching the regex AND containing /src/ in their path

```

--------------------------------

### Pipe discovered paths through a function with pipeTo

Source: https://context7.com/vic/import-tree/llms.txt

The `pipeTo` function allows processing the list of discovered paths through a given function. It can be combined with `map` for complex pipelines.

```nix
# Count number of .nix files
(import-tree.withLib lib).pipeTo builtins.length ./modules
# => 5
```

```nix
# Combine with map for powerful pipelines
lib.pipe import-tree [
  (i: i.map import)
  (i: i.pipeTo lib.length)
  (i: i.withLib lib)
  (i: i ./modules)
]
```

--------------------------------

### Skip files with 'experimental' in path

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/filtering.mdx

Use `import-tree.filterNot` to exclude files that match a given predicate, such as having a specific substring in their path.

```nix
# Skip any file with "experimental" in the path
import-tree.filterNot (lib.hasInfix "experimental") ./modules
```

--------------------------------

### Call import-tree with nested paths

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Import-tree flattens nested lists of paths, allowing for structured path definitions.

```nix
import-tree [ ./a [ ./b ] ]   # nested lists are flattened
```

--------------------------------

### Transformation

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Describes the `.map` function for transforming each discovered path before it's included.

```APIDOC
## Transformation

### `.map <fn>`

`fn : path -> a` — transform each discovered path.

```nix
import-tree.map lib.traceVal ./modules        # trace each path
import-tree.map (p: { imports = [ p ]; })      # wrap in module
import-tree.map import                         # actually import
```

Multiple `.map` calls compose (first map runs first).
```

--------------------------------

### Output

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Covers methods for obtaining the final result, such as file lists or evaluated values.

```APIDOC
## Output

### `.withLib <lib>`

Required before `.leafs` or `.pipeTo` when used outside module evaluation. Provides `lib.filesystem.listFilesRecursive`.

```nix
import-tree.withLib pkgs.lib
```

### `.leafs`

Returns a configured import-tree that produces file lists instead of modules:

```nix
(import-tree.withLib lib).leafs ./modules
# => [ ./modules/a.nix ./modules/b.nix ]
```

### `.files`

Shorthand for `.leafs.result`:

```nix
(import-tree.addPath ./modules).withLib lib |>.files
```

### `.pipeTo <fn>`

Like `.leafs` but pipes the result list through `fn`:

```nix
(import-tree.withLib lib).pipeTo builtins.length ./modules
# => 3
```

### `.result`

Evaluate with an empty path list. Equivalent to calling with `[]`:

```nix
(import-tree.addPath ./modules).result
```

### `.new`

Returns a fresh import-tree with empty state — no paths, filters, maps, or API extensions.

```nix
configured-tree.new  # back to a clean slate
```
```

--------------------------------

### result Function

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/outside-modules.mdx

Details the `result` function, which evaluates the import-tree with an empty path list, useful when paths are pre-configured via `.addPath`.

```APIDOC
### result

`.result` evaluates the import-tree with an empty path list — useful when paths are already configured via `.addPath`:

```nix
(import-tree.addPath ./modules).result
# equivalent to:
(import-tree.addPath ./modules) []
```
```

--------------------------------

### Filter Discovered Files by Name

Source: https://context7.com/vic/import-tree/llms.txt

Use `.filter` with a predicate function to include only files whose paths match specific criteria.

```nix
# Only import files containing ".mod." in their name
import-tree.filter (lib.hasInfix ".mod.") ./modules

# Skip any file with "experimental" in the path
import-tree.filterNot (lib.hasInfix "experimental") ./modules

# Multiple filters combine with AND - file must pass all filters
lib.pipe import-tree [
  (i: i.filter (lib.hasInfix "/desktop/"))
  (i: i.filter (lib.hasSuffix "bar.nix"))
  (i: i ./modules)
]
# Selects only files under desktop/ directory whose name ends in bar.nix

# Filter by convention - only import files tagged with +feature
import-tree.filter (lib.hasInfix "+networking") ./modules

```

--------------------------------

### files Function

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/outside-modules.mdx

Describes the `files` function as a shortcut for `.leafs.result`, returning the list directly when paths have already been added via `.addPath`.

```APIDOC
### files

`.files` is a shortcut for `.leafs.result` — returns the list directly when paths have already been added via `.addPath`:

```nix
lib.pipe import-tree [
  (i: i.addPath ./modules)
  (i: i.withLib lib)
  (i: i.files)
]
```
```

--------------------------------

### Filtering

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Details various filtering methods to customize which files are included in the import process.

```APIDOC
## Filtering

### `.filter <fn>`

`fn : string -> bool` — only include paths where `fn` returns `true`.

```nix
import-tree.filter (lib.hasInfix ".mod.") ./modules
```

Multiple `.filter` calls compose with AND.

### `.filterNot <fn>`

Inverse of `.filter` — exclude paths where `fn` returns `true`.

```nix
import-tree.filterNot (lib.hasInfix "experimental") ./modules
```

### `.match <regex>`

Include only paths matching the regex. Uses `builtins.match` (tests full string).

```nix
import-tree.match ".*/[a-z]+_[a-z]+\.nix" ./modules
```

Multiple `.match` calls compose with AND.

### `.matchNot <regex>`

Exclude paths matching the regex.

```nix
import-tree.matchNot ".*/test_.*\.nix" ./modules
```

### `.initFilter <fn>`

**Replaces** the default filter (`.nix` suffix, no `/_` infix). Use for non-Nix files or custom ignore conventions.

```nix
import-tree.initFilter (lib.hasSuffix ".md") ./docs
import-tree.initFilter (p: lib.hasSuffix ".nix" p && !lib.hasInfix "/skip/" p)
```

Also applies to non-path items in import lists.
```

--------------------------------

### Filter paths by suffix

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Use the `.filter` method with a function to include only paths that satisfy a specific condition, such as having a '.mod.' suffix.

```nix
import-tree.filter (lib.hasInfix ".mod.") ./modules
```

--------------------------------

### Skip files with numeric names using regex

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/filtering.mdx

Use `import-tree.matchNot` with a regular expression to exclude files whose full path matches the pattern, such as those with numeric names.

```nix
# Skip files with numeric names
import-tree.matchNot ".*/[0-9]+\.nix" ./modules
```

--------------------------------

### leafs Function

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/outside-modules.mdx

Details the `leafs` function, which returns a configured import-tree that produces a flat list of discovered files when given a path.

```APIDOC
### leafs

`.leafs` returns a configured import-tree that, when given a path, produces a flat list of discovered files:

```nix
(import-tree.withLib lib).leafs ./src
# => [ ./src/main.nix ./src/utils.nix ]
```
```

--------------------------------

### Filtering and Matching API

Source: https://context7.com/vic/import-tree/llms.txt

Methods for refining the set of discovered files using predicates or regular expressions.

```APIDOC
## .filter(predicate) / .filterNot(predicate)

### Description
Filters discovered files based on a predicate function that takes a path string and returns a boolean.

## .match(regex) / .matchNot(regex)

### Description
Filters discovered files using regular expressions tested against the full path.

## .initFilter(predicate)

### Description
Replaces the default filter (which defaults to .nix suffix and ignoring /_ paths) with a custom predicate.
```

--------------------------------

### Transformation API

Source: https://context7.com/vic/import-tree/llms.txt

Methods for transforming discovered paths or their contents.

```APIDOC
## .map(function)

### Description
Applies a transformation function to each discovered path after filtering.

### Parameters
- **function** (function) - Required - A function that takes a path and returns a transformed value.
```

--------------------------------

### Exclude paths using regex

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Use `.matchNot` to exclude paths that match a specified regular expression.

```nix
import-tree.matchNot ".*/test_.*\.nix" ./modules
```

--------------------------------

### Late Binding of API Methods

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/guides/custom-api.mdx

API methods are late-bound, meaning they can reference methods that don't exist yet and resolve when called. This enables incremental API development across multiple .addAPI calls.

```nix
let
  first = import-tree.addAPI { result = self: self.late; };
  extended = first.addAPI { late = _self: "hello"; };
in
extended.result  # => "hello"
```

--------------------------------

### Filter out paths by suffix

Source: https://github.com/vic/import-tree/blob/main/docs/src/content/docs/reference/api.mdx

Use `.filterNot` to exclude paths that match a given condition, like containing the string 'experimental'.

```nix
import-tree.filterNot (lib.hasInfix "experimental") ./modules
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.