project-tab-groups.el

Provides a global minor mode that enhances the Emacs built-in project.el library to support keeping projects isolated in named tab groups.

This package automates the steps you’d otherwise need to do manually if you wanted to keep the buffers of a project neatly isolated in separate, named tab groups:

• Switching to another project via project-switch-project (C-x p p) will instead select a tab in the tab group of that project, if it exists. Otherwise, it will create a new, named tab group for the selected project and run the original command there.
• The same goes for any of the project-related commands like finding a file of a project via project-find-file (C-x p f), or finding the project root directory, running an eshell, etc: if a tab group for the selected or current project exists and you’re not in it already, it will switch to it before running the command. Otherwise, it will create a new, named tab group for the selected project and run the command there.
• Closing a project via project-kill-buffers (C-x p k) will close all tabs of the selected or current project’s tab group in addition to closing all its buffers.

Note that by default, Emacs does not display tab groups in the tab bar; please see the note about grouping tabs in C-h v tab-bar-format (link) or Issue #2 for more details.

Customization Options

Finding the name to use for the tab group of a project is customizable via project-tab-groups-tab-group-name-function. The default implementation looks for dir-local variables named tab-group-name or project-name. If none of these are set, it calls the project-name function if it exists (Emacs 29), and falls back to the project’s directory name otherwise.

In addition, if one of tab-group-name-template or project-name-template is present, it is used as the format-string in a call to format to further customize the tab group name. The format-string is expected to have a single %s sequence which will be substituted with the current tab group name. This can be useful if you want to have all projects in a directory share a common prefix, for example.

Finally, project-tab-groups-reconnect-tab controls what to do when project-switch-project selected an existing tab and found its current buffer’s working directory to be outside of the project. It accepts a function which is called with the switched-to project’s root directory as its single argument. Alternatively, a value of t (default) shows the project dispatch menu, and nil does nothing.

Compatibility

This package currently requires Emacs 28 for its native support of tab bar groups.

There’s a backport of tab bar group functionality available for Emacs 27 in the tab-bar-groups package, and making this package work with it should not be too much effort. Please contact me if you’re interested.

Installation

If you use MELPA, an easy way to install this package is via package-install. Alternatively, download project-tab-groups.el, put it in your load-path and require it. Finally, use (project-tab-groups-mode 1) or M-x project-tab-groups to turn on the provided features.

If you use both MELPA and use-package, you can use this, too:

(use-package project-tab-groups
  :ensure
  :config
  (project-tab-groups-mode 1))

If you happen to use the tab-bar-echo-area package, you’ll want to add this to your Emacs initialization file somewhere to display tabs / tab groups after switching projects.

(with-eval-after-load 'tab-bar-echo-area
  (push #'project-switch-project tab-bar-echo-area-trigger-display-functions)
  (tab-bar-echo-area-apply-display-tab-names-advice))

Limitations

• This package does not allow managing tabs / tab groups of projects across multiple frames (C-x 5 p f, etc.) yet.
• If you happen to use both tab-bar and tab-line, you’ll notice that the current buffer remains visible in the tab line after switching to a new project, even though that buffer doesn’t belong to the project. Issue #1 has a discussion of the problem and provides a fix as well.

Related, Supplementary, Alternative Packages

• tab-bar-groups to further customize the appearance of individual tab groups.
• tab-bar-echo-area to temporarily display a list of available tabs and tab groups in the echo area after tab-related commands.
• cascading-dir-locals to allow for setting project-related dir-local variables in addition to more global ones.
• tabspaces, to leverage the Emacs tab bar and the Emacs built-in project.el to create buffer-isolated workspaces that also integrate with version-controlled projects.