https://github.com/qkessler/consult-project-extra
Consult extension for project.el
https://github.com/qkessler/consult-project-extra
emacs emacs-package management project
Last synced: 6 months ago
JSON representation
Consult extension for project.el
- Host: GitHub
- URL: https://github.com/qkessler/consult-project-extra
- Owner: Qkessler
- License: gpl-3.0
- Created: 2022-02-13T16:20:57.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-09-26T06:03:38.000Z (9 months ago)
- Last Synced: 2025-09-26T08:14:37.232Z (9 months ago)
- Topics: emacs, emacs-package, management, project
- Language: Emacs Lisp
- Homepage:
- Size: 2.38 MB
- Stars: 71
- Watchers: 2
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README.org
- License: LICENSE
Awesome Lists containing this project
README
#+title: consult-project-extra.el - consult extension for project.el
#+author: Enrique Kessler Martínez
#+language: en
#+html: 
[[https://melpa.org/#/consult-project-extra][file:https://melpa.org/packages/consult-project-extra-badge.svg]]
* Introduction
consult-project-extra defines an endpoint for accessing different sources related to the common project workflow. Using [[https://github.com/minad/consult][Consult]]'s narrowing system, the user is able to access the current project's buffers, project files and all the known projects, in case they want to change projects quickly. consult-project-extra provides an extension to the default [[https://github.com/minad/consult][Consult]] functionality, using the built-in package =project.el=, defining the functions =consult-project-extra-find= and =consult-project-extra-find-other-window=. Furthermore, consult-project-extra only depends on consult, resulting in a lean and simple to maintain functionality.
Additionally consult-project-extra provides optional integrations for [[https://github.com/domtronn/all-the-icons.el][all-the-icons]], [[https://github.com/oantolin/embark][embark]] and [[https://github.com/minad/marginalia][marginalia]], if those packages are installed.
⚠️ *NOTE*: This package has come to life adapting the great package [[https://gitlab.com/OlMon/consult-projectile][consult-projectile by OlMon]]. Most if not all credit should go to him, I have been using his package for months now. What inspired me to create this package is my recent effort to avoid most third party packages, specially if they prefer a newly defined interface over the built-in Emacs interface.
** Table of Contents :TOC:
- [[#introduction][Introduction]]
- [[#screenshots][Screenshots]]
- [[#why-projectel][Why =project.el=?]]
- [[#installation][Installation]]
- [[#straightel][Straight.el]]
- [[#manually][Manually]]
- [[#credit][Credit]]
* Screenshots
All screenshots have been taken calling =consult-project-extra-find=, which I have bound to a keybinding.
- Buffer narrowing
[[file:videos/consult-project-buffers.gif]]
- Project file narrowing
[[file:videos/consult-project-files.gif]]
- Known projects narrowing
[[file:videos/consult-project-projects.gif]]
* Why =project.el=?
As stated in the Emacs manual:
#+begin_quote
28.2 Working with Projects
==========================
A “project” is a collection of files used for producing one or more
programs. Files that belong to a project are typically stored in a
hierarchy of directories; the top-level directory of the hierarchy is
known as the “project root”.
Whether a given directory is a root of some project is determined by
the project-specific infrastructure, known as “project back-end”. Emacs
currently supports two such back-ends: VC (*note Version Control::),
whereby a VCS repository is considered a project; and EDE (*note EDE::).
This is expected to be extended in the future to support additional
types of projects.
Which files do or don’t belong to a project is also determined by the
project back-end. For example, the VC back-end doesn’t consider
“ignored” files (*note VC Ignore::) to be part of the project.
#+end_quote
=project.el= contains generic infrastructure for dealing with projects, some utility functions, and commands using that infrastructure. The goal is to make it easier for Lisp programs to operate on the current project, without having to know which package handles detection of that project type, parsing its configuration files, etc. Throughout the years, =project.el= has defined utility functions, extending the project detection API. Some examples (from the functions that I use the most) are the functions:
- =project-shell-command=: run a shell command in the project's root directory.
- =project-async-shell-command=: run an async shell command in the project's root directory.
- =project-compile=: run the project's compile command from the project's root directory.
- =project-dired=: spawn a =dired= buffer on the project's root directory.
- =project-kill-buffers=: kill all active project buffers.
On the other side, the project management standard package is called Projectile. From its documentation: /Its goal is to 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 sake an indexing mechanism backed by external commands exists as well)/.
For my needs, =project.el= is more than enough, plus it has the advantage to be included in Emacs since the 27.1 version. It is also key to note that =project.el='s API is experimental, and is subject to change in the future. If that's the case, I'll be more than happy to revisit this package and fix the hypothetical problems.
* Installation
** [[https://github.com/raxod502/straight.el][Straight.el]]
Install directly from source (a.k.a this repository) using =straight.el=. The configuration shown here relies on the =use-package= macro, which is a convenient tool to manage package configurations.
#+begin_src emacs-lisp
;; Install from source directly.
(use-package consult-project-extra
:straight (consult-project-extra :type git :host github :repo "Qkessler/consult-project-extra")
:custom (consult-project-function #'consult-project-extra-project-fn) ;; Optional but recommended for a more consistent UI
:bind
(("C-c p f" . consult-project-extra-find)
("C-c p o" . consult-project-extra-find-other-window)))
;; or install from melpa
(use-package consult-project-extra
:straight t
:custom (consult-project-function #'consult-project-extra-project-fn) ;; Optional but recommended for a more consistent UI
:bind
(("C-c p f" . consult-project-extra-find)
("C-c p o" . consult-project-extra-find-other-window)))
#+end_src
** Use-package or package-install
Install with the built-in package-install (though I recommend investing in learning use-package or straight above.
#+begin_src emacs-lisp
;; Make sure you have MELPA as a package source.
(package-refresh-contents)
(package-install 'consult-project-extra)
(require 'consult-project-extra)
#+end_src
Or install using use-package
#+begin_src emacs-lisp
(use-package consult-project-extra
:ensure t
:custom (consult-project-function #'consult-project-extra-project-fn) ;; Optional but recommended for a more consistent UI
:bind
(("C-c p f" . consult-project-extra-find)
("C-c p o" . consult-project-extra-find-other-window)))
#+end_src
** Manually
If you want emacs to load the file when it starts, download the =consult-project-extra.el= file and copy it to the dir "~/.emacs.d/lisp/", (create that directory if it doesn't exist) then put the following in your Emacs configuration file:
#+begin_src emacs-lisp
;; Tell emacs where is your personal elisp lib dir
(add-to-list 'load-path "~/.emacs.d/lisp/")
;; Require consult-project-extra.
(require 'consult-project-extra)
#+end_src
* Credit
- OlMon ([[https://gitlab.com/OlMon/consult-projectile][consult-projectile]]).
- Daniel Mendler ([[https://github.com/minad/consult][consult]]).