Project Shells

Why bother?

This is to manage multiple shell (or terminal, eshell) buffers for each project. For example, to develop for Linux kernel, I usually use one shell buffer to configure and build kernel, one shell buffer to run some git command not supported by magit, one shell buffer to run qemu for built kernel, one shell buffer to ssh into guest system to test. Different set of commands is used by the shell in each buffer, so each shell should have different command history configuration, and for some shell, I may need different setup. And I have several projects to work on. In addition to project specific shell buffers, I want some global shell buffers, so that I can use them whichever project I am working on. Project shells is an Emacs package to let my life easier via helping me to manage all these shell/terminal/eshell buffers.

Install

The preferred install method is through package manager: package.el. project-shells is available in MELPA package repository.

Or you can download the project-shells.el, add its path into emacs load path, and load the file. For example, add

(add-to-list 'load-path "<directory of project-shells.el>")
(require 'project-shells)

in your Emacs init file.

Usage

To enable the project-shells minor mode globally, global-project-shells-mode can be used, or it can enabled in a buffer with project-shells-mode. The default prefix key is “C-c s”, which can be changed via customizing project-shells-keymap-prefix.

The package could also be setup with enabling minor mode via call project-shells-setup, the parameter is the keymap to add project shells key binding. For example, to use project shells with projectile you can put the following forms in your init file,

(project-shells-setup projectile-mode-map)

You can add project-shells key binding in other keymap too, or you can create your own keymap.

After enabling the project-shells minor mode or binding the key, you can create or switch to the shell buffers via,

<prefix key> <shell key>

The default <shell key>s are “1”, “2”, “3”, “4”, “5”, “6”, “7”, “8”, “9”, “0”, “-“, “=”, so you can have 12 shell/terminal/eshell buffers for each project. You can change the number of buffers and keys to activate them via customizing project-shells-keys. By default “1” - “0” will create shell buffers, “-” will create terminal buffers, “=” will create eshell buffers. You can customize which keys to create terminal, eshell buffers via customize the following variables,

project-shells-term-keys
project-shells-eshell-keys
project-shells-vterm-keys

To create or switch to the global shells, you need to use position parameter for the <shell key>. For example,

<prefix key> C-u <shell key>

Use customize-group project-shell to change the configuration.

Work with project management package

You need a project management package enabled, so that project shells knows what the current project is and what the project root directory is. The default configuration works with projectile. To work with other project management package, you need to customize project-shells-project-name-func and project-shells-project-root-func.

Shell configuration

In the default configuration, each shell program and eshell runs by project-shells will has own history file. The default history file name is “~/.sessions/<project name>/<key>/.shell_history”. The default configuration works for bash, to support other shell, the project-shells-histfile-env may need to be customized.

If some special shell configuration is needed, the shell initialize file could be added into the session directory, the default initialize file name is “~/.sessions/<project name>/<key>/.shellrc”. The default configuration works for bash, to support other shell, the project-shells-default-init-func may need to be customized.

SSH

The shell buffer could be a remote shell buffer, that is, a ssh session accessing a remote machine. To make a shell buffer remote, use something like /ssh:<user>@<host>:<dir> as the default directory when configure shell buffers via project-shells-setup. Or you can use ask (symbol ask) as default directory, and you will be prompted for destination user@host.

The ssh support code is based on Ian Eure’s nssh. Thanks Ian!

Example configuration

One of the most important configuration for project-shells is project-shells-setup. It could be set via customizing or setting in Emacs lisp directly. The following is the example for the Linux kernel development described at the begin of the document.

(setf project-shells-setup
 `(("linux" .
    (("0" .
      ("build" "~/projects/linux/obj"))
     ("9" .
      ("qemu" "~/projects/linux/qemu"))
     ("8" .
      ("guest" "/ssh:root@qemu:"))
     ("1" .
      ("git"))))))

Where 4 shell buffers are configured for project “linux”, they can be activated via key “0”, “9”, “8”, and “1”. The name in configuration reflects the intended usage. Different initial directory is specified for “0”, and “9”, because that is more convenient for the corresponding intended usage, for example, there may be some qemu scripts in ~/projects/linux/qemu. “8” is a ssh shell buffer, which is used to ssh into the testing guest system running in qemu. The usage is quite simple, just start the qemu in “9”, then when you activate “8”, ssh will be run in the buffer.