/ README.org
README.org
1 #+title: Eat: Emulate A Terminal 2 3 💡 *This fork of Emacs EAT has the following PRs merged from upstream:* 4 5 - [[/commits/946ad0c1d1b315ef5242ac045140e988c8fa47d4][Fish integration #133]] 6 - [[/commits/cd0668c11dbbbb2299d1452a9ed519fec5930934][* eat.el (eat--1): Make returned buffer current #193]] 7 - [[/commits/088de506dae440ccc98cfd9c994ed272b31a562d][feat: Add buffer renaming based on terminal title #246]] 8 9 Eat's name is self-explanatory, it stands for "Emulate A Terminal". Eat 10 is a terminal emulator. It can run most (if not all) full-screen 11 terminal programs, including Emacs. 12 13 It is pretty fast, more than three times faster than Term, despite 14 being implemented entirely in Emacs Lisp. So fast that you can 15 comfortably run Emacs inside Eat, or even use your Emacs as a terminal 16 multiplexer. 17 18 It has many features that other Emacs terminal emulator still don't 19 have, for example Sixel support, complete mouse support, shell 20 integration, etc. 21 22 It flickers less than other Emacs terminal emulator, so you get more 23 performance and a smoother experience. 24 25 To get the most out of Eat, you should also setup shell integration. 26 27 * Usage 28 29 To start Eat, run =M-x eat=. Eat has four input modes: 30 31 - "semi-char" mode: This is the default input mode. Most keys are 32 bound to send the key to the terminal, except the following keys: 33 =C-\=, =C-c=, =C-x=, =C-g=, =C-h=, =C-M-c=, =C-u=, =C-q=, =M-x=, 34 =M-:=, =M-!=, =M-&= and some other keys (see the user option 35 ~eat-semi-char-non-bound-keys~ for the complete list). The 36 following special keybinding are available: 37 38 - =C-q=: Send next key to the terminal. 39 - =C-y=: Like `yank', but send the text to the terminal. 40 - =M-y=: Like `yank-pop', but send the text to the terminal. 41 - =C-c C-k=: Kill process. 42 - =C-c C-e=: Switch to "emacs" input mode. 43 - =C-c M-d=: Switch to "char" input mode. 44 - =C-c C-l=: Switch to "line" input mode. 45 46 - "emacs" mode: No special keybinding, except the following: 47 48 - =C-c C-j=: Switch to "semi-char" input mode. 49 - =C-c M-d=: Switch to "char" input mode. 50 - =C-c C-l=: Switch to "line" input mode. 51 - =C-c C-k=: Kill process. 52 53 - "char" mode: All supported keys are bound to send the key to the 54 terminal, except =C-M-m= or =M-RET=, which is bound to switch to 55 "semi-char" input mode. 56 57 - "line" mode: Similar to Comint, Shell mode and Term line mode. In 58 this input mode, terminal input is sent one line at once, and you 59 can edit input line using the usual Emacs commands. 60 61 - =C-c C-e=: Switch to "emacs" input mode 62 - =C-c C-j=: Switch to "semi-char" input mode. 63 - =C-c M-d=: Switch to "char" input mode. 64 65 If you like Eshell, then there is a good news for you. Eat integrates 66 with Eshell. Eat has two global minor modes for Eshell: 67 68 - ~eat-eshell-visual-command-mode~: Run visual commands with Eat 69 instead of Term. 70 71 - ~eat-eshell-mode~: Run Eat inside Eshell. After enabling this, you 72 can run full-screen terminal programs directly in Eshell. You have 73 the above input modes here too, except line mode and that =C-c C-k= 74 is not special (i.e. not bound by Eat) in "emacs" mode and "line" 75 mode. 76 77 You can add any of these to ~eshell-load-hook~ like the following: 78 79 #+begin_src emacs-lisp 80 ;; For `eat-eshell-mode'. 81 (add-hook 'eshell-load-hook #'eat-eshell-mode) 82 83 ;; For `eat-eshell-visual-command-mode'. 84 (add-hook 'eshell-load-hook #'eat-eshell-visual-command-mode) 85 #+end_src 86 87 To setup shell integration for GNU Bash, put the following at the end 88 of your ~.bashrc~: 89 90 #+begin_src sh 91 [ -n "$EAT_SHELL_INTEGRATION_DIR" ] && \ 92 source "$EAT_SHELL_INTEGRATION_DIR/bash" 93 #+end_src sh 94 95 For Zsh, put the following in your ~.zshrc~: 96 97 #+begin_src sh 98 [ -n "$EAT_SHELL_INTEGRATION_DIR" ] && \ 99 source "$EAT_SHELL_INTEGRATION_DIR/zsh" 100 #+end_src sh 101 102 There's a Info manual available with much more information, which can 103 be accessed with =C-h i m Eat=, also available [[https://elpa.nongnu.org/nongnu-devel/doc/eat.html][here on the internet]]. 104 105 * Installation 106 107 Eat requires at least Emacs 26.1 or above. 108 109 ** NonGNU ELPA 110 111 Eat is available on NonGNU ELPA. So you can just do 112 =M-x package-install RET eat RET=. 113 114 If you're on Emacs 27 or earlier, you'll need to add NonGNU ELPA to 115 your ~package-archives~ by putting the following in your ~init.el~: 116 117 #+begin_src emacs-lisp 118 (add-to-list 'package-archives 119 '("nongnu" . "https://elpa.nongnu.org/nongnu/")) 120 #+end_src 121 122 ** Quelpa 123 124 #+begin_src emacs-lisp 125 (quelpa '(eat :fetcher git 126 :url "https://codeberg.org/akib/emacs-eat" 127 :files ("*.el" ("term" "term/*.el") "*.texi" 128 "*.ti" ("terminfo/e" "terminfo/e/*") 129 ("terminfo/65" "terminfo/65/*") 130 ("integration" "integration/*") 131 (:exclude ".dir-locals.el" "*-tests.el")))) 132 #+end_src 133 134 ** Straight.el 135 136 #+begin_src emacs-lisp 137 (straight-use-package 138 '(eat :type git 139 :host codeberg 140 :repo "akib/emacs-eat" 141 :files ("*.el" ("term" "term/*.el") "*.texi" 142 "*.ti" ("terminfo/e" "terminfo/e/*") 143 ("terminfo/65" "terminfo/65/*") 144 ("integration" "integration/*") 145 (:exclude ".dir-locals.el" "*-tests.el")))) 146 #+end_src 147 148 ** Manual 149 150 Clone the repository and put it in your ~load-path~. 151 152 * Comparison With Other Terminal Emulators 153 154 ** Term 155 156 Term is the Emacs built-in terminal emulator. Its terminal emulation 157 is pretty good too. But it's slow. It is so slow that Eat can beat 158 native-compiled Term even without byte-compilation, and when Eat is 159 byte-compiled, Eat is more than three times fast. Also, Term 160 flickers, just try to run =emacs -nw= in it. It doesn't support 161 remote connections, for example over Tramp. However, it's builtin 162 from the early days of Emacs, while Eat needs atleast Emacs 26.1. 163 164 ** Vterm 165 166 Vterm is powered by a C library, libvterm. For this reason, it can 167 process huge amount of text quickly. It is about 1.5 times faster 168 than Eat (byte-compiled or native-compiled) (and about 2.75 faster 169 then Eat without byte-compilation). But it doesn't have a char mode 170 (however you can make a char mode by putting some effort). And it too 171 flickers like Term, so despite being much faster that Eat, it seems to 172 be slow. If you need your terminal to handle huge bursts (megabytes) 173 of data, you should use Vterm. 174 175 ** Coterm + Shell 176 177 Coterm adds terminal emulation to Shell mode. Although the terminal 178 Coterm emulates is same as Term, it is much faster, about three times, 179 just a bit slow than Eat. However, it too flickers like other 180 terminals. Since it's an upgrade to Shell, you get all the features 181 of Shell like "line" mode, completion using your favorite completion 182 UI (Company, Corfu, etc), etc. Most of these features are available 183 in Eat, and also in Eat-Eshell-Mode as Eshell is similar to Shell, 184 however it's not Shell mode. Recommended if you like Shell. 185 186 * Acknowledgements 187 188 This wouldn't have been possible if the following awesome softwares 189 didn't exist: 190 191 - [[https://gnu.org][GNU Operating System]] 192 - [[https://st.suckless.org/][St]] 193 - [[https://sw.kovidgoyal.net/kitty/][Kitty]] 194 - [[https://invisible-island.net/xterm/][XTerm]] 195 - [[https://www.gnu.org/software/linux-libre/][Linux-libre]] 196 - [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Terminal-emulator.html][Term]] 197 - [[https://repo.or.cz/emacs-coterm.git][Coterm]] 198 - [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Interactive-Shell.html][Shell]] 199 - [[https://github.com/akermu/emacs-libvterm][Vterm]] 200 - [[https://www.gnu.org/software/emacs/manual/html_node/eshell/index.html][Eshell]] 201 - Numerous terminal programs 202 - And obviously, [[https://www.gnu.org/software/emacs/][GNU Emacs]]