Convert Figma logo to code with AI

bbatsov logoprojectile

Project Interaction Library for Emacs

4,101
584
4,101
92

Top Related Projects

20,602

An Emacs framework for the stubborn martian hacker

24,142

A community-driven Emacs distribution - The best editor is neither Emacs nor Vim, it's Emacs *and* Vim!

3,420

Emacs incremental completion and selection narrowing framework

2,355

Ivy - a generic completion frontend for Emacs, Swiper - isearch with an overview, and more. Oh, man!

Modular in-buffer completion framework for Emacs

6,832

It's Magit! A Git Porcelain inside Emacs.

Quick Overview

Projectile is a project interaction library for Emacs. It provides a set of features for efficient project management and navigation within Emacs, including project-aware file finding, searching, and task management. Projectile aims to be a universal project management tool for Emacs users.

Pros

  • Seamless integration with Emacs and various other popular Emacs packages
  • Extensive customization options to tailor the experience to individual needs
  • Supports a wide range of project types and version control systems
  • Improves productivity with quick project navigation and management features

Cons

  • Learning curve for new users, especially those not familiar with Emacs
  • Can be overwhelming with its large number of commands and options
  • May require additional configuration for optimal performance in large projects
  • Some features may conflict with other Emacs packages or user configurations

Code Examples

Here are a few examples of how to use Projectile in Emacs Lisp:

  1. Find a file in the current project:
(projectile-find-file)
  1. Switch to a different project:
(projectile-switch-project)
  1. Run a shell command in the project root:
(projectile-run-shell-command-in-root "git status")
  1. Search for text in project files:
(projectile-grep "search term")

Getting Started

To get started with Projectile, follow these steps:

  1. Install Projectile using your preferred Emacs package manager (e.g., use-package, straight.el).
  2. Add the following configuration to your Emacs init file:
