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.