Migrating to Projectile 3.0

The single-key "Commander" (projectile-commander and def-projectile-commander-method) is gone. Its replacement is projectile-dispatch, a transient menu bound to s-p m. A prefix argument on project switch (C-u s-p p) also opens it.

If you defined your own commander methods, add them to the dispatch transient instead (see transient-append-suffix and the projectile-dispatch definition).

projectile-enable-idle-timer, projectile-idle-timer-seconds and projectile-idle-timer-hook were removed. If you relied on running something periodically, wire it up yourself:

Removed. For an overview of repositories with uncommitted changes use magit-list-repositories or vc-dir, which do this far better than Projectile ever did.

All of the built-in ctags/etags/gtags glue is gone: projectile-find-tag, projectile-regenerate-tags, projectile-visit-project-tags-table, and the projectile-tags-command / projectile-tags-backend options.

Modern code navigation is better served by xref (M-.) backed by a language server (Eglot/LSP) or etags/ggtags directly, plus projectile-find-references (s-p s x) for textual references.

projectile-completion-system used to accept ido, ivy, helm, default, or auto (which detected ido-mode/ivy-mode/helm-mode). The dedicated ido/ivy/helm/auto values were removed - it now takes default (Emacs’s completing-read) or a custom function.

This isn’t a loss of functionality: Vertico, Consult, fido-mode, Ido’s ido-ubiquitous, and friends all work through completing-read, and helm-projectile / counsel-projectile provide their own dedicated integration. Any of the old values now simply behaves like default, so nothing breaks - you can just delete the setting.

The single-letter lifecycle bindings s-p C / s-p K / s-p L / s-p P / s-p u (configure / package / install / test / run project) were removed. Use the c prefix instead: s-p c o, s-p c p, s-p c i, s-p c t, s-p c r.

Two long-obsolete aliases were also deleted: projectile-global-mode (use projectile-mode) and projectile-project-root-files-functions (use projectile-project-root-functions).

The search commands now share one entry point, projectile-search (s-p s s), backed by a pluggable backend. projectile-search-backend picks the backend (auto by default, favouring ripgrep then grep); you can also register your own with projectile-register-search-backend. See the Searching section for details.

projectile-grep, projectile-ripgrep and projectile-ag still exist as thin wrappers that force a specific backend.

Similarly, projectile-run (s-p x r) is a single command that opens a shell/REPL/terminal in the project root using a backend chosen by projectile-shell-backend (default eshell). The individual commands (projectile-run-eshell, projectile-run-vterm, …​, and their -other-window variants) are unchanged, and you can add your own terminal with projectile-register-shell-backend.

The projectile-dispatch menu gained modifier switches - -d (--display: cycle this window / other window / other frame), -r (--regexp), -n (--new-process) and -i (--invalidate-cache) - which replace the old dedicated "Other window" and "Other frame" menu columns. The projectile-command-map 4 <key> / 5 <key> bindings and the individual -other-window / -other-frame commands are untouched.

projectile-find-references now honours Projectile’s ignore configuration (.projectile and the globally-ignored files/directories) and searches only the project’s file set. It previously went through the semantic-symref API, which scanned the whole tree and ignored that configuration. For semantic (not textual) references, use the built-in xref-find-references - it is also scoped to the Projectile project now.