From 3a645b28dbf835e05feed8e662449ee0c6ef6432 Mon Sep 17 00:00:00 2001
From: Bozhidar Batsov <bozhidar@toptal.com>
Date: Sun, 26 Apr 2026 11:17:33 +0100
Subject: Document hybrid indexing and add a per-method feature matrix

The configuration page covered alien indexing in depth but mentioned
hybrid only in passing, so users had to read the source to learn that
hybrid is "alien with Projectile's filtering rules layered on top".
Add a dedicated section explaining what hybrid does and when to reach
for it, and a comparison table summarising which knobs (dirconfig,
global ignores/unignores, sort order, default caching, Windows
support) apply under each indexing method.
---
 CHANGELOG.md                              |  1 +
 doc/modules/ROOT/pages/configuration.adoc | 74 +++++++++++++++++++++++++++++++
 2 files changed, 75 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8a7f0ce..eca17ad 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 ### Changes
 
+* Document the `hybrid` indexing method in the manual and add a feature matrix showing which Projectile knobs (dirconfig, global ignores/unignores, sort order, default caching) apply under `native`/`hybrid`/`alien`.
 * `projectile-dir-files-alien` now accepts an optional `vcs` argument so the dispatcher can thread through the already-resolved VCS instead of recomputing it. Existing single-argument callers are unaffected.
 * `projectile-index-directory` (native indexing) now relies on `directory-files-no-dot-files-regexp` to filter out `.` and `..` at the C level instead of walking past them in Elisp.
 * `projectile-project-root-cache` now keys entries on cons cells (`(FUNC . DIR)` for per-function results, `('none . DIR)` for the overall failure marker) instead of formatted strings. This is internal state, but third-party code that reaches into the cache directly will need to update.
diff --git a/doc/modules/ROOT/pages/configuration.adoc b/doc/modules/ROOT/pages/configuration.adoc
index 4427bd2..1492633 100644
--- a/doc/modules/ROOT/pages/configuration.adoc
+++ b/doc/modules/ROOT/pages/configuration.adoc
@@ -146,6 +146,80 @@ You can also customize the path to the `fd` executable and the arguments passed
 (setq projectile-git-fd-args "-H -0 -E .git -tf --strip-cwd-prefix -c never")
 ----
 
+=== Hybrid indexing
+
+The `hybrid` method runs the same external command as `alien` and then
+post-processes the result with Projectile's filtering rules.  In other
+words, it's `alien` plus a second pass that applies:
+
+* `.projectile` (dirconfig) ignore/keep/ensure entries
+* `projectile-globally-ignored-files`,
+  `projectile-globally-ignored-directories`,
+  `projectile-globally-ignored-file-suffixes`, and
+  `projectile-global-ignore-file-patterns`
+* `projectile-globally-unignored-files` and
+  `projectile-globally-unignored-directories`
+* The configured sort order from `projectile-sort-order`
+
+This is the right choice when your VCS lists more files than you want
+Projectile to surface (e.g. you want to drop `*.elc` even though they're
+checked in), or when you rely on `.projectile` to keep/ignore subtrees
+inside an otherwise large repository.  It's slower than `alien` because
+of the extra pass, but it remains substantially faster than `native` for
+big projects since the file list itself is still produced by the
+external tool.
+
+=== Indexing method comparison
+
+Not all Projectile features apply to every indexing method.  The table
+below summarises which configuration knobs take effect under which mode:
+
+[cols="3,1,1,1", options="header"]
+|===
+| Feature | `native` | `hybrid` | `alien`
+
+| Project file listing speed
+| Slow (Elisp)
+| Fast
+| Fastest
+
+| Honors `.projectile` (dirconfig) `+`/`-`/`!` rules
+| Yes
+| Yes
+| No
+
+| Honors `projectile-globally-ignored-files` / `-directories` / `-file-suffixes` / `projectile-global-ignore-file-patterns`
+| Yes
+| Yes
+| No (rely on the VCS / `fd` / `find` ignores instead)
+
+| Honors `projectile-globally-unignored-*`
+| Yes
+| Yes
+| No
+
+| Sorts via `projectile-sort-order`
+| Yes
+| Yes
+| No (returned in the external tool's order)
+
+| File caching enabled by default
+| Yes
+| No
+| No
+
+| Works on Windows out of the box
+| Yes
+| Requires Unix utilities
+| Requires Unix utilities
+|===
+
+NOTE: When `alien` is in use and a non-empty `.projectile` file is
+present, Projectile emits a one-time warning so the silent bypass
+doesn't catch you off guard.  Switch to `hybrid` (or `native`) if you
+need those rules applied; set
+`projectile-warn-when-dirconfig-is-ignored` to nil to silence.
+
 == Sorting
 
 You can choose how Projectile sorts files by customizing `projectile-sort-order`.
-- 
cgit v1.0