projectile

如果要安装在主分支中找到的 Projectile 版本，请在 Emacs 初始化文件（.emacs 或 init.el）中声明以下内容：

(use-package projectile
  :ensure t
  :config
  (define-key projectile-mode-map (kbd "s-p") 'projectile-command-map)
  (define-key projectile-mode-map (kbd "C-c p") 'projectile-command-map)
  (projectile-mode +1))

但是，如果您想要更加保守并且只使用 Projectile 的稳定版本，需要声明以下内容：

(use-package projectile
  :ensure t
  :pin melpa-stable
  :config
  (define-key projectile-mode-map (kbd "s-p") 'projectile-command-map)
  (define-key projectile-mode-map (kbd "C-c p") 'projectile-command-map)
  (projectile-mode +1))

Projectile 与 Emacs Prelude 捆绑在一起。如果是 Prelude 用户，Projectile 已经正确配置。

Projectile 的主要目标之一是在不需要任何配置的情况下操作各种项目类型。为实现这一点，它包含许多项目检测逻辑和项目类型特定的逻辑。

Projectile 可讲大多数版本控制的仓库识别为一个项目。Projectile 支持：

• Git
• Mercurial
• Bazaar
• Subversion
• CVS
• Fossil
• Darcs

Projectile 将许多文件识别为表示项目的 root。通常这些文件是各种构建工具的配置文件。支持以下内容：

Projectile 自己的 .projectile 既可以作为项目标记，也可以作为配置文件。将在本节后面详细讨论。

如果没有正确识别正在处理的项目，或者想定制项目类型，则可以在 Emacs 初始化代码中添加以下内容：

(projectile-register-project-type 'npm '("package.json")
                  :compile "npm install"
                  :test "npm test"
                  :run "npm start"
                  :test-suffix ".spec")

如果要动态定义编译命令，可以在项目类型定义中传递函数的符号引用：

(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)

如果现在导航到 ./tests/ 目录下具有 *.java 扩展名的文件，并点击 C-c c p ，将看到 ./gradlew build 作为建议。 如果要导航到 HTML 文件，编译命令将切换到 ./gradlew compile-templates 。

可同样设置的还有：

• :configure
• :compile
• :compilation-dir
• :run

请注意，函数必须返回一个字符串才能正常工作。

可以设置 projectile-project-root-files, projectile-project-root-files-top-down-recurring, projectile-project-root-files-bottom-up and projectile-project-root-files-functions 的值来定制如何识别项目的 root。

注意：使用 alien 方法索引项目时，忽略.projectile 的内容。

如果想 Projectile 在索引项目时忽略某些文件，可以在 .projectile 文件中添加要忽略的路径，其中所有相对于根目录的路径都以 / 开头。忽略的项目都应该以 - 符号开头。 或者，没有任何前缀也意味着忽略后面的目录或文件模式。 以下是典型 Rails 应用程序的示例：

-/log
-/tmp
-/vendor
-/public/uploads

这将忽略仅在项目根目录下的文件夹。Projectile 还支持相对路径名忽略：

-tmp
-*.rb
-*.yml
-models

也可以忽略除某些子目录之外的所有内容。 这在选择要保留的目录比选择要忽略的目录更容易时很有用，尽管您可以同时执行这两个操作。 选择要保留的目录，这意味着其他所有内容都将被忽略。

+/src/foo
+/tests/foo

注意：此时只能包含子目录，而不能包含文件模式。

如果目录同时被指定为保留和忽略，则首先应用要保留，从而限制考虑的文件。然后将要忽略的路径和模式应用于该集合。

最后，可以覆盖被忽略的文件。当 VCS 忽略的某些文件应被视为项目的一部分时，这尤其有用：

!/src/foo
!*.yml

如果要用指定文件覆盖 projectile 项目的 root，可以设置文件局部变量 projectile-project-root。 如果一个项目中的文件与另一个项目相关（例如，一个 git 仓库中的 Org 文件与其他项目相对应），这将非常有用。

即使相同的语言项目也有可能各不相同：编码样式、自动完成源等。如果需要根据所选项目设置一些变量，可以使用名为 Per-directory Local 的 Emacs 标准功能。要使用它，您必须在项目目录中创建名为 .dir-locals.el 的文件（由常量 dir-locals-file 指定）。 此文件包含内容与以下类似：

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

使用键 nil 引用的顶级 alist 成员适用于整个项目。 名为 eval 的键将会求值。在上面的示例中，它用于创建函数。 它也可以用于将这样的函数添加到键映射中。

还可以使用 s-p E（M-x projectile-edit-dir-locals RET） 快速访问或创建 dir-locals-file 。

以下是如何在 Projectile 中使用此功能的几个示例。

Projectile 有三种操作模式 - 一种是可移植的，使用 Emacs Lisp 实现（因此它是 Emacs 原生，被称为 native 索引方法），另外两种（hybrid 和 alien）依赖于外部命令，如 find，git 等 获取项目中的文件列表。

alien 索引方法优化了 hybrid 索引方法的速度。 这意味着 Projectile 不会对外部命令返回的文件进行任何处理，将获得最大的性能。这种行为适用于大多数人，因为他们通常会在他们的 VCS 配置中放弃忽略（例如.gitignore），并且不会关心 Projectile 可能提供的任何其他 ignores/unignores/sorting。

默认情况下，alien 方法用于除 Windows 之外的所有操作系统。Projectile 2.0 之前 hybrid 曾经是默认设置。

要在所有操作系统中强制使用 native 索引：

(setq projectile-indexing-method 'native)

强制在所有操作系统中使用 hybrid 索引：

(setq projectile-indexing-method 'hybrid)

强制在所有操作系统中使用 alien 索引：

(setq projectile-indexing-method 'alien)

Windows 中这可以显著加速 Projectile（特别是在大型项目中）。 这种方法的缺点是它在 Windows 系统上得不到很好的支持，因为它需要在那里设置一些 Unix 实用程序。 如果出现问题，可以使用 native 索引模式。

alien 索引以一种非常简单的方式工作 - 它只是执行一个返回项目中文件列表的命令。 对于版本控制的项目，默认情况下，Projectile 将使用 VCS 本身来获取文件列表。例如，Projectile 用于 Git 项目的命令：

git ls-files -zco --exclude-standard

对于支持的 VCS，都有一个匹配的 Projectile 命令调用它（例如 projectile-git-command，projectile-hg-command 等）。

警告：如果决定调整这些命令，请记住命令应该总是返回相对于项目根目录的文件列表，结果文件列表应该是 0 分隔（而不是换行符分隔）。

对于非版本控制的项目，Projectile 将调用 projectile-generic-command 中的命令。默认情况下是：

find . -type f -print0

安装 fd 并用其替代 git ls-files （fd 理解 .gitignore ）和 find 是个好主意。

如果希望在每个目录中都使用 Projectile（即使没有项目文件）：

   (setq projectile-require-project-root nil)

当运行 projectile-switch-project（s-p p）时，Projectile 会调用 projectile-switch-project-action 中指定的命令（默认情况下它是 projectile-find-file）。

使用前缀参数（C-u s-p p）调用命令将触发 Projectile Commander，可以快速访问可能要在项目上调用的大多数常用命令。

根据您的个人工作流程和习惯，可能需要改变 projectile-switch-project-action 的值：

每当 Emacs 在该项目中空闲 projectile-idle-timer-seconds 配置时间（默认为 30 秒），可以运行配置 projectile-idle-timer-hook。要启用此功能，请运行：

(add-hook 'projectile-idle-timer-hook #'my-projectile-idle-timer-function)

默认情况下，Projectile 的 minor mode 指示器以 “Projectile [ProjectName：ProjectType]” 的形式出现。可以通过几个自定义变量进行配置：

• projectile-mode-line-prefix （默认为 “Projectile”）控制 mode-line 的静态部分。
• projectile-dynamic-mode-line （默认为 t）控制是否显示 mode-line 的项目名称和类型部分。

• projectile-mode-line-function （默认为 projectile-default-mode-line）控制要生成 mode-line 的实际调用的函数。如果想显示不同的信息，应该提供一个自定义函数来替换默认值，例如：

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

注意：编辑远程文件时（通过 TRAMP），项目名称和类型不会出现，因为重新计算项目名称是一个相当慢的操作，并且会减慢打开文件的速度。它们也不会出现在非文件缓冲区中，因为它们是通过 find-file-hook 更新的。