Exploring large projects with Projectile and Helm Projectile

Demo (begins when START DEMO appears in minibuffer):

In the demo, a few files are narrowed and marked, then opened. I ran helm-mini to display a list of opened txt files.

Demo (begins when START DEMO appears in minibuffer):

As you can see in the demo, Projectile can jump anywhere, even if there's only a filename without path. It works everywhere, even in text file.

• In the demo, the first path is a file that I opened using a command from M-x.
• The second path is a directory that I opened using a key binding.
• The third path is highlighted in a region and I opened using command history in Helm, so no need to type anything.

Demo (begins when START DEMO appears in minibuffer):

In the demo, I marked a few files with helm-projectile-find-file, then switched to action menu and selected Copy file(s) action (it can be executed with a key binding, but I want to show you the action as a proof). Then, I copy to the directory ~/test. Notice that I got prompted to that directory immediately, because another Dired buffer is below. After I confirmed the action, 4 files got copied and displayed at the lower Dired buffer of ~/test.

Demo (begins when START DEMO appears in minibuffer):

As you see, you don't have to navigate to a file to delete it. All project files are always at your finger tip for you to delete!

Demo (begins when START DEMO appears in minibuffer):

• First, I select helm-projectile-find-other-file and a list of other files displayed.
• Then, I marked a few files and press RET to open all.
• Finally, I use helm-mini to open a list of opened buffers and the files I marked and opened are there.

NOTE: In the demo, you can see me narrow to a small set of files, then mark them and perform some action (such as copy or delete). However, if you want to continue to mark other files, you can delete the previous search pattern and enter another search pattern to narrow to another set of files and continue marking those files without losing your old markings. For example, at the beginning I want to mark files with the string "aaaa" in it; after done marking those files, I delete "aaaa" and enter "bbbb" to narrow to this set of files and mark the needed files, without losing the markings on the files contains "aaaa".

Usage: This command lists all files in a project for users to narrow down to wanted files. Some frequently used actions that cover open, rename, copy, delete,search and other miscelaneous operations. Once you mastered the actions of helm-projectile-find-file, you master the actions of other commands as well since the actions of other commands are just a subset of helm-projectile-find-file actions. All the key bindings associated with actions are only available while a Helm buffer is active. You can think of actions as an mini version of M-x: only applicable commands are listed, and even those commands have key bindings. Prefix argument can be applied, when possible.

The same Helm interface can be used to search for an action. The first 12 actions are bound from <f1> to <f12>. You can type the index number to instantly narrow to that action, or simply press respective key.

This command is another one that can be used outside of any project. When executed, it lists all files in all known projects. Depends on your style, use this command or helm-projectile-switch-project command, when you want to jump to a file. Note that this command could be slow to show you the list of files if there is a large number of files. To speed it up, it is beneficial to enable caching. You will learn about caching at near the end of this tutorial. With caching, Projectile won't have to build up a list of files again; it simply reuses, and show you the list instantly for selecting.

The action menu is the same as helm-projectile-find-file.

Usage: Find file based on context at point (do what you mean):

