### Install Projectile with use-package (Master Branch)

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/installation.adoc

Configure Projectile installation using use-package, ensuring it installs from the master branch. This setup also defines keybindings for Projectile.

```elisp
(use-package projectile
  :ensure t
  :init
  (projectile-mode +1)
  :bind (:map projectile-mode-map
              ("s-p" . projectile-command-map)
              ("C-c p" . projectile-command-map)))
```

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

### Install Projectile with use-package (Stable Releases)

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/installation.adoc

Configure Projectile installation using use-package, pinning it to stable releases. This setup also defines keybindings for Projectile.

```elisp
(use-package projectile
  :ensure t
  :pin melpa-stable
  :init
  (projectile-mode +1)
  :bind (:map projectile-mode-map
              ("s-p" . projectile-command-map)
              ("C-c p" . projectile-command-map)))
```

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

### Install Projectile with package.el

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/installation.adoc

Use this command to install Projectile via the package.el package manager. Ensure your package list is refreshed if installation fails.

```elisp
(unless (package-installed-p 'projectile)
  (package-install 'projectile))
```

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

### Run with Idle Timer Example

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/migrating_to_projectile_3.adoc

If you relied on running something periodically, wire it up yourself using `run-with-idle-timer`.

```elisp
(run-with-idle-timer 60 t (lambda () (when (projectile-project-p) ;; ... )))
```

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

### Enable Projectile Global Mode and Bind Prefix Key

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/migrating_from_project_el.adoc

Install Projectile from MELPA, enable its global mode, and define a keybinding for the Projectile command map. This is the basic setup to start using Projectile.

```emacs-lisp
(require 'projectile)
(projectile-mode +1)
(define-key projectile-mode-map (kbd "C-c p") 'projectile-command-map)
```

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

### Install Antora Documentation Generator

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/contributing.adoc

Install the Antora documentation generator using npm. This command should be run from the 'docs.projectile.mx' directory.

```sh
$ cd docs.projectile.mx
$ npm install
```

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

### Define Projectile Command Prefix

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/usage.adoc

This example shows how to add a new command prefix for Projectile commands, using 's-,' as an example. This allows for custom keybindings to trigger Projectile actions.

```elisp
(define-key projectile-mode-map (kbd "s-,") 'projectile-command-map)
```

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

### Run Projectile Tests with Package Installation

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/contributing.adoc

Run all tests with Projectile installed as an Emacs package. This simulates a real-world installation without affecting your current Emacs setup.

```sh
$ eldev -p test
```

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

### Configure Projectile Shell Backend

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Set the default shell backend for `projectile-run`. The default is 'eshell', but this example changes it to 'vterm'.

```elisp
(setq projectile-shell-backend 'vterm)
```

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

### Register Custom Shell Backend

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Register a new shell backend using `projectile-register-shell-backend`. This example shows how to integrate 'mistty'. Ensure 'mistty' is available.

```elisp
(projectile-register-shell-backend 'mistty
  :description "mistty"
  :available (lambda () (require 'mistty nil t))
  :run (lambda (_new-process _other-window)
         (let ((default-directory (projectile-acquire-root)))
           (mistty))))
```

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

### Minimal Asynchronous File Finder Integration

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

A basic example of integrating a custom file finder using Projectile's asynchronous command runner. This function indexes the project and then prompts the user to select a file.

```elisp
(defun my/project-find-file ()
  "Pick a file from the current project, indexing without blocking."
  (interactive)
  (let* ((producer (projectile-project-files-producer))
         (default-directory (plist-get producer :directory)))
    (projectile-files-via-ext-command-async
     default-directory (plist-get producer :command)
     (lambda (files _err)
       (find-file (expand-file-name (completing-read "File: " files)
                                    default-directory))))))
```

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

### Register Custom Search Backend

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Register a new search backend using `projectile-register-search-backend`. This example shows how to integrate 'deadgrep'. Ensure 'deadgrep' is available.

```elisp
(projectile-register-search-backend 'deadgrep
  :description "deadgrep"
  :available (lambda () (require 'deadgrep nil t))
  :search (lambda (term _regexp)
            (deadgrep term (projectile-acquire-root))))

(setq projectile-search-backend 'deadgrep)
```

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

### Bind Super Key for Projectile Commands

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/usage.adoc

