project-shells

project-shells copied to clipboard

• 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 [[http://melpa.org/][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

#+BEGIN_SRC emacs-lisp (add-to-list 'load-path "") (require 'project-shells) #+END_SRC

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,

#+BEGIN_SRC emacs-lisp (project-shells-setup projectile-mode-map) #+END_SRC

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,

The default 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,

#+BEGIN_SRC emacs-lisp project-shells-term-keys project-shells-eshell-keys project-shells-vterm-keys #+END_SRC

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

C-u

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///.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///.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:@:

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.

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

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.