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