(use-package projectile
  :ensure t
  :init
  (projectile-mode +1)
  :bind (:map projectile-mode-map
              ("C-c p" . projectile-command-map))
  :config
  (setq projectile-completion-system 'ivy)) ; Or your preferred completion system
  1. Restart Emacs or evaluate the configuration.
  2. Open a project directory and start using Projectile commands with the prefix C-c p.

Competitor Comparisons

20,602

An Emacs framework for the stubborn martian hacker

Pros of Doomemacs

  • Comprehensive Emacs configuration framework with a focus on performance and stability
  • Extensive module system for easy customization and feature selection
  • Integrated package management and configuration for a wide range of development tools

Cons of Doomemacs

  • Steeper learning curve due to its complexity and extensive feature set
  • Potentially overwhelming for users who prefer a minimal Emacs setup
  • Requires more system resources compared to lightweight solutions

Code Comparison

Projectile (project management):

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

Doomemacs (project management via Projectile):

(map! :leader
      (:prefix-map ("p" . "project")
       :desc "Find file in project" "f" #'projectile-find-file
       :desc "Switch project"       "p" #'projectile-switch-project))

Summary

Projectile is a focused project management tool for Emacs, while Doomemacs is a comprehensive Emacs configuration framework that includes Projectile among many other features. Projectile offers a lightweight solution for project-related tasks, whereas Doomemacs provides a complete, opinionated Emacs setup with integrated tools and optimizations. Users seeking a simple project management solution may prefer Projectile, while those looking for a full-featured Emacs experience might choose Doomemacs.

24,142

A community-driven Emacs distribution - The best editor is neither Emacs nor Vim, it's Emacs *and* Vim!

Pros of Spacemacs

  • Comprehensive Emacs configuration framework with extensive customization options
  • Integrates Vim-style editing with Emacs, appealing to a wider user base
  • Includes a vast collection of pre-configured packages and layers for various programming languages and tools

Cons of Spacemacs

  • Steeper learning curve due to its complexity and extensive feature set
  • Slower startup time compared to Projectile's lightweight approach
  • May be overwhelming for users who prefer a minimalist Emacs setup

Code Comparison

Spacemacs configuration example:

(setq-default dotspacemacs-configuration-layers
  '(
    (auto-completion :variables
                     auto-completion-enable-snippets-in-popup t)
    (git :variables
         git-magit-status-fullscreen t)
    (markdown :variables markdown-live-preview-engine 'vmd)
  ))

Projectile usage example:

(require 'projectile)
(define-key projectile-mode-map (kbd "s-p") 'projectile-command-map)
(projectile-mode +1)

Spacemacs offers a more comprehensive and opinionated configuration framework, while Projectile focuses on project management and navigation within Emacs. Spacemacs provides a pre-configured environment with numerous features, whereas Projectile is a lightweight tool that can be easily integrated into existing Emacs setups.

3,420

Emacs incremental completion and selection narrowing framework

Pros of Helm

  • More comprehensive and versatile, offering a wide range of features beyond project management
  • Provides an interactive interface for various Emacs commands and functions
  • Highly customizable with numerous extensions and plugins available

Cons of Helm

  • Steeper learning curve due to its extensive feature set
  • Can be resource-intensive, especially on older hardware or with large datasets
  • May require more configuration to achieve optimal performance

Code Comparison

Helm:

(require 'helm-config)
(helm-mode 1)
(global-set-key (kbd "M-x") #'helm-M-x)
(global-set-key (kbd "C-x r b") #'helm-filtered-bookmarks)
(global-set-key (kbd "C-x C-f") #'helm-find-files)

Projectile:

(require 'projectile)
(projectile-mode +1)
(define-key projectile-mode-map (kbd "C-c p") 'projectile-command-map)
(setq projectile-completion-system 'helm)
(helm-projectile-on)

While Helm provides a more comprehensive solution for various Emacs interactions, Projectile focuses specifically on project management. Helm offers a wider range of features but may require more setup and resources. Projectile, on the other hand, is more lightweight and easier to configure for project-specific tasks. Both can work together seamlessly, with Projectile often using Helm as its completion system for enhanced functionality.

2,355

Ivy - a generic completion frontend for Emacs, Swiper - isearch with an overview, and more. Oh, man!

Pros of Swiper

  • Focuses on enhancing search and navigation within Emacs
  • Provides a more modern, interactive interface for searching
  • Offers a family of related packages (ivy, counsel) for a cohesive experience

Cons of Swiper

  • More specialized in functionality compared to Projectile's broad project management features
  • May require additional configuration to integrate with project-specific workflows
  • Learning curve can be steeper for users accustomed to traditional Emacs search methods

Code Comparison

Swiper (using ivy):

(ivy-mode 1)
(global-set-key (kbd "C-s") 'swiper)
(global-set-key (kbd "M-x") 'counsel-M-x)
(global-set-key (kbd "C-x C-f") 'counsel-find-file)

Projectile:

(projectile-mode +1)
(define-key projectile-mode-map (kbd "C-c p") 'projectile-command-map)
(setq projectile-completion-system 'ivy)

Summary

Swiper excels in enhancing Emacs' search capabilities with a modern interface, while Projectile offers comprehensive project management features. Swiper, along with its companion packages, provides a more focused set of tools for navigation and search. Projectile, on the other hand, offers a broader range of project-related functionalities. The choice between the two depends on whether the user prioritizes advanced search capabilities or overall project management features.

Modular in-buffer completion framework for Emacs

Pros of Company-mode

  • Focused on auto-completion, providing a more specialized and refined experience
  • Extensive backend support for various programming languages and modes
  • Highly customizable appearance and behavior

Cons of Company-mode

  • Limited project management features compared to Projectile
  • Narrower scope, focusing primarily on completion rather than overall project workflow

Code Comparison

Company-mode configuration example:

(use-package company
  :config
  (setq company-idle-delay 0.3)
  (global-company-mode 1))

Projectile configuration example:

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

Summary

Company-mode and Projectile serve different purposes in the Emacs ecosystem. Company-mode excels at providing a robust auto-completion framework, while Projectile offers comprehensive project management tools. Company-mode is more focused and specialized, whereas Projectile has a broader scope for managing projects. The choice between the two depends on the specific needs of the user, with many Emacs enthusiasts opting to use both packages in conjunction for a more complete development environment.

6,832

It's Magit! A Git Porcelain inside Emacs.

Pros of Magit

  • More comprehensive Git integration, offering a full-featured interface for Git operations within Emacs
  • Provides an intuitive and powerful staging interface for commits
  • Offers advanced features like interactive rebasing and bisecting

Cons of Magit

  • Steeper learning curve due to its extensive feature set
  • Primarily focused on Git, while Projectile offers broader project management capabilities
  • Larger codebase, potentially leading to slower load times

Code Comparison

Magit (transient definition):

(transient-define-prefix magit-commit ()
  "Create a new commit or amend an existing commit."
  :info-manual "(magit)Initiating a Commit"
  ["Arguments"
   ("-a" "Stage all modified and deleted files"   ("-a" "--all"))
   ("-e" "Allow empty commit"                     "--allow-empty")
   ("-v" "Show diff of changes to be committed"   ("-v" "--verbose"))]
  ["Actions"
   ("c" "Commit"         magit-commit-create)
   ("a" "Amend"          magit-commit-amend)])

Projectile (project management):

(defun projectile-project-root (&optional dir)
  "Retrieves the root directory of a project.
If DIR is not supplied its set to the current directory by default."
  (let ((dir (or dir default-directory)))
    (or (projectile-root-top-down dir projectile-project-root-files-top-down-recurring)
        (projectile-root-bottom-up dir projectile-project-root-files)
        (projectile-root-top-down-recurring dir projectile-project-root-files-bottom-up))))

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Projectile

Build Status MELPA MELPA Stable NonGNU ELPA License GPL 3 Discord

Synopsis

Projectile is a project interaction library for Emacs. It provides a powerful set of features operating at the project level, as well as simple heuristics to identify projects.

Here are some of essential Projectile's features:

  • jump to a file in project
  • jump to a project buffer
  • jump to a test in project
  • toggle between files with same names but different extensions (e.g. .h <-> .c/.cpp, Gemfile <-> Gemfile.lock)
  • toggle between code and its test (e.g. main.service.js <-> main.service.spec.js)
  • jump to recently visited files in the project
  • switch between projects you have worked on
  • kill (close) all project buffers
  • grep (search) in project
  • replace in project
  • find references in project (using xref internally)
  • run shell commands in a project (e.g. make, lein)
  • support for multiple minibuffer completion/selection libraries (ido, ivy, helm, and the default completion system)
  • automatic project discovery (see projectile-project-search-path)
  • integration with the built-in project.el library

There's also a rich ecosystem of third-party Projectile extensions that add even more features.


Patreon Paypal

I've been developing Projectile for over a decade now (since 2011). While it's a fun project to work on, it still requires a lot of time and energy to maintain.

You can support my work on Projectile via PayPal, Patreon and GitHub Sponsors.

Projectile in Action

Here's a glimpse of Projectile in action (using ivy):

Projectile Demo

In this short demo you can see:

  • finding files in a project
  • switching between implementation and test
  • switching between projects

Quickstart

The instructions that follow are meant to get you from zero to a running Projectile setup in a minute. Visit the online documentation for (way) more details.

Installation

package.el is the built-in package manager in Emacs.

Projectile is available on all major package.el community maintained repos - NonGNU ELPA, MELPA Stable and MELPA.

You can install Projectile with the following command:

M-x package-install [RET] projectile [RET]

Alternatively, users of Debian 9 or later or Ubuntu 16.04 or later may simply apt-get install elpa-projectile.

Finally add this to your Emacs config:

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

Those keymap prefixes are just a suggestion. Feel free to put there whatever works best for you.

Basic Usage

Enable projectile-mode, open a file in one of your projects and type a command such as C-c p f.

See the online documentation for more details.

To get the most of Projectile you also need to enable (and potentially install) some minibuffer completion framework (e.g. ido, ivy or vertico). See this section of the documentation for more details.

[!CAUTION]

Historically projectile-completion-system defaulted to ido, but this was changed in version 2.3. You may need to enable ido-mode in your Emacs configuration if updating from an older version of Projectile.

Design Goals

In this section you'll find some notes on Projectile's design goals, that have been upheld since the earliest days of the project.

Portability

Projectile provide a nice set of features operating on a project level without introducing external dependencies (when feasible). For instance - finding project files has a portable implementation written in pure Emacs Lisp without the use of GNU find (but for performance's sake an indexing mechanism backed by external commands exists as well).

Simplicity

This library provides easy project management and navigation. The concept of a project is pretty basic - just a folder containing some special file (e.g. a VCS marker or a project descriptor file like pom.xml or Gemfile). Projectile will auto-detect pretty much every popular project type out of the box and you can easily extend it with additional project types.

Easy to Use

The configuration defaults are pretty reasonable and most users will probably never feel a strong need to change them.

All commands are easily discoverable and are unlikely to surprise you with their behavior.

Practicality

Projectile tries to be practical - portability is great, but if some external tools could speed up some task substantially and the tools are available, Projectile will leverage them.

Flexibility

In the classic spirit of Emacs almost every aspect of Projectile's behavior is configurable.

Caveats

  • Some operations like search (grep) depend (presently) on external utilities such as find or fd (version 8.3.0+).
    • for older fd version add (setq projectile-generic-command "fd . -0 --type f --color=never") to your init-file
  • Commands depending on external utilities might misbehave on the fish shell.
  • Using Projectile over TRAMP might be slow in certain cases.
  • Some commands might misbehave on complex project setups (e.g. a git project with submodules).
  • Projectile was mostly tested on Unix OS-es (e.g. GNU/Linux and macOS), so some functionality might not work well on Windows.
  • In Git repositories, deleted files are still shown in projectile-find-file until their deletions are staged, due to a limitation of git ls-files. If you install fd then it is automatically used instead, and does not have this problem. (You can inhibit the use of fd by setting projectile-git-use-fd to nil.)

Known issues

Check out the project's issue list a list of unresolved issues. By the way - feel free to fix any of them and send me a pull request. :-)

Contributors

Here's a list of all the people who have contributed to the development of Projectile (a.k.a. Projectile's Hall of Fame).

Joining this esteemed group of people is only a commit away!

Changelog

A fairly extensive changelog is available here.

License

Copyright © 2011-2025 Bozhidar Batsov and contributors.

Distributed under the GNU General Public License, version 3