branch: elpa/projectile
commit 6a11eff0a66cd35c3dce761125a07fa9e2805795
Author: Bozhidar Batsov <[email protected]>
Commit: Bozhidar Batsov <[email protected]>
Document previously undocumented configuration options
- fd integration: projectile-git-use-fd, projectile-fd-executable,
projectile-git-fd-args
- Known projects: projectile-known-projects-file,
projectile-ignored-projects, projectile-ignored-project-function,
projectile-track-known-projects-automatically
- Buffer filtering: projectile-buffers-filter-function,
projectile-kill-buffers-filter
- Test/impl toggling: projectile-default-src-directory,
projectile-default-test-directory, projectile-test-prefix-function,
projectile-test-suffix-function, projectile-create-missing-test-files
---
doc/modules/ROOT/pages/configuration.adoc | 61 ++++++++++++++++++++++++++++
doc/modules/ROOT/pages/projects.adoc | 66 +++++++++++++++++++++++++++++++
2 files changed, 127 insertions(+)
diff --git a/doc/modules/ROOT/pages/configuration.adoc
b/doc/modules/ROOT/pages/configuration.adoc
index 4e7cac7543..f16d4cf3b1 100644
--- a/doc/modules/ROOT/pages/configuration.adoc
+++ b/doc/modules/ROOT/pages/configuration.adoc
@@ -82,6 +82,27 @@ find . -type f -print0
TIP: It's a great idea to install https://github.com/sharkdp/fd[fd] which is
much faster than `find`.
If `fd` is found, projectile will use it as a replacement for `find`.
+By default, `fd` is also used inside Git repositories (instead of `git
ls-files`),
+because `git ls-files` has the limitation that it lists deleted files until the
+deletions are staged. You can control this with `projectile-git-use-fd`:
+
+[source,elisp]
+----
+;; Disable fd in git repos (use git ls-files instead)
+(setq projectile-git-use-fd nil)
+----
+
+You can also customize the path to the `fd` executable and the arguments
passed to it:
+
+[source,elisp]
+----
+;; Use a custom fd path
+(setq projectile-fd-executable "/usr/local/bin/fd")
+
+;; Customize the fd arguments used in git repos
+(setq projectile-git-fd-args "-H -0 -E .git -tf --strip-cwd-prefix -c never")
+----
+
== Sorting
You can choose how Projectile sorts files by customizing
`projectile-sort-order`.
@@ -398,6 +419,46 @@ want to set
in order to allow for the occasions where you want to select the
top-level directory.
+== Known Projects
+
+Projectile stores the list of known projects in a file on disk. You can
+customize its location:
+
+[source,elisp]
+----
+(setq projectile-known-projects-file "~/.emacs.d/projectile-bookmarks.eld")
+----
+
+=== Ignoring projects
+
+You can prevent certain projects from being added to the known projects list:
+
+[source,elisp]
+----
+;; A list of projects to ignore
+(setq projectile-ignored-projects '("/tmp/" "~/.emacs.d/"))
+----
+
+For more flexible filtering, set `projectile-ignored-project-function` to a
+predicate that receives a project root and returns non-nil if the project
should
+be ignored:
+
+[source,elisp]
+----
+;; Ignore all remote (TRAMP) projects
+(setq projectile-ignored-project-function #'file-remote-p)
+----
+
+=== Automatic tracking
+
+By default, Projectile automatically adds projects to the known projects list
+whenever you visit a file in a project. You can disable this:
+
+[source,elisp]
+----
+(setq projectile-track-known-projects-automatically nil)
+----
+
== Completion Options
Projectile supports all major minibuffer completion packages that
diff --git a/doc/modules/ROOT/pages/projects.adoc
b/doc/modules/ROOT/pages/projects.adoc
index 4a07aca001..abb3a19b82 100644
--- a/doc/modules/ROOT/pages/projects.adoc
+++ b/doc/modules/ROOT/pages/projects.adoc
@@ -681,6 +681,40 @@ could be:
In fact this is a lot more flexible in terms of finding test files in different
locations, but will not create test files for you.
+=== Default source and test directories
+
+When a project type doesn't specify `:src-dir` or `:test-dir`, Projectile falls
+back to these defaults:
+
+[source,elisp]
+----
+(setq projectile-default-src-directory "src/")
+(setq projectile-default-test-directory "test/")
+----
+
+=== Custom test prefix/suffix functions
+
+For advanced use cases you can replace the functions that determine the test
+file prefix and suffix. These receive the project type and should return the
+appropriate prefix or suffix string:
+
+[source,elisp]
+----
+(setq projectile-test-prefix-function #'my-test-prefix)
+(setq projectile-test-suffix-function #'my-test-suffix)
+----
+
+=== Creating missing test files
+
+By default, when you toggle to a test file that doesn't exist, Projectile will
+signal an error. If you'd like Projectile to create the missing test file
+automatically:
+
+[source,elisp]
+----
+(setq projectile-create-missing-test-files t)
+----
+
== Customizing Project Detection
Project detection is pretty simple - Projectile just runs a list of
@@ -979,6 +1013,38 @@ Here are a couple of examples:
"occur-mode"))
----
+=== Buffer filtering
+
+You can supply a custom filter function for `projectile-project-buffers` via
+`projectile-buffers-filter-function`. Projectile ships with two built-in
+filters you can use:
+
+[source,elisp]
+----
+;; Only include file-backed buffers
+(setq projectile-buffers-filter-function #'projectile-buffers-with-file)
+
+;; Include file-backed buffers and process buffers (e.g. REPLs, shells)
+(setq projectile-buffers-filter-function
#'projectile-buffers-with-file-or-process)
+----
+
+=== Killing project buffers
+
+When you run `projectile-kill-buffers` (kbd:[s-p k]), the variable
+`projectile-kill-buffers-filter` controls which buffers get killed:
+
+[source,elisp]
+----
+;; Kill all project buffers (the default)
+(setq projectile-kill-buffers-filter 'kill-all)
+
+;; Kill only file-visiting buffers (keep shells, REPLs, etc.)
+(setq projectile-kill-buffers-filter 'kill-only-files)
+----
+
+You can also set it to a custom predicate function that receives a buffer and
+returns non-nil if the buffer should be killed.
+
== Configure a Project's Lifecycle Commands and Other Attributes
There are a few variables that are intended to be customized via
`.dir-locals.el`.