This example demonstrates binding the 'Super' key (often mapped to Command or Windows key) to common Projectile commands for quick access. Note that these bindings may not work on Windows due to system key usage.

```elisp
(define-key projectile-mode-map [?\s-d] 'projectile-find-dir)
```

```elisp
(define-key projectile-mode-map [?\s-p] 'projectile-switch-project)
```

```elisp
(define-key projectile-mode-map [?\s-f] 'projectile-find-file)
```

```elisp
(define-key projectile-mode-map [?\s-g] 'projectile-grep)
```

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

### Get Project Files Producer Information

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Retrieve information needed to run Projectile's indexing command asynchronously. This includes the directory, VCS type, command, and output separator.

```elisp
(projectile-project-files-producer)
;; => (:directory "/path/to/project/"
;;     :vcs git
;;     :command "git ls-files -zco --exclude-standard"
;;     :separator "\0")
```

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

### Hook for Asynchronous Project Indexing

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Automatically trigger an asynchronous project index after switching to a new project. This ensures the cache is warm when you start working in a new project.

```elisp
(add-hook 'projectile-after-switch-project-hook
          #'projectile-index-project-async)
```

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

### Override Projectile Get External Command

Source: https://github.com/bbatsov/projectile/wiki/Windows-and-Projectile

Override the `projectile-get-ext-command` function to use the 'Everything' search command-line tool (`es.exe`). This significantly speeds up file searches by leveraging the external tool's efficient indexing. Ensure `<PATHTOEVERYTHINGSEARCH>` is replaced with the actual path to your 'Everything' installation.

```emacs-lisp
(defun projectile-get-ext-command() "" 
         (concat "<PATHTOEVERYTHINGSEARCH>\es.exe -r " 
            (concat (replace-regexp-in-string "/" "\\\\" default-directory t t) 
            ".+[^\\\\]\\.[^\\\\]+$" | tr '\n' '\0'"))
         )
```

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

### Update Existing Project Type Configuration

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Modify specific options of an existing project type, such as 'sbt'. This example updates the related files function, removes the test prefix, and sets a higher precedence for the 'sbt' project type.

```elisp
(projectile-update-project-type
 'sbt
 :related-files-fn
 (list
  (projectile-related-files-fn-test-with-suffix "scala" "Spec")
  (projectile-related-files-fn-test-with-suffix "scala" "Test"))
 :test-prefix nil
 :precedence 'high)
```

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

### Add Projectile Hooks

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Integrate custom functions into Projectile's workflow by adding hooks. Examples include hooks for finding files, finding directories, and switching projects.

```elisp
;; Run after a file is opened via projectile-find-file
(add-hook 'projectile-find-file-hook #'my-find-file-setup)

;; Run after a directory is opened via projectile-find-dir
(add-hook 'projectile-find-dir-hook #'my-find-dir-setup)

;; Run right before switching projects
(add-hook 'projectile-before-switch-project-hook #'my-before-switch-setup)
```

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

### Define Custom Projectile Kill Buffer Conditions

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Use a composable condition DSL to specify which buffers should be killed. This example kills file-visiting and dired buffers, leaving others untouched.

```elisp
;; Kill file-visiting buffers and dired buffers, but leave everything else alone
(setq projectile-kill-buffers-filter
      '(buffer-file-name (derived-mode . dired-mode)))
```

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

### Customize fd Executable Path

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Specify a custom path for the `fd` executable if it's not in the system's default PATH. This ensures Projectile can find and use your desired `fd` installation.

```elisp
(setq projectile-fd-executable "/usr/local/bin/fd")
```

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

### Set Projectile Switch Project Action to projectile-find-dir

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Configures Projectile to allow selecting a subdirectory within the project to open in a dired buffer. This provides a more targeted way to start working within a specific part of the project.

```elisp
(setq projectile-switch-project-action #'projectile-find-dir)
```

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

### Customize Project Name Function

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Define a custom function for `projectile-project-name-function` to determine the project name displayed in the mode line and buffer names. This example uses the directory name.

```elisp
(setq projectile-project-name-function
      (lambda (project-root)
        (file-name-nondirectory
         (directory-file-name project-root))))
```

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

### Set Custom Project Lifecycle Command

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Override the default project lifecycle commands (configure, compile, test, etc.) by setting the corresponding variable to a string for an external command or an Emacs Lisp function. This example sets a custom test command.

```elisp
(setq projectile-test-cmd #'custom-test-function)
```

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

