]> code.delx.au - gnu-emacs-elpa/blobdiff - README.md
multishell - update features list, remove change log and todo
[gnu-emacs-elpa] / README.md
index 4e005745536e0b76cd1cba0c86dd27e930fc2fa2..08125f12f1e3a4197326664bb72f97cb6c930dd4 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,58 +1,57 @@
-EmacsUtils
-==========
-
-Handy Emacs utilities
-
-I've been using Emacs since it was publicly available (1985 or 1986), and have contributed some items which are included with Emacs, notably the [Allout outliner](http://myriadicity.net/software-and-systems/craft/emacs-allout), [icomplete mode](http://www.emacswiki.org/emacs/IcompleteMode), and python-mode's [pdbtrack functionality](http://myriadicity.net/software-and-systems/craft/crafty-hacks#section-1). Like many long-time Emacs users, I've got some personal custom code, some of which I wouldn't do without. Here's some that I particularly like, and think might be useful to others - I hope to include more, as time allows.
-
-* **[pdbtrack.el](./pdbtrack.el)**
-
-  Add sensitivity to comint shells so the source file lines are automatically
-  presented in a separate window when the Python PDB debugger steps to them.
-
-  This is derived from the pdb tracking code, which I originally wrote, and
-  which has been included in (various) official Emacs Python modes. I wanted
-  a version that I could more easily tweak and maintain, independently of
-  the python-mode code.
-
-  It would eventually be nice to generalize this code, to work for things
-  like the node.js debugger. We'll see if I (or anyone) ever gets around to
-  that.
-
-* **[poptoshell.el](./poptoshell.el)**
-
-  I use the emacs shell a lot. This code enables me to streamline and
-  extend how I can a single one, or multiple ones in a project-oriented
-  fashion:
-
-  * It simplifies getting to the input prompt, by doing the right thing when
-    I hit the key I have bound to pop-to-shell (I use [M-space], ie
-    meta-space:
-  * If the cursor is in a buffer that has no subprocess, pop the window to
-    the primary shell buffer
-  * If there is no shell buffer, start one.
-  * If the cursor is in a buffer which has a process, move the cursor to
-    the process input point.
-  * With a universal argument, even if the current buffer has a subprocess,
-    solicit the name of the target shell buffer - defaulting to the currently
-    chosen primary one - and pop to that.
-    * This enables starting an alternate shell buffer, for instance, and/or
-      switching between the main and alternate ones.
-    * (The expected name is without the surrounding asterisks, and
-      completion is done against existing shell buffer names stripped of
-      their asterisks.)
-  * With a doubled universal arg, prompt for the target shell buffer and
-    use the provided name as the ensuing default. This is how the "primary"
-    is chosen.
-
-  The last few things enable a kind of project-focus mode.  I often have
-  various shell buffers, each one associated with a project. As I switch
-  which project is currently my primary focus, I use the double universal
-  argument to switch which shell buffer is the default. I can still use the
-  single universal argument to easily switch to any of the shells, but most
-  easily to my current primary.
-
-  (This code has grown gradually over many years, and undoubtedly could stand
-  cleaning and clarifying. It works quite reliably, though, and in a choice
-  between spending the time cleaning versus spending the time releasing it, I'm
-  choosing to release.)
+multishell.el
+=============
+
+Facilitate use of multiple local and remote Emacs shell buffers.
+
+Multishell is available via Emacs package manager, in ELPA. Install "multishell" from the `M-x package-list-packages` listing.
+
+I use the emacs shell a *lot*, including separate shells for separate
+project, and more shells for access to remote systems (which I do a lot, as
+a systems administrator). On top of emacs' powerful shell and tramp
+facilities, use a `multishell` (customization-activated) key binding to:
+
+* Get to the input point from wherever you are in a shell buffer,
+  ... or to any of your shell buffers, from anywhere inside emacs.
+
+* Use universal arguments to launch and choose among alternate shell buffers,
+  ... and change which is the current default.
+
+* Easily restart disconnected shells, or shells from prior sessions
+  ... the latter from Emacs builtin savehist minibuf history persistence
+
+* Append a path to a new shell name to launch a shell in that directory,
+  ... and use a path with Emacs tramp syntax to launch a remote shell -
+  for example:
+
+  * `#root/sudo:root@localhost:/etc` for a buffer named "#root" with a
+    root shell starting in /etc.
+
+  * `/ssh:example.net:/` for a shell buffer in / on example.net.
+    The buffer will be named "*example.net*".
+
+  * `#ex/ssh:example.net|sudo:root@example.net:/etc` for a root shell
+    starting in /etc on example.net named "*#ex*".
+
+  * 'interior/ssh:gateway.corp.com|ssh:interior.corp.com:' to go via
+    gateway.corp.com to your homedir on interior.corp.com.  The buffer
+    will be named "*interior*". You could append a sudo hop, and so on.
+
+* Thanks to tramp, file visits from the shell will seamlessly be in
+  the auspices of the target account, and relative to the current
+  directory, on the host where the shell is running.
+
+See the `multishell-pop-to-shell` docstring (in
+[multishell.el](multishell.el)) for details, and
+[getting-to-a-shell.md](getting-to-a-shell.md) for the nitty-gritty
+decision tree that determines where different hits of the keybinding go.
+
+Customize-group `multishell' to select and activate a keybinding and set
+various behaviors. Customize-group `savehist' to preserve buffer
+names/paths across emacs restarts.
+
+Please use
+[the multishell repository](https://github.com/kenmanheimer/EmacsMultishell)
+issue tracker to report problems, suggestions, etc.
+
+See the [multishell.el](multishell.el) file commentary for a change log and
+Todo list.