• If the command finds just a file, it switches to that file instantly. This works even if the filename is incomplete, but there's only a single file in the current project that matches the filename at point. For example, if there's only a single file named "projectile/projectile.el" but the current filename is "projectile/proj" (incomplete), the command still switches to "projectile/projectile.el" immediately because this is the only filename that matches.
• If it finds a list of files, the list is displayed for selecting. A list of files is displayed when a filename appears more than one in the project or the filename at point is a prefix of more than two files in a project. For example, if `projectile-find-file' is executed on a path like "projectile/", it lists the content of that directory. If it is executed on a partial filename like "projectile/a", a list of files with character 'a' in that directory is presented.
• If it finds nothing, display a list of all files in project for selecting.

This command is demonstrated at the beginning: Open file at point anywhere.

Usage: List available directories in the current project.

Available actions:

• Open Dired in project's directory: Open the directory in a Dired buffer.
• Switch to Eshell (M-e): Open the directory in Eshell.
• Grep in projects (C-s; add prefix C-u for recurse Grep): Run grep on selected directory.

Usage: List recently visited files in current project. The command has a subset of actions in helm-projectile-find-file, so once you mastered the actions in helm-projectile-find-file, you can reuse your knowledge here.

Usage: Switch between files with the same name but different extensions. With prefix argument C-u, enable flex-matching that match any file that contains the name of current file. The command has a subset of actions in helm-projectile-find-file, so once you mastered the actions in helm-projectile-find-file, you don't need to learn anything else.

Other file extensions can be customized with the variable projectile-other-file-alist. The variable looks like this:

'(("cpp" "h" "hpp" "ipp")
  ("ipp" "h" "hpp" "cpp")
  ("hpp" "h" "ipp" "cpp")
  ("cxx" "hxx" "ixx")
  ("ixx" "cxx" "hxx")
  ("hxx" "ixx" "cxx")
  ("c" "h")
  ("m" "h")
  ("mm" "h")
  ("h" "c" "cpp" "ipp" "hpp" "m" "mm")
  ("cc" "hh")
  ("hh" "cc")
  ("vert" "frag")
  ("frag" "vert")
  (nil "lock" "gpg")
  ("lock" "")
  ("gpg" ""))

Basically just a list of lists. Each lists hold the current file extension as first element and other files' extensions to switch to. For example, the list ("cpp" "h" "hpp" "ipp") means that if your current file is foo.cpp, the command will search for other files with foo as exact name (add prefix C-u for any file that contains foo) and with extensions .h, .hpp and .ipp; anything but .cpp.

If you want to add more, for example, to switch between html <-> js, add to your init file like this:

(add-to-list 'projectile-other-file-alist '("html" "js")) ;; switch from html -> js
(add-to-list 'projectile-other-file-alist '("js" "html")) ;; switch from js -> html

The command is already demonstrated in the section Switch between current file and other files with same names but different extensions.

Usage: In large projects, caching can significantly speedup file and directory listings, making it display instantly. Caching is enabled by:

(setq projectile-enable-caching t)

With caching enabled, even if you use Projectile on your home directory with 30GB, it lists files instantly. Cache is a way to speed up getting files because Projectile only needs to index your project once and reuses this result future usages. In case if your project has new files, you have to add C-u before executing any command to invalidate the cache (except for helm-projectile-find-other-file and projectile-find-other-file, C-u is reserved for different behaviour), or using standalone command invalidate C-c p i to refresh the whole cache.

Using Bookmark (or Bookmark+), you can actually save your virtual Dired buffers and preserve this knowledge for future reference, when you want to quickly review related files to improve or fix bug. You won't have to reconnect related files again, and often it takes quite some time since you could forget many things.

If you haven't learned how to use Bookmark, learn the basics of it with Xah Lee's "Emacs: Using Bookmark Feature" article. I recommend you to install Bookmark+ because it offers much more features. For example, you can write annotations for (C-u a on a bookmark) bookmarks in Org-mode and read the annotation with Org-mode (press a to open the annotation of a bookmark for reading). To learn all about Bookmark+ features, please refer to Bookmark+ documentation.

Usage: List all opened buffers in current project. The command has a similar subset of actions in helm-projectile-find-file, so once you mastered the actions in helm-projectile-find-file, except instead of opening files, you open buffers instead.

This is a replacement command for projectile-grep that uses Helm interface. When a symbol is at point, this command uses that symbol and search at project root for every occurrence of this symbol in all non-ignored files in project. If a region is active, use the region instead.

Demo (begins when START DEMO appears in minibuffer):

You can specify directory to exclude when searching by customize either one of these variables:

• grep-find-ignored-files: List of file names which rgrep and lgrep shall exclude. helm-projectile-grep also uses this variable.
• grep-find-ignored-directories: List of names of sub-directories which rgrep shall not recurse into. helm-projectile-grep also uses this variable.
• projectile-globally-ignored-files: A list of files globally ignored by Projectile.
• projectile-globally-ignored-directories: A list of directories globally ignored by Projectile.

For example, if you have a directory like personal/backup and if you want to ignore directory backup, simply add backup to the grep-find-ignored-directories or projectile-globally-ignored-directories. For example, if I use projectile-globally-ignored-directories, I would do it like this:

(add-to-list 'projectile-globally-ignored-directories "backup")

You can also use C-h v and select either of the above variables and use customize GUI to add your selections.

NOTE: For helm-projectile-grep, when specifying directories to ignore, you must enter only the names of sub-directories, not its full path, either absolute or relative to current project. In the example above, I only add backup, not personal/backup.

Finally, if you quit your current helm-projectile-grep session with current search results and don't want to search things all over again, you can save the result with the action Save results in grep buffer (bound to <f3>). Or you can simply resume the previous buffer with helm-resume (you should bind it to a key. If your follow my Helm guide, it is bound to C-c h b); if you helm-projectile-grep buffer is not the most recently used Helm buffer, add C-u before running helm-resume to select it from the list of all previously Helm buffers of all ran Helm commands.

This is a replacement command for projectile-ack. Similar to helm-projectile-grep, but use ack instead. You must have ack installed to be able to use this command. You can also customize these variables to ignore files or directories:

• grep-find-ignored-files: List of file names which rgrep and lgrep shall exclude, and helm-projectile-ack also uses this variable.
• grep-find-ignored-directories: List of names of sub-directories which rgrep shall not recurse into. helm-projectile-ack also uses this variable.
• projectile-globally-ignored-files: A list of files globally ignored by Projectile.
• projectile-globally-ignored-directories: A list of directories globally ignored by Projectile.

Similarly, you can save results in a grep buffer with the action Save results in grep buffer (bound to <f3>), and resume with C-c h b (add C-u to select from the list of all previous Helm sessions).

NOTE: if you want ack to ignore files/directories, you must use regex pattern. Otherwise it won't work.

This is a replacement command for projectile-ag. Similar to helm-projectile-grep, but use ag insetad. You must have ag and helm-ag installed to be able to use this command. This command only works with symbol at point, but not region. You can also customize these variables to ignore files or directories:

• grep-find-ignored-files: List of file names which rgrep and lgrep shall exclude, and helm-projectile-ack also uses this variable.
• grep-find-ignored-directories: List of names of sub-directories which rgrep shall not recurse into. helm-projectile-ack also uses this variable.
• projectile-globally-ignored-files: A list of files globally ignored by Projectile.
• projectile-globally-ignored-directories: A list of directories globally ignored by Projectile.

NOTE: Unlike helm-projectile-grep, you can specify directory with path to ignore. For example, you can only specify sub-directory names to ignore in helm-projectile-grep, i.e. backup not personal/backup, but with helm-projectile-ag, either backup or personal/backup works fine.