### Build Projectile Documentation Site Locally

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/contributing.adoc

Build the documentation site locally from the 'docs.projectile.mx' repository. This allows you to preview changes before deploying.

```sh
$ cd docs.projectile.mx
$ make build
```

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

### Deploy Projectile Documentation Site

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/contributing.adoc

Deploy the built documentation site to the live server. This command requires commit access to the repository.

```sh
$ make deploy
```

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

### Configure Generic Project File Listing Command

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Defines the command used for non-VCS projects. Defaults to 'fd' if available, otherwise falls back to 'find'.

```shell
;; Effective default value of projectile-generic-command, picked at load time:
;;   when fd is on PATH:
"fd . -0 --type f --color=never --strip-cwd-prefix"
;;   otherwise:
"find . -type f | cut -c3- | tr '\n' '\0'"
```

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

### Per-Project Directory Includes

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Specify directories to keep, ignoring everything else. Only subdirectories can be included, not file patterns.

```projectile
+/src/foo
+/tests/foo
```

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

### Set Remote File Existence Cache Expiration

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Configure the time-to-live (TTL) for cached remote file existence results. This example sets the expiration to 10 minutes.

```elisp
(setq projectile-file-exists-remote-cache-expire (* 10 60))
```

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

### Delegate Project Detection to project.el

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Leverage Emacs's built-in `project.el` for project root detection. A wrapper function is needed to align with Projectile's API.

```elisp
;; we need this wrapper to match Projectile's API
(defun projectile-project-current (dir)
  "Retrieve the root directory of the project at DIR using `project-current'."
  (cdr (project-current nil dir)))

