1 ;;; multishell.el --- facilitate multiple local and remote shell buffers
3 ;; Copyright (C) 1999-2016 Free Software Foundation, Inc. and Ken Manheimer
5 ;; Author: Ken Manheimer <ken.manheimer@gmail.com>
7 ;; Created: 1999 -- first public availability
9 ;; URL: https://github.com/kenmanheimer/EmacsMultishell
13 ;; Easily use and navigate multiple shell buffers, including remote shells.
14 ;; Fundamentally, multishell is the function `multishell-pop-to-shell' -
15 ;; a la `pop-to-buffer' - plus a keybinding. Together, they enable you to:
17 ;; * Get to the input point from wherever you are in a shell buffer,
18 ;; ... or to any of your shell buffers, from anywhere inside emacs.
20 ;; * Use universal arguments to launch and choose among alternate shell buffers,
21 ;; ... and change which is the current default.
23 ;; * Easily restart disconnected shells, or shells from prior sessions
24 ;; ... the latter from Emacs builtin savehist minibuf history persistence
26 ;; * Append a path to a new shell name to launch a shell in that directory,
27 ;; ... and use a path with Emacs tramp syntax to launch a remote shell -
30 ;; * `#root/sudo:root@localhost:/etc` for a buffer named "#root" with a
31 ;; root shell starting in /etc.
33 ;; * `/ssh:example.net:/` for a shell buffer in / on example.net.
34 ;; The buffer will be named "*example.net*".
36 ;; * `#ex/ssh:example.net|sudo:root@example.net:/etc` for a root shell
37 ;; starting in /etc on example.net named "*#ex*".
39 ;; * 'interior/ssh:gateway.corp.com|ssh:interior.corp.com:' to go via
40 ;; gateway.corp.com to your homedir on interior.corp.com. The buffer
41 ;; will be named "*interior*". You could append a sudo hop, and so on.
43 ;; * Thanks to tramp, file visits from the shell will seamlessly be in
44 ;; the auspices of the target account, and relative to the current
45 ;; directory, on the host where the shell is running.
47 ;; See the `multishell-pop-to-shell` docstring for details.
49 ;; Customize-group `multishell' to select and activate a keybinding and set
50 ;; various behaviors. Customize-group `savehist' to preserve buffer
51 ;; names/paths across emacs restarts.
54 ;; [the multishell repository](https://github.com/kenmanheimer/EmacsMultishell)
55 ;; issue tracker to report problems, suggestions, etc.
57 ;; (NOTE - tramp sometimes fails to open a remote shell when pointed at a
58 ;; homedir, eg `/ssh:example.net:` or `/ssh:example.net:~`. Once it fails
59 ;; for a shell path, that path won't work for the rest of the
60 ;; session. Non-homedir remote access isn't disrupted. You can always work
61 ;; around this by switching to an explicit, non-homedir remote path when
62 ;; the problem occurs, and then cd'ing to wherever, including your homedir,
63 ;; in the remote shell.)
67 ;; * 2016-01-22 1.0.6 Ken Manheimer:
68 ;; - Add multishell-version function.
69 ;; - Tweak commentary/comments/docstrings.
70 ;; - Null old multishell-buffer-name-history var, if present.
71 ;; * 2016-01-16 1.0.5 Ken Manheimer:
72 ;; - History now includes paths, when designated.
73 ;; - Actively track current directory in history entries that have a path.
74 ;; Custom control: multishell-history-entry-tracks-current-directory
75 ;; - Offer to remove shell's history entry when buffer is killed.
76 ;; (Currently the only UI mechanism to remove history entries.)
77 ;; - Fix - prevent duplicate entries for same name but different paths
78 ;; - Fix - recognize and respect tramp path syntax to start in home dir
79 ;; - But tramp bug, remote w/empty path (homedir) often fails, gets wedged.
80 ;; - Simplify history var name, migrate existing history if any from old name
81 ;; * 2016-01-04 1.0.4 Ken Manheimer - Released to ELPA
82 ;; * 2016-01-02 Ken Manheimer - working on this in public, but not yet released.
86 ;; * Isolate tramp's sporadic failure to connect to remote+homedir (empty path)
88 ;; (eg, /ssh:xyz.com|sudo:root@xyz.com: or /ssh:xyz.com|sudo:root@xyz.com:~)
89 ;; * Find suitable, internally consistent ways to tidy completions, eg:
90 ;; - first list completions for active shells, then present but inactive,
92 ;; - some way for user to toggle between presenting just buffer names vs
94 ;; - without cutting user off from easy editing of path
95 ;; * Try minibuffer field boundary at beginning of tramp path, to see whether
96 ;; the field boundary magically enables tramp path completion.
97 ;; * Assess whether deletion of history entry via kill-buffer is sufficient.
105 (defvar multishell-version "1.0.6")
106 (defun multishell-version (&optional here)
107 "Return string describing the loaded multishell version."
109 (let ((msg (concat "Multishell " multishell-version)))
110 (if here (insert msg)
111 (if (called-interactively-p 'interactive)
115 (defgroup multishell nil
116 "Allout extension that highlights outline structure graphically.
118 Customize `allout-widgets-auto-activation' to activate allout-widgets
122 (defcustom multishell-command-key "\M- "
123 "The key to use if `multishell-activate-command-key' is true.
125 You can instead manually bind `multishell-pop-to-shell` using emacs
126 lisp, eg: (global-set-key \"\\M- \" 'multishell-pop-to-shell)."
130 (defvar multishell--responsible-for-command-key nil
131 "Coordination for multishell key assignment.")
132 (defun multishell-activate-command-key-setter (symbol setting)
133 "Implement `multishell-activate-command-key' choice."
134 (set-default 'multishell-activate-command-key setting)
135 (when (or setting multishell--responsible-for-command-key)
136 (multishell-implement-command-key-choice (not setting))))
137 (defun multishell-implement-command-key-choice (&optional unbind)
138 "If settings dicate, implement binding of multishell command key.
140 If optional UNBIND is true, globally unbind the key.
142 * `multishell-activate-command-key' - Set this to get the binding or not.
143 * `multishell-command-key' - The key to use for the binding, if appropriate."
145 (when (and (boundp 'multishell-command-key) multishell-command-key)
146 (global-unset-key multishell-command-key)))
147 ((not (and (boundp 'multishell-activate-command-key)
148 (boundp 'multishell-command-key)))
150 ((and multishell-activate-command-key multishell-command-key)
151 (setq multishell--responsible-for-command-key t)
152 (global-set-key multishell-command-key 'multishell-pop-to-shell))))
154 (defcustom multishell-activate-command-key nil
155 "Set this to impose the `multishell-command-key' binding.
157 You can instead manually bind `multishell-pop-to-shell` using emacs
158 lisp, eg: (global-set-key \"\\M- \" 'multishell-pop-to-shell)."
160 :set 'multishell-activate-command-key-setter
163 ;; Implement the key customization whenever the package is loaded:
164 (with-eval-after-load "multishell"
165 (multishell-implement-command-key-choice))
167 (defcustom multishell-pop-to-frame nil
168 "*If non-nil, jump to a frame already showing the shell, if another one is.
170 Otherwise, disregard already-open windows on the shell if they're
171 in another frame, and open a new window on the shell in the
174 \(Use `pop-up-windows' to change multishell other-window vs
175 current-window behavior.)"
179 (defcustom multishell-history-entry-tracks-current-directory t
180 "Maintain shell's current directory in its multishell history entry.
182 When set, the history entry for shells started with explicit
183 paths will track the shell's current working directory. (Explicit
184 paths will not be added to local shells started without one,
187 If `savehist-save-minibuffer-history' is enabled, the current
188 working directory of shells \(that were started with an explicit
189 path) will be conveyed between emacs sessions."
193 (defvar multishell-history nil
194 "Name/path entries, most recent first.")
195 ;; Migrate the few pre 1.0.5 users to changed history var:
196 (when (and (not multishell-history)
197 (boundp 'multishell-buffer-name-history)
198 multishell-buffer-name-history)
199 (setq multishell-history multishell-buffer-name-history
200 multishell-buffer-name-history nil))
202 (defvar multishell-primary-name "*shell*"
203 "Default shell name for un-modified multishell-pop-to-shell buffer target.
205 This is adjusted by `multishell-pop-to-shell' when it is
206 invoked (with doubled universal argument) to set the default.
208 To preserve changes to this setting across emacs restarts, add it
209 to `savehist-additional-variables' by customizing the latter.")
211 ;;; Can't just add multishell-primary-name to savehist-additional-variables
212 ;;; - it'll be lost any time the user runs emacs without loading
213 ;;; multishell. So instead, inform the user that they can customize
214 ;;; savehist-additional-variables.
216 ;;; I suspect that including savehist-additional-variables *on*
217 ;;; savehist-additional-variables could avoid this problem, as long as it
218 ;;; doesn't conflict with user customizations. However, even if that works,
219 ;;; doing so from multishell would change a behavior (for the better, but)
220 ;;; beyond multishell's scope, making the change hard to track down.
222 ;; (when (not (member 'multishell-primary-name
223 ;; savehist-additional-variables))
224 ;; (setq savehist-additional-variables
225 ;; (cons 'multishell-primary-name savehist-additional-variables)))
227 ;; Multiple entries happen because completion also adds name to history.
228 (defun multishell-register-name-to-path (name path)
229 "Add or replace entry associating NAME with PATH in `multishell-history'.
231 If NAME already had a PATH and new PATH is empty, retain the prior one.
233 Promote added/changed entry to the front of the list."
234 ;; Add or promote to the front, tracking path changes in the process.
235 (let* ((entries (multishell-history-entries name))
237 (dolist (entry entries)
238 (when (string= path "")
239 ;; Retain explicit established path.
240 (setq path (cadr (multishell-split-entry entry))))
241 (setq multishell-history (delete entry multishell-history)))
242 (setq multishell-history (push (concat name path)
243 multishell-history))))
245 (defun multishell-history-entries (name)
246 "Return `multishell-history' entry that starts with NAME, or nil if none."
247 (let ((match-expr (concat "^" name "\\\(/.*$\\\)?$"))
249 (dolist (entry multishell-history)
250 (when (and (string-match match-expr entry)
251 (not (member entry got)))
252 (setq got (cons entry got))))
255 (defun multishell-pop-to-shell (&optional arg)
256 "Easily navigate to and within multiple shell buffers, local and remote.
258 Use universal arguments to launch and choose between alternate
259 shell buffers and to select which is default. Append a path to
260 a new shell name to launch a shell in that directory, and use
261 Emacs tramp syntax to launch a remote shell.
263 Customize-group `multishell' to set up a key binding and tweak behaviors.
265 ==== Basic operation:
267 - If the current buffer is shell-mode (or shell-mode derived)
268 buffer then focus is moved to the process input point.
270 \(You can use a universal argument go to a different shell
271 buffer when already in a buffer that has a process - see
274 - If not in a shell buffer (or with universal argument), go to a
275 window that is already showing the (a) shell buffer, if any.
277 In this case, the cursor is left in its prior position in the
278 shell buffer. Repeating the command will then go to the
279 process input point, per the first item in this list.
281 We respect `pop-up-windows', so you can adjust it to set the
282 other-buffer/same-buffer behavior.
284 - Otherwise, start a new shell buffer, using the current
285 directory as the working directory.
287 If a buffer with the resulting name exists and its shell process
288 was disconnected or otherwise stopped, it's resumed.
290 ===== Universal arg to start and select between named shell buffers:
292 You can name alternate shell buffers to create or return to using
293 single or doubled universal arguments:
295 - With a single universal argument, prompt for the buffer name
296 to use (without the asterisks that shell mode will put around
297 the name), defaulting to 'shell'.
299 Completion is available.
301 This combination makes it easy to start and switch across
302 multiple shell restarts.
304 - A double universal argument will prompt for the name *and* set
305 the default to that name, so the target shell becomes the
308 See `multishell-primary-name' for info about preserving the
309 setting across emacs restarts.
311 ===== Select starting directory and remote host:
313 The shell buffer name you give to the prompt for a universal arg
314 can include an appended path. That will be used for the startup
315 directory. You can use tramp remote syntax to specify a remote
316 shell. If there is an element after a final '/', that's used for
317 the buffer name. Otherwise, the host, domain, or path is used.
321 * '#root/sudo:root@localhost:/etc' for a buffer named \"#root\" with a
322 root shell starting in /etc.
324 * '/ssh:example.net:/' for a shell buffer in / on example.net; the buffer
325 will be named \"*example.net*\".
327 * '#ex/ssh:example.net|sudo:root@example.net:/etc' for a root shell
328 starting in /etc on example.net named \"*#ex*\".
330 * 'interior/ssh:gateway.corp.com|ssh:interior.corp.com:' to go
331 via gateway.corp.com to your homedir on interior.corp.com. The
332 buffer will be named \"*interior*\". You could append a sudo
333 hop to the path, combining the previous example, and so on.
335 Thanks to tramp, file visits from the shell, and many common
336 emacs activities, like dired, will seamlessly be in the auspices
337 of the target account, and relative to the current directory, on
338 the host where the shell is running.
340 \(NOTE that there is a problem with specifying a remote homedir
341 using tramp syntax, eg '/ssh:example.net:'. That sometimes fails
342 on an obscure bug. Once it fails for a shell path, that path
343 won't work for the rest of the session. You can always work
344 around this by switching to an explicit, non-homedir remote path
345 when the problem occurs, and then cd'ing to wherever, including
346 your homedir, in the remote shell. Non-homedir initial paths
349 You can change the startup path for a shell buffer by editing it
350 at the completion prompt. The new path will be preserved in
351 history but will not take effect for an already-running shell.
353 To remove a shell buffer's history entry, kill the buffer and
354 affirm removal of the entry when prompted.
356 ===== Activate savehist to retain shell buffer names and paths across Emacs restarts:
358 To have emacs maintain your history of shell buffer names and paths,
359 customize the savehist group to activate savehist."
363 (let* ((from-buffer (current-buffer))
364 (from-buffer-is-shell (derived-mode-p 'shell-mode))
365 (doublearg (equal arg '(16)))
366 (target-name-and-path (multishell-resolve-target-name-and-path
368 (multishell-read-bare-shell-buffer-name
369 (format "Shell buffer name [%s]%s "
370 (substring-no-properties
371 multishell-primary-name
372 1 (- (length multishell-primary-name) 1))
373 (if doublearg " <==" ":"))
374 (multishell-unbracket-asterisks multishell-primary-name))
375 (multishell-unbracket-asterisks multishell-primary-name))))
376 (use-default-dir (cadr target-name-and-path))
377 (target-shell-buffer-name (car target-name-and-path))
378 (curr-buff-proc (get-buffer-process from-buffer))
379 (target-buffer (if from-buffer-is-shell
381 (get-buffer target-shell-buffer-name)))
385 ;; Register early so the entry is pushed to the front:
386 (multishell-register-name-to-path (multishell-unbracket-asterisks
387 target-shell-buffer-name)
391 (setq multishell-primary-name target-shell-buffer-name))
397 ((and (or curr-buff-proc from-buffer-is-shell)
399 (eq from-buffer target-buffer)
400 (not (eq target-shell-buffer-name (buffer-name from-buffer))))
401 ;; In a shell buffer, but not named - stay in buffer, but go to end.
402 (setq already-there t))
404 ((string= (buffer-name) target-shell-buffer-name)
405 ;; Already in the specified shell buffer:
406 (setq already-there t))
408 ((or (not target-buffer)
410 (multishell-get-visible-window-for-buffer target-buffer))))
411 ;; No preexisting shell buffer, or not in a visible window:
412 (pop-to-buffer target-shell-buffer-name pop-up-windows))
414 ;; Buffer exists and already has a window - jump to it:
415 (t (if (and multishell-pop-to-frame
417 (not (equal (window-frame (selected-window))
418 (window-frame inwin))))
419 (select-frame-set-input-focus (window-frame inwin)))
420 (if (not (string= (buffer-name (current-buffer))
421 target-shell-buffer-name))
422 (pop-to-buffer target-shell-buffer-name t))))
424 ;; We're in the buffer. Activate:
426 (if (not (comint-check-proc (current-buffer)))
427 (multishell-start-shell-in-buffer (buffer-name (current-buffer))
430 ;; If the destination buffer has a stopped process, resume it:
431 (let ((process (get-buffer-process (current-buffer))))
432 (if (and process (equal 'stop (process-status process)))
433 (continue-process process)))
435 (when (or already-there
436 (equal (current-buffer) from-buffer))
437 (goto-char (point-max))
438 (and (get-buffer-process from-buffer)
439 (goto-char (process-mark (get-buffer-process from-buffer)))))))
441 (defun multishell-kill-buffer-query-function ()
442 "Offer to remove multishell-history entry for buffer."
443 ;; Removal choice is crucial, so users can, eg, kill a shell with huge
444 ;; output backlog, while keeping the history entry to easily restart it.
446 ;; We use kill-buffer-query-functions instead of kill-buffer-hook because:
448 ;; 1. It enables the user to remove the history without actually killing a
449 ;; running buffer, by not confirming the subsequent running-proc query.
450 ;; 2. kill-buffer-hooks often fails to run when killing shell buffers!
451 ;; It's probably due to failures in other hooks - beyond our control -
452 ;; and anyway, I like the first reason well enough.
454 ;; (Use condition-case to avoid inadvertant disruption of kill-buffer
455 ;; activity. kill-buffer happens behind the scenes a whole lot.)
457 (dolist (entry (and (derived-mode-p 'shell-mode)
458 (multishell-history-entries
459 (multishell-unbracket-asterisks (buffer-name)))))
461 (y-or-n-p (format "Remove multishell history entry `%s'? "
463 (setq multishell-history
464 (delete entry multishell-history))))
466 (message "multishell-kill-buffer-query-function error: %s" err)))
468 (add-hook 'kill-buffer-query-functions 'multishell-kill-buffer-query-function)
470 (defun multishell-get-visible-window-for-buffer (buffer)
471 "Return visible window containing buffer."
474 (function (lambda (win)
475 (if (and (eq (window-buffer win) buffer)
476 (equal (frame-parameter
477 (selected-frame) 'display)
479 (window-frame win) 'display)))
480 (throw 'got-a-vis win))))
484 (defun multishell-read-bare-shell-buffer-name (prompt default)
485 "PROMPT for shell buffer name, sans asterisks.
487 Return the supplied name not bracketed with the asterisks, or specified
488 DEFAULT on empty input."
491 ;; Plain shell buffer names appended with names from name/path hist:
493 (mapcar (lambda (buffer)
494 (let* ((name (multishell-unbracket-asterisks
495 (buffer-name buffer))))
496 (and (buffer-live-p buffer)
497 (with-current-buffer buffer
498 ;; Shell mode buffers.
499 (derived-mode-p 'shell-mode))
500 (not (multishell-history-entries name))
504 (got (completing-read prompt
514 'multishell-history)))
515 (if (not (string= got ""))
519 (defun multishell-resolve-target-name-and-path (path-ish)
520 "Given name/tramp-path PATH-ISH, resolve buffer name and initial directory.
522 The name is the part of the string up to the first '/' slash, if
523 any. Missing pieces are filled in from remote path elements, if
524 any, and multishell history. Given a path and no name, either the
525 host-name, domain-name, final directory name, or local host name
528 Return them as a list (name path), with name asterisk-bracketed
529 and path nil if none resolved."
530 (let* ((splat (multishell-split-entry path-ish))
536 (if (file-remote-p path)
537 (let ((vec (tramp-dissect-file-name path)))
538 (or (tramp-file-name-host vec)
539 (tramp-file-name-domain vec)
540 (tramp-file-name-localname vec)
542 multishell-primary-name)))
543 ;; No path - get one from history, if present.
545 (setq name multishell-primary-name))
546 (mapcar #'(lambda (entry)
547 (when (or (not path) (string= path ""))
548 (setq path (cadr (multishell-split-entry entry)))))
549 (multishell-history-entries
550 (multishell-unbracket-asterisks name))))
551 (list (multishell-bracket-asterisks name) path)))
553 (defun multishell-bracket-asterisks (name)
554 "Return a copy of name, ensuring it has an asterisk at the beginning and end."
555 (if (not (string= (substring name 0 1) "*"))
556 (setq name (concat "*" name)))
557 (if (not (string= (substring name -1) "*"))
558 (setq name (concat name "*")))
560 (defun multishell-unbracket-asterisks (name)
561 "Return a copy of name, removing asterisks, if any, at beginning and end."
562 (if (string= (substring name 0 1) "*")
563 (setq name (substring name 1)))
564 (if (string= (substring name -1) "*")
565 (setq name (substring name 0 -1)))
568 (defun multishell-start-shell-in-buffer (buffer-name path)
569 "Ensure a shell is started, with name NAME and PATH."
570 ;; We work around shell-mode's bracketing of the buffer name, and do
571 ;; some tramp-mode hygiene for remote connections.
573 (let* ((buffer buffer-name)
574 (prog (or explicit-shell-file-name
578 (name (file-name-nondirectory prog))
579 (startfile (concat "~/.emacs_" name))
580 (xargs-name (intern-soft (concat "explicit-" name "-args")))
582 (set-buffer buffer-name)
583 (if (and path (not (string= path "")))
584 (setq default-directory path))
585 (setq is-remote (file-remote-p default-directory))
587 (derived-mode-p 'shell-mode)
588 (not (comint-check-proc (current-buffer))))
589 ;; We're returning to an already established but disconnected remote
591 (tramp-cleanup-connection
592 (tramp-dissect-file-name default-directory 'noexpand)
593 'keep-debug 'keep-password))
594 ;; (cd default-directory) will connect if remote:
596 (message "Connecting to %s" default-directory))
598 (cd default-directory)
600 ;; Aargh. Need to isolate this tramp bug.
601 (if (and (stringp (cadr err))
602 (string-equal (cadr err)
603 "Selecting deleted buffer"))
606 (format "%s, %s (\"%s\")"
607 "Tramp shell can fail on empty (homedir) path"
608 "please try again with an explicit path"
610 (signal (car err)(cdr err)))))
611 (setq buffer (set-buffer (apply 'make-comint
612 (multishell-unbracket-asterisks buffer-name)
614 (if (file-exists-p startfile)
618 (symbol-value xargs-name)
622 (defun multishell-track-dirchange (name newpath)
623 "Change multishell history entry to track current directory."
624 (let* ((entries (multishell-history-entries name)))
625 (dolist (entry entries)
626 (let* ((name-path (multishell-split-entry entry))
627 (name (car name-path))
628 (path (cadr name-path)))
630 (let* ((is-remote (file-remote-p path))
631 (vec (and is-remote (tramp-dissect-file-name path nil)))
632 (localname (if is-remote
633 (tramp-file-name-localname vec)
636 (replace-regexp-in-string (if (string= localname "")
638 (regexp-quote localname))
648 (newpath (if is-remote
649 (tramp-make-tramp-file-name (aref vec 0)
655 (newentry (concat name newpath))
656 (membership (member entry multishell-history)))
658 (setcar membership newentry))))))))
659 (defvar multishell-was-default-directory ()
660 "Provide for tracking directory changes.")
661 (make-variable-buffer-local 'multishell-was-default-directory)
662 (defun multishell-post-command-business ()
663 "Do multishell bookkeeping."
664 ;; Update multishell-history with dir changes.
666 (when (and multishell-history-entry-tracks-current-directory
667 (derived-mode-p 'shell-mode))
668 (let ((curdir (if (file-remote-p default-directory)
669 (tramp-file-name-localname
670 (tramp-dissect-file-name default-directory))
672 (when (and multishell-was-default-directory
673 (not (string= curdir multishell-was-default-directory)))
674 (multishell-track-dirchange (multishell-unbracket-asterisks
677 (setq multishell-was-default-directory curdir)))
678 ;; To avoid disruption as a pervasive hook function, swallow all errors:
680 (message "multishell-post-command-business error: %s" err))))
681 (add-hook 'post-command-hook 'multishell-post-command-business)
683 (defun multishell-split-entry (entry)
684 "Given multishell name/path ENTRY, return the separated name and path pair.
686 Returns nil for empty parts, rather than the empty string."
687 (string-match "^\\([^/]*\\)\\(/?.*\\)?" entry)
688 (let ((name (match-string 1 entry))
689 (path (match-string 2 entry)))
690 (and (string= name "") (setq name nil))
691 (and (string= path "") (setq path nil))
694 (provide 'multishell)
696 ;;; multishell.el ends here