(setq projectile-project-root-functions '(projectile-project-current))
```

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

### Enable Projectile Mode and Configure Keymaps

Source: https://github.com/bbatsov/projectile/blob/master/README.md

Enable projectile-mode and set custom keymap prefixes for projectile commands. Recommended prefixes are provided for macOS and Windows/Linux.

```elisp
(projectile-mode +1)
;; Recommended keymap prefix on macOS
(define-key projectile-mode-map (kbd "s-p") 'projectile-command-map)
;; Recommended keymap prefix on Windows/Linux
(define-key projectile-mode-map (kbd "C-c p") 'projectile-command-map)
```

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

### Enable Git Grep for Faster Searching

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Use `vc-git-grep` for searching in Git projects to leverage `.gitignore` and improve performance.

```elisp
(setq projectile-use-git-grep t)
```

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

### Configure Projectile Keymaps

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/installation.adoc

Add these lines to your Emacs configuration to set up Projectile keybindings. The suggested prefixes are 's-p' on macOS and 'C-c p' on Windows/Linux.

```elisp
(require 'projectile)
;; Recommended keymap prefix on macOS
(define-key projectile-mode-map (kbd "s-p") 'projectile-command-map)
;; Recommended keymap prefix on Windows/Linux
(define-key projectile-mode-map (kbd "C-c p") 'projectile-command-map)
(projectile-mode +1)
```

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

### Enable Local File System Cache

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Enable caching for local file existence checks, setting the expiration to 5 minutes. This is typically not needed but can be configured.

```elisp
(setq projectile-file-exists-local-cache-expire (* 5 60))
```

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

### Basic Projectile Configuration

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/usage.adoc

A typical Projectile configuration including optional packages like ag, vertico, and which-key. It sets up project search paths and defines keybindings for Projectile commands.

```elisp
;; Optional: ag is nice alternative to using grep with Projectile
(use-package ag
  :ensure t)

;; Optional: Enable vertico as the selection framework to use with Projectile
(use-package vertico
  :ensure t
  :init
  (vertico-mode +1))

;; Optional: which-key will show you options for partially completed keybindings
;; It's extremely useful for packages with many keybindings like Projectile.
(use-package which-key
  :ensure t
  :config
  (which-key-mode +1))

(use-package projectile
  :ensure t
  :init
  (setq projectile-project-search-path '("~/projects/" "~/work/" "~/playground"))
  :config
  ;; I typically use this keymap prefix on macOS
  (define-key projectile-mode-map (kbd "s-p") 'projectile-command-map)
  ;; On Linux, however, I usually go with another one
  (define-key projectile-mode-map (kbd "C-c C-p") 'projectile-command-map)
  (global-set-key (kbd "C-c p") 'projectile-command-map)
  (projectile-mode +1))
```

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

### Define Custom Related Files Function in Elisp

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Register a custom function to determine related files based on file paths. This example matches C++ files in 'src' or 'test' directories and generates corresponding test or implementation file paths.

```elisp
(defun my/related-files (path)
  (if (string-match (rx (group (or "src" "test")) (group "/" (1+ anything) ".cpp")) path)
      (let ((dir (match-string 1 path))
            (file-name (match-string 2 path)))
        (if (equal dir "test")
            (list :impl (concat "src" file-name))
          (list :test (concat "test" file-name)
                :other (concat "src" file-name ".def"))))))

(projectile-register-project-type
   ;; ...
   :related-files-fn #'my/related-files)
```

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

### Configure Ido for Projectile Prompts

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/migrating_to_projectile_3.adoc

For users of `ido`, enable `ido-mode` and `ido-ubiquitous-mode` to have `ido` handle Projectile's prompts via `completing-read`.

```elisp
;; M-x package-install RET ido-completing-read+ RET
(ido-mode 1)
(ido-ubiquitous-mode 1)
```

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

### Combine Multiple Related Files Function Helpers

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Configure a project type to use a list of related files function helpers for different purposes like grouping, extensions, and test prefixes. This allows for complex related file discovery logic.

```elisp
(setq my/related-files
      (list
       (projectile-related-files-fn-extensions :other '("cpp" "h" "hpp"))
       (projectile-related-files-fn-test-with-prefix "cpp" "Test")
       (projectile-related-files-fn-test-with-suffix "el" "_test")
       (projectile-related-files-fn-groups
        :doc
        '(("doc/common.txt"
           "src/foo.h"
           "src/bar.h")))))

(projectile-register-project-type
   ;; ...
   :related-files-fn my/related-files)
```

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

### Store Project-Specific Settings with .dir-locals.el

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Use a `.dir-locals.el` file in the project directory to store project-specific Emacs variables. The `nil` key applies to the entire project, and `eval` can be used to execute Elisp code.

```elisp
((nil . ((secret-ftp-password . "secret")
         (compile-command . "make target-x")
         (eval . (progn
                   (defun my-project-specific-function ()
                     ;; ...
                     )))))
 (c-mode . ((c-file-style . "BSD"))))

```

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

### Default Project Root Detection Functions

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Displays the default list of functions Projectile uses to detect project roots. The order of functions in this list determines their precedence.

```elisp
(defcustom projectile-project-root-functions
  '(projectile-root-local
    projectile-root-marked
    projectile-root-bottom-up
    projectile-root-top-down
    projectile-root-top-down-recurring)
  "A list of functions for finding project roots."
  :group 'projectile
  :type '(repeat function))
```

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

### Global Directory Ignores (Anchored vs. Anywhere)

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Globally ignore directories. Use a leading '*' to ignore directories at any depth, otherwise they are anchored to the project root.

```elisp
(setq projectile-globally-ignored-directories
      '("tmp"
        "*node_modules"
        ))
```

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

### Delegate Project Detection to vc-root-dir

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Replace the default project root detection with Emacs's built-in `vc-root-dir` function. This requires a wrapper function to match Projectile's API.

```elisp
;; we need this wrapper to match Projectile's API
(defun projectile-vc-root-dir (dir)
  "Retrieve the root directory of the project at DIR using `vc-root-dir'."
  (let ((default-directory dir))
    (vc-root-dir)))

(setq projectile-project-root-functions '(projectile-vc-root-dir))
```

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

### Index Project Asynchronously

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Initiate an asynchronous index of the current project. This warms the project files cache without blocking Emacs, allowing subsequent 'find file' operations to use the pre-populated cache.

```elisp
;; index the current project in the background
(projectile-index-project-async)
```

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

### Integrate Projectile with Consult

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Opt-in to use the Consult finder for Projectile commands. Requires Emacs 29.1+.

```elisp
(require 'projectile-consult)
(define-key projectile-command-map (kbd "f") #'projectile-consult-find-file)
```

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

### Set Projectile Search Backend

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Specifies the backend for `projectile-search`. Options include 'auto' (default), 'grep', 'ripgrep', 'ag', or 'prompt' to be asked each time.

```elisp
;; `auto' (the default) picks the first available backend, favouring ripgrep,
;; then grep (which is always available).  You can also name a specific backend
;; or use `prompt' to be asked each time.
(setq projectile-search-backend 'ripgrep)
```

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

### Configure Projectile Kill Buffer Behavior

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Control which buffers are killed when running `projectile-kill-buffers`. Set to 'kill-all' to kill all project buffers, 'kill-only-files' to keep shells and REPLs, or a custom predicate function for finer control.

```elisp
;; Kill all project buffers (the default)
(setq projectile-kill-buffers-filter 'kill-all)
```

```elisp
;; Kill only file-visiting buffers (keep shells, REPLs, etc.)
(setq projectile-kill-buffers-filter 'kill-only-files)
```

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

### Integrate Projectile with project.el

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/usage.adoc

Add this Elisp hook to enable Projectile's project lookup functions when `project-mode` is active. This allows `project.el` to use Projectile's project root and file lookup.

```elisp
(add-hook 'project-find-functions #'project-projectile)
```

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

### Enable Projectile Caching Per Project

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Configure Projectile to enable caching for a specific project by setting `projectile-enable-caching` in the `.dir-locals.el` file.

```elisp
((nil . ((projectile-enable-caching . t))))

```

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

### Set Default Completion System

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Configures Projectile to use the default completion system, which is the standard Emacs completing-read.

```elisp
(setq projectile-completion-system 'default)
```

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

### Set Default Source and Test Directories

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Configures the default directories Projectile uses for source and test files when a project type does not explicitly define them. Ensure these paths match your project's conventions.

```elisp
(setq projectile-default-src-directory "src/")
(setq projectile-default-test-directory "test/")
```

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

### Customize Test File Prefix and Suffix Functions

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Allows overriding the default functions that determine the prefix and suffix for test files. These custom functions should accept the project type and return the desired string.

```elisp
(setq projectile-test-prefix-function #'my-test-prefix)
(setq projectile-test-suffix-function #'my-test-suffix)
```

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

### Configure Git Ignored Files Command

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Sets the command used to retrieve Git-ignored files. The command must return a 0-delimited list of files relative to the project root.

```elisp
;; Command to get git-ignored files
(setq projectile-git-ignored-command "git ls-files -zcoi --exclude-standard")
```

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

### Set Projectile Switch Project Action to projectile-dired

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Configures Projectile to open the project's top-level directory in a dired buffer after switching projects. This is useful for immediately browsing the project's file structure.

```elisp
(setq projectile-switch-project-action #'projectile-dired)
```

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

### Enable Caching Unconditionally

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Force Projectile to enable file caching, regardless of the indexing method used. Caching speeds up file lookups by storing previously indexed project files.

```elisp
(setq projectile-enable-caching t)
```

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

### Global Unignore Directories

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Globally unignore specific directories that would otherwise be excluded. Useful for directories like 'vendor'.

```elisp
(setq projectile-globally-unignored-directories '("vendor"))
```

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

### Enable Projectile Uniquify Directory Transform

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Configure Projectile to use project names for disambiguating buffer names when files with the same name exist in different projects. This setting can be safely set globally.

```elisp
(setq uniquify-dirname-transform #'projectile-uniquify-dirname-transform)
```

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

### Configure Git Submodule Command

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Sets the command used to list Git submodules. Set to nil to disable submodule listing.

```elisp
;; Command to list git submodules (set to nil to disable)
(setq projectile-git-submodule-command
  "git submodule --quiet foreach 'echo $displaypath' | tr '\n' '\0'")
```

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

### Register .NET Project Type

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Registers a project type for .NET C# or F# projects. It uses a list of wildcards for project files due to their naming conventions.

```elisp
;; .NET C# or F# projects
(projectile-register-project-type 'dotnet #'projectile-dotnet-project-p
                                  :project-file '("?*.csproj" "?*.fsproj")
                                  :compile "dotnet build"
                                  :run "dotnet run"
                                  :test "dotnet test")
```

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

### Wrap Projectile's Git Command

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Customize the git command Projectile uses to list repository files by setting `projectile-git-command` in `.dir-locals.el`.

```elisp
((nil . ((projectile-git-command . "/path/to/other/git ls-files -zco --exclude-standard"))))

```

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

### Global Unignore Files

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Globally unignore specific files that would otherwise be excluded. Useful when VCS ignores files you want in Projectile.

```elisp
(setq projectile-globally-unignored-files '("important.dat"))
```

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

### Set Projectile Indexing Method to Hybrid

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Forces Projectile to use the hybrid indexing method on all operating systems.

```elisp
(setq projectile-indexing-method 'hybrid)
```

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

### Run Projectile Tests in Batch Mode

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/contributing.adoc

Execute all Projectile tests using the eldev tool. Ensure you are in the project's root directory.

```sh
$ cd /path/to/projectile
$ eldev test
```

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

### Ignore Files in .projectile

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Configure Projectile to ignore specific files and directories within a project by listing them in the `.projectile` file. Paths are relative to the root directory and should be prefixed with '-'.

```text
-/log
-/tmp
-/vendor
-/public/uploads
```

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

### Per-Project Directory Ignores

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Specify directories to ignore at the root of the project. Use relative pathnames for more specific ignores.

```projectile
-tmp
-*.rb
-*.yml
-models
```

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

### Configure Projectile Mode Line Indicator

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Customizes the Projectile mode line indicator. `projectile-mode-line-prefix` sets the static prefix, `projectile-dynamic-mode-line` controls the display of project name/type, and `projectile-mode-line-function` allows a custom function for generation.

```elisp
(setq projectile-mode-line-prefix " Projectile")
```

```elisp
(setq projectile-dynamic-mode-line t)
```

```elisp
(setq projectile-mode-line-function '(lambda () (format " Proj[%s]" (projectile-project-name))))
```

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

### Configure Projectile Known Projects File Location

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Specifies the file path where Projectile stores its list of known projects (bookmarks). Customizing this allows you to manage where Projectile saves and loads project information.

```elisp
(setq projectile-known-projects-file "~/.emacs.d/projectile-bookmarks.eld")
```

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

### Flexible Test File Detection with related-files-fn

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Uses the 'related-files-fn' option for more flexible test file discovery, supporting custom suffixes and prefixes. This method is more adaptable but does not create missing test files.

```elisp
(projectile-update-project-type
 'python-pkg
 :related-files-fn
 (list
  (projectile-related-files-fn-test-with-suffix "py" "_test")
  (projectile-related-files-fn-test-with-prefix "py" "test_")))
```

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

### Enable Automatic Project Discovery

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/usage.adoc

Enables Projectile to automatically discover projects on the configured search path. Be cautious with this setting if you have a large number of projects.

```elisp
(setq projectile-auto-discover t)
```

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

### Recursive Project Discovery Configuration

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/usage.adoc

Configures Projectile to discover projects recursively within specified directories by setting the search depth.

```elisp
(setq projectile-project-search-path '("~/projects/" "~/work/" ("~/github" . 1)))
```

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

### Custom Related Files with Extension-Specific Test Prefixes

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Implement a flexible related files function that uses different test prefixes based on file extensions. This is useful for projects with varied testing conventions.

```elisp
(defun my/related-files(file)
  (let ((ext-to-test-prefix '(("cpp" . "Test")
                              ("py" . "test_"))))
    (if-let* ((ext (file-name-extension file))
              (test-prefix (assoc-default ext ext-to-test-prefix))
              (file-name (file-name-nondirectory file)))
        (if (string-prefix-p test-prefix file-name)
            (let ((suffix (concat "/" (substring file-name (length test-prefix)))))
              (list :impl (lambda (other-file)
                            (string-suffix-p suffix other-file))))
          (let ((suffix (concat "/" test-prefix file-name)))
            (list :test (lambda (other-file)
                          (string-suffix-p suffix other-file))))))))
```

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

### Ignore Files Per Project with Projectile

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Specify files to be ignored by Projectile on a per-project basis by customizing `projectile-globally-ignored-files` in `.dir-locals.el`.

```elisp
((nil . ((projectile-globally-ignored-files . ("MyBinaryFile")))))

```

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

### Set Custom Completion Function

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Allows setting a custom Elisp function for Projectile's completion system. The function should accept a prompt and a list of choices.

```elisp
(setq projectile-completion-system #'my-custom-completion-fn)
```

```elisp
(setq projectile-completion-system
      (lambda (prompt choices)
        ;; ...
        ))
```

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

### Set Projectile Buffer Filter Function

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Configure which buffers are considered part of a project. Use `projectile-buffers-with-file` to include only file-backed buffers, or `projectile-buffers-with-file-or-process` to also include process buffers like REPLs and shells.

```elisp
;; Only include file-backed buffers
(setq projectile-buffers-filter-function #'projectile-buffers-with-file)
```

```elisp
;; Include file-backed buffers and process buffers (e.g. REPLs, shells)
(setq projectile-buffers-filter-function #'projectile-buffers-with-file-or-process)
```

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

### Configure Emacs to Debug on Error

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/troubleshooting.adoc

Toggle Emacs' behavior to display backtraces on error instead of just logging them. This is useful for diagnosing unexpected errors.

```elisp
(toggle-debug-on-error)
```

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

### Define Dynamic Compile and Test Commands

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Use Elisp functions to dynamically determine compile and test commands based on the current context, such as major mode or file path. Register these functions with `projectile-register-project-type`.

```elisp
(defun my/compile-command () "Returns a String representing the compile command to run for the given context" (cond ((and (eq major-mode 'java-mode) (not (string-match-p (regexp-quote "\\.*/test/\\.*") (buffer-file-name (current-buffer))))) "./gradlew build") ((eq major-mode 'web-mode) "./gradlew compile-templates") ))
(defun my/test-command () "Returns a String representing the test command to run for the given context" (cond ((eq major-mode 'js-mode) "grunt test") ;; Test the JS of the project ((eq major-mode 'java-mode) "./gradlew test") ;; Test the Java code of the project ((eq major-mode 'my-mode) "special-command.sh") ;; Even Special conditions/test-sets can be covered ))
(projectile-register-project-type 'has-command-at-point '("file.txt") :compile 'my/compile-command :test 'my/test-command)
```

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

### Pin Projectile to MELPA Stable

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/installation.adoc

Add this to your Emacs initialization file to ensure Projectile always uses the MELPA Stable release. This is recommended for users who prefer stability over the latest features.

```elisp
(add-to-list 'package-pinned-packages '(projectile . "melpa-stable") t)
```

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

### Global Ignore File Patterns

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Globally ignore files matching specific regular expression patterns. Useful for minified files or source maps.

```elisp
(setq projectile-global-ignore-file-patterns '("\.min\.js$" "\.map$"))
```

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

### Include Top-Level Directory in projectile-find-dir

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

When using `projectile-find-dir`, this setting ensures that the top-level directory of the project is included in the selectable list. This is often used in conjunction with `projectile-switch-project-action` set to `projectile-find-dir`.

```elisp
(setq projectile-find-dir-includes-top-level t)
```

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

### Set Sorting Order to Recently Opened

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Configure Projectile to sort files based on when they were most recently opened. This prioritizes files you've accessed recently.

```elisp
(setq projectile-sort-order 'recentf)
```

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

### Set Projectile Indexing Method to Native

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Forces Projectile to use the native Emacs Lisp indexing method on all operating systems.

```elisp
(setq projectile-indexing-method 'native)
```

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

### Enable Interactive Compilation Buffers in Projectile

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Make Projectile compilation buffers interactive by setting `projectile-comint-mode` to `t`. This allows for editing and re-running commands.

```elisp
(setq projectile-comint-mode t)

```

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

### Per-Project File Overrides

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Override ignored files to include them in the project. This is useful for files ignored by VCS but needed by Projectile.

```projectile
!/src/foo
!*.yml
```

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

### Enable Automatic Creation of Missing Test Files

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/projects.adoc

Enables Projectile to automatically create test files when you navigate to a non-existent test file. By default, Projectile signals an error in such cases.

```elisp
(setq projectile-create-missing-test-files t)
```

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

### Allow Projectile Commands Outside Projects

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/configuration.adoc

Configure Projectile to allow commands to be used in any directory, even outside of a recognized project. The current directory will be considered the project root in such cases.

```elisp
(setq projectile-require-project-root nil)
```

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

### Configure Emacs to Debug on Quit

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/troubleshooting.adoc

Enable debugging on quit to capture a backtrace when a command hangs. This helps identify the cause of freezes.

```elisp
(toggle-debug-on-quit)
```

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

### Set Default Shell to Bash for Projectile

Source: https://github.com/bbatsov/projectile/blob/master/doc/modules/ROOT/pages/troubleshooting.adoc

Configure Projectile to use Bash as the default shell if encountering issues with other shells like fish. This can resolve quoting or compatibility problems.

```elisp
(setq shell-file-name "/bin/bash")
```