{"id":13440192,"url":"https://github.com/akermu/emacs-libvterm","last_synced_at":"2025-04-11T20:59:40.542Z","repository":{"id":38206457,"uuid":"99721074","full_name":"akermu/emacs-libvterm","owner":"akermu","description":"Emacs libvterm integration","archived":false,"fork":false,"pushed_at":"2025-01-13T16:45:31.000Z","size":803,"stargazers_count":1771,"open_issues_count":196,"forks_count":141,"subscribers_count":32,"default_branch":"master","last_synced_at":"2025-04-11T20:59:35.160Z","etag":null,"topics":["emacs","libvterm","terminal","terminal-emulator"],"latest_commit_sha":null,"homepage":"","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akermu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-08T17:51:40.000Z","updated_at":"2025-04-08T15:48:16.000Z","dependencies_parsed_at":"2024-05-20T03:32:40.089Z","dependency_job_id":"581222b6-eaa9-403d-98b6-6b7b7ef1d241","html_url":"https://github.com/akermu/emacs-libvterm","commit_stats":{"total_commits":543,"total_committers":85,"mean_commits":"6.3882352941176475","dds":0.6998158379373849,"last_synced_commit":"99c1f5e76ac927825775c887c93e46036fac7327"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akermu%2Femacs-libvterm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akermu%2Femacs-libvterm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akermu%2Femacs-libvterm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akermu%2Femacs-libvterm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akermu","download_url":"https://codeload.github.com/akermu/emacs-libvterm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248480436,"owners_count":21110936,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["emacs","libvterm","terminal","terminal-emulator"],"created_at":"2024-07-31T03:01:20.567Z","updated_at":"2025-04-11T20:59:40.383Z","avatar_url":"https://github.com/akermu.png","language":"Emacs Lisp","funding_links":[],"categories":["C","Emacs Lisp"],"sub_categories":[],"readme":"[![MELPA](https://melpa.org/packages/vterm-badge.svg)](https://melpa.org/#/vterm)\n\n# Introduction\n\nEmacs-libvterm (_vterm_) is fully-fledged terminal emulator inside GNU Emacs\nbased on [libvterm](https://github.com/neovim/libvterm), a C library. As a\nresult of using compiled code (instead of elisp), emacs-libvterm is fully\ncapable, fast, and it can seamlessly handle large outputs.\n\n## Warning\n\nThis package is in active development and, while being stable enough to be used\nas a daily-driver, it is currently in **alpha** stage. This means that\noccasionally the public interface will change (for example names of options or\nfunctions). A list of recent breaking changes is in\n[appendix](#breaking-changes). Moreover, emacs-libvterm deals directly with some\nlow-level operations, hence, bugs can lead to segmentation faults and crashes.\nIf that happens, please [report the\nproblem](https://github.com/akermu/emacs-libvterm/issues/new).\n\n## Given that eshell, shell, and (ansi-)term are Emacs built-in, why should I use vterm?\n\nThe short answer is: unparalleled performance and compatibility with standard\ncommand-line tools.\n\nFor the long answer, let us discuss the differences between `eshell`, `shell`,\n`term` and `vterm`:\n- `eshell`: it is a shell completely implemented in Emacs Lisp. It is\n  well-integrated in Emacs and it runs on Windows. It does not support command line\n  tools that require terminal manipulation capabilities (e.g., `ncdu`, `nmtui`,\n  ...).\n- `shell`: it interfaces with a standard shell (e.g., `bash`). It reads an input\n  from Emacs, sends it to the shell, and reports back the output from the shell.\n  As such, like `eshell`, it does not support interactive commands, especially\n  those that directly handle how the output should be displayed (e.g., `htop`).\n- `term`: it is a terminal emulator written in elisp. `term` runs a shell\n  (similarly to other terminal emulators like Gnome Terminal) and programs can\n  directly manipulate the output using escape codes. Hence, many interactive\n  applications (like the one aforementioned) work with `term`. However, `term`\n  and `ansi-term` do not implement all the escapes codes needed, so some\n  programs do not work properly. Moreover, `term` has inferior performance\n  compared to standalone terminals, especially with large bursts of output.\n- `vterm`: like `term` it is a terminal emulator. Unlike `term`, the core of\n  `vterm` is an external library written in C, `libvterm`. For this reason,\n  `vterm` outperforms `term` and has a nearly universal compatibility with\n  terminal applications.\n\nVterm is not for you [if you are using Windows](https://github.com/akermu/emacs-libvterm/issues/12), or if you cannot set up Emacs\nwith support for modules. Otherwise, you should try vterm, as it provides a\nsuperior terminal experience in Emacs.\n\nUsing `vterm` is like using Gnome Terminal inside Emacs: Vterm is fully-featured\nand fast, but is not as well integrated in Emacs as `eshell` (yet), so some of\nthe editing keybinding you are used to using may not work. For example,\n`evil-mode` is currently not supported (though, users can enable VI emulation in\ntheir shells). This is because keys are sent directly to the shell. We are\nconstantly working to improve this.\n\n# Installation\n\n## Requirements\n\nBefore installing emacs-libvterm, you need to make sure you have installed\n 1. GNU Emacs (\u003e= 25.1) with [module\n    support](https://www.gnu.org/software/emacs/manual/html_node/elisp/Dynamic-Modules.html).\n    You can check that, by verifying that `module-file-suffix` is not `nil`.\n 2. cmake (\u003e= 3.11)\n 3. libtool-bin (related issues:\n    [#66](https://github.com/akermu/emacs-libvterm/issues/66)\n    [#85](https://github.com/akermu/emacs-libvterm/issues/85#issuecomment-491845136))\n 4. OPTIONAL: [libvterm](https://github.com/Sbozzolo/libvterm-mirror.git) (\u003e= 0.2). This\n    library can be found in the official repositories of most distributions\n    (e.g., Arch, Debian, Fedora, Gentoo, openSUSE, Ubuntu). Typical names are\n    `libvterm` (Arch, Fedora, Gentoo, openSUSE), or `libvterm-dev` (Debian,\n    Ubuntu). If not available, `libvterm` will be downloaded during the\n    compilation process. Some distributions (e.g. Ubuntu \u003c 20.04, Debian \u003c 11)\n    have versions of `libvterm` that are too old. If you find compilation errors\n    related to `VTERM_COLOR`, you should not use your system libvterm. See\n    [FAQ](#frequently-asked-questions-and-problems) for more details.\n\n## From MELPA\n\n`vterm` is available on [MELPA](https://melpa.org/), and it can be installed as\na normal package. If the requirements are satisfied (mainly, Emacs was built\nwith support for modules), `vterm` will compile the module the first time it is\nrun. This is the recommended way to install `vterm`.\n\n`vterm` can be install from MELPA with `use-package` by adding the following\nlines to your `init.el`:\n\n```elisp\n(use-package vterm\n    :ensure t)\n```\n\nTo take full advantage of the capabilities of `vterm`, you should configure your\nshell too. Read about this in the section [shell-side\nconfiguration](#shell-side-configuration).\n\n## Manual installation\n\nClone the repository:\n\n```sh\ngit clone https://github.com/akermu/emacs-libvterm.git\n```\n\nBy default, vterm will try to find if libvterm is installed. If it is not found,\nemacs-libvterm will download the latest version available of libvterm (from\n[here](https://github.com/neovim/libvterm)), compile it, and use it. If you\nalways want to use the vendored version as opposed to the one on you system, set\n`USE_SYSTEM_LIBVTERM` to `no`. To do this, change `cmake ..` with `cmake\n-DUSE_SYSTEM_LIBVTERM=no ..` in the following instructions.\n\nBuild the module with:\n\n```sh\ncd emacs-libvterm\nmkdir -p build\ncd build\ncmake ..\nmake\n```\n\nAnd add this to your `init.el`:\n\n```elisp\n(add-to-list 'load-path \"path/to/emacs-libvterm\")\n(require 'vterm)\n```\n\nOr, with `use-package`:\n\n```elisp\n(use-package vterm\n  :load-path  \"path/to/emacs-libvterm/\")\n```\n\n## vterm and Ubuntu\n### 20.04\nUsing `vterm` on Ubuntu requires additional steps. The latest LTS version\n(20.04) ships without CMake installed and Emacs27 is not yet available from Ubuntu's package repository.\n\nThe basic steps for getting vterm to work on Ubuntu 20.04 are:\n* Ensure Emacs27 is installed\n* Install cmake, libtool, and libtool-bin\n\nThere are a few options for installing Emacs27 on Ubuntu 20.04:\n* Compile Emacs27 from source\n* Install Emacs27 from Snap\n* Install Emacs27 from Kevin Kelley's PPA\n\nIn any case, if you have an older Emacs version you will need to purge it before proceeding:\n\n#### Purge Emacs\n\n```sh\nsudo apt --purge remove emacs\nsudo apt autoremove\n```\n\n#### Installing Emacs27 from Kevin Kelley PPA\n\n```sh\nsudo add-apt-repository ppa:kelleyk/emacs\nsudo apt install emacs27\n```\n\n##### If you get an error about emacs27_common during the install process:\n\n```sh\nErrors were encountered while processing:\n /tmp/apt-dpkg-install-RVK8CA/064-emacs27-common_27.1~1.git86d8d76aa3-kk2+20.04_all.deb\n```\n\nrun\n\n```sh\nsudo apt --purge remove emacs-common\nsudo apt --fix-broken install\n```\n\n#### Installing Emacs27 from Snap\nI hesitate to include SNAP here, because I ran into a number of GTK Theme parsing errors, and Fontconfig errors when I tested it, and reverted to installing from Kevin Kelley's PPA. YMMV\n\n```sh\nsudo snap install emacs --classic\n```\n\n#### Install CMake and Libtool\nIn Ubuntu 20.04 CMake (v3.16.3-1ubuntu1) and Libtool can be installed with\n\n```sh\nsudo apt install cmake\nsudo apt install libtool\nsudo apt install libtool-bin\n```\n\n### 18.04\n\nUsing `vterm` on Ubuntu 18.04 requires additional steps.\n18.04 ships with a version of CMake that is too old for `vterm` and GNU\nEmacs is not compiled with support for dynamical module loading.\n\nIt is possible to install GNU Emacs with module support from Kevin Kelley's PPA.\nThe binary in Ubuntu Emacs Lisp PPA is currently broken and leads to segmentation faults\n(see [#185](https://github.com/akermu/emacs-libvterm/issues/185#issuecomment-562237077)).\nIn case Emacs is already on the system, you need to purge it before proceeding\nwith the following commands.\n\n```sh\nsudo add-apt-repository ppa:kelleyk/emacs\nsudo apt update\nsudo apt-get install emacs26\n```\n\nA way to install a recent version of CMake (\u003e= 3.11) is with linuxbrew.\n\n```sh\nbrew install cmake\n```\n\n\nIn some cases, `/bin/sh` needs to be relinked to `/bin/bash` for the compilation\nto work (see,\n[#216](https://github.com/akermu/emacs-libvterm/issues/216#issuecomment-575934593)).\n\nPull requests to improve support for Ubuntu are welcome (e.g., simplifying the\ninstallation).\n\nSome releases of Ubuntu (e.g., 18.04) ship with a old version of libvterm that\ncan lead to compilation errors. If you have this problem, see the\n[FAQ](#frequently-asked-questions-and-problems) for a solution.\n\n## GNU Guix\n\n`vterm` and its dependencies are available in GNU Guix as\n[emacs-vterm](https://guix.gnu.org/packages/emacs-vterm-0-1.7d7381f/).\nThe package can be installed with `guix package -i emacs-vterm`.\n\n## Shell-side configuration\n\nSome of the most useful features in `vterm` (e.g., [directory-tracking and\nprompt-tracking](#directory-tracking-and-prompt-tracking) or [message\npassing](#message-passing)) require shell-side configurations. The main goal of\nthese additional functions is to enable the shell to send information to `vterm`\nvia properly escaped sequences. A function that helps in this task,\n`vterm_printf`, is defined below. This function is widely used throughout this\nreadme.\n\nFor `bash` or `zsh`, put this in your `.zshrc` or `.bashrc`\n\n```sh\nvterm_printf() {\n    if [ -n \"$TMUX\" ] \\\n        \u0026\u0026 { [ \"${TERM%%-*}\" = \"tmux\" ] \\\n            || [ \"${TERM%%-*}\" = \"screen\" ]; }; then\n        # Tell tmux to pass the escape sequences through\n        printf \"\\ePtmux;\\e\\e]%s\\007\\e\\\\\" \"$1\"\n    elif [ \"${TERM%%-*}\" = \"screen\" ]; then\n        # GNU screen (screen, screen-256color, screen-256color-bce)\n        printf \"\\eP\\e]%s\\007\\e\\\\\" \"$1\"\n    else\n        printf \"\\e]%s\\e\\\\\" \"$1\"\n    fi\n}\n```\n\nThis works also for `dash`.\n\nFor `fish` put this in your `~/.config/fish/config.fish`:\n\n```fish\nfunction vterm_printf;\n    if begin; [  -n \"$TMUX\" ]  ; and  string match -q -r \"screen|tmux\" \"$TERM\"; end\n        # tell tmux to pass the escape sequences through\n        printf \"\\ePtmux;\\e\\e]%s\\007\\e\\\\\" \"$argv\"\n    else if string match -q -- \"screen*\" \"$TERM\"\n        # GNU screen (screen, screen-256color, screen-256color-bce)\n        printf \"\\eP\\e]%s\\007\\e\\\\\" \"$argv\"\n    else\n        printf \"\\e]%s\\e\\\\\" \"$argv\"\n    end\nend\n```\n\n# Debugging and testing\n\nIf you have successfully built the module, you can test it by executing the\nfollowing command in the `build` directory:\n\n```sh\nmake run\n```\n\n# Usage\n\n## `vterm`\n\nOpen a terminal in the current window.\n\n## `vterm-other-window`\n\nOpen a terminal in another window.\n\n## `vterm-copy-mode`\n\nWhen you enable `vterm-copy-mode`, the terminal buffer behaves like a normal\n`read-only` text buffer: you can search, copy text, etc. The default keybinding\nto toggle `vterm-copy-mode` is `C-c C-t`. When a region is selected, it is\npossible to copy the text and leave `vterm-copy-mode` with the enter key.\n\nIf no region is selected when the enter key is pressed it will copy the current\nline from start to end. If `vterm-copy-exclude-prompt` is true it will skip\nthe prompt and not include it in the copy.\n\n## `vterm-clear-scrollback`\n\n`vterm-clear-scrollback` does exactly what the name suggests: it clears the\ncurrent buffer from the data that it is not currently visible.\n`vterm-clear-scrollback` is bound to `C-c C-l`. This function is typically used\nwith the `clear` function provided by the shell to clear both screen and\nscrollback. In order to achieve this behavior, you need to add a new shell alias.\n\nFor `zsh`, put this in your `.zshrc`:\n\n```zsh\nif [[ \"$INSIDE_EMACS\" = 'vterm' ]]; then\n    alias clear='vterm_printf \"51;Evterm-clear-scrollback\";tput clear'\nfi\n```\n\nFor `bash`, put this in your `.bashrc`:\n\n```bash\nif [ \"$INSIDE_EMACS\" = 'vterm' ]; then\n    clear() {\n        vterm_printf \"51;Evterm-clear-scrollback\";\n        tput clear;\n    }\nfi\n```\n\nFor `fish`:\n\n```fish\nif [ \"$INSIDE_EMACS\" = 'vterm' ]\n    function clear\n        vterm_printf \"51;Evterm-clear-scrollback\";\n        tput clear;\n    end\nend\n```\n\nThese aliases take advantage of the fact that `vterm` can execute `elisp`\ncommands, as explained below.\n\nIf it possible to automatically clear the scrollback when the screen is cleared\nby setting the variable `vterm-clear-scrollback-when-clearing`: When\n`vterm-clear-scrollback-when-clearing` is non nil, `C-l` clears both the screen\nand the scrollback. When is nil, `C-l` only clears the screen. The opposite\nbehavior can be achieved by using the universal prefix (i.e., calling `C-u C-l`).\n\n# Customization\n\n## `vterm-shell`\n\nShell to run in a new vterm. It defaults to `$SHELL`.\n\n## `vterm-environment`\n\nto add more environment variables there is the custom vterm-environment which has\na similar format than the internal Emacs variable process-environment.\nYou can check the documentation with C-h v process-environment for more details.\n\n## `vterm-term-environment-variable`\n\nValue for the `TERM` environment variable. It defaults to `xterm-256color`. If\n[eterm-256color](https://github.com/dieggsy/eterm-256color) is installed,\nsetting `vterm-term-environment-variable` to `eterm-color` improves the\nrendering of colors in some systems.\n\n## `vterm-kill-buffer-on-exit`\n\nIf set to `t`, buffers are killed when the associated process is terminated (for\nexample, by logging out the shell). Keeping buffers around it is useful if you\nneed to copy or manipulate the content.\n\n## `vterm-module-cmake-args`\n\nCompilation flags and arguments to be given to CMake when compiling the module.\nThis string is directly passed to CMake, so it uses the same syntax. At the\nmoment, it main use is for compiling vterm using the system libvterm instead of\nthe one downloaded from GitHub. You can find all the arguments and flags\navailable with `cmake -LA` in the build directory.\n\n## `vterm-copy-exclude-prompt`\n\nControls whether or not to exclude the prompt when copying a line in\n`vterm-copy-mode`. Using the universal prefix before calling\n`vterm-copy-mode-done` will invert the value for that call, allowing you to\ntemporarily override the setting. When a prompt is not found, the whole line is\ncopied.\n\n## `vterm-use-vterm-prompt-detection-method`\n\nThe variable `vterm-use-vterm-prompt-detection-method` determines whether to use\nthe vterm prompt tracking, if false it use the regexp in\n`vterm-copy-prompt-regexp` to search for the prompt.\n\n## `vterm-enable-manipulate-selection-data-by-osc52`\n\nVterm support copy text to Emacs kill ring and system clipboard by using OSC 52.\nSee https://invisible-island.net/xterm/ctlseqs/ctlseqs.html for more info about OSC 52.\nFor example: send 'blabla' to kill ring: printf \"\\033]52;c;$(printf \"%s\" \"blabla\" | base64)\\a\"\n\ntmux can share its copy buffer to terminals by supporting osc52(like iterm2 xterm),\nyou can enable this feature for tmux by :\nset -g set-clipboard on         #osc 52 copy paste share with iterm\nset -ga terminal-overrides ',xterm*:XT:Ms=\\E]52;%p1%s;%p2%s\\007'\nset -ga terminal-overrides ',screen*:XT:Ms=\\E]52;%p1%s;%p2%s\\007'\n\nThe clipboard querying/clearing functionality offered by OSC 52 is not implemented here,\nAnd for security reason, this feature is disabled by default.\"\n\nThis feature need the new way of handling strings with a struct `VTermStringFragment`\nin libvterm. You'd better compile emacs-libvterm with `cmake -DUSE_SYSTEM_LIBVTERM=no ..`.\nIf you don't do that, when  the content you want to copied is too long, it would be truncated\nby bug of libvterm.\n\n## `vterm-buffer-name-string`\n\nWhen `vterm-buffer-name-string` is not nil, vterm renames automatically its own\nbuffers with `vterm-buffer-name-string`. This string can contain the character\n`%s`, which is substituted with the _title_ (as defined by the shell, see\nbelow). A possible value for `vterm-buffer-name-string` is `vterm %s`, according\nto which all the vterm buffers will be named \"vterm TITLE\".\n\nThis requires some shell-side configuration to print the title. For example to\nset the name \"HOSTNAME:PWD\", use can you the following:\n\nFor `zsh`,\n\n```zsh\nautoload -U add-zsh-hook\nadd-zsh-hook -Uz chpwd (){ print -Pn \"\\e]2;%m:%2~\\a\" }\n```\n\nFor `bash`,\n\n```bash\nPROMPT_COMMAND=\"${PROMPT_COMMAND:+$PROMPT_COMMAND; }\"'echo -ne \"\\033]0;${HOSTNAME}:${PWD}\\007\"'\n```\n\nFor `fish`,\n\n```fish\nfunction fish_title\n    hostname\n    echo \":\"\n    prompt_pwd\nend\n```\n\nSee [zsh and bash](http://tldp.org/HOWTO/Xterm-Title-4.html) and [fish\ndocumentations](https://fishshell.com/docs/current/#programmable-title).\n\n## `vterm-always-compile-module`\n\nVterm needs `vterm-module` to work. This can be compiled externally, or `vterm`\nwill ask the user whether to build the module when `vterm` is first called. To\navoid this question and always compile the module, set\n`vterm-always-compile-module` to `t`.\n\n## `vterm-copy-mode-remove-fake-newlines`\n\nWhen not-nil fake newlines are removed on entering copy mode.\nvterm inserts fake-newlines purely for rendering. When using\n`vterm-copy-mode` these are in conflict with many emacs functions\nlike isearch-forward. if this varialbe is not-nil the\nfake-newlines are removed on entering copy-mode and re-inserted\non leaving copy mode. Also truncate-lines is set to t on entering\ncopy-mode and set to nil on leaving.\n\n## `vterm-tramp-shells`\n\nThe shell that gets run in the vterm for tramp.\n\nThis has to be a list of pairs of the format:\n`(TRAMP-METHOD SHELL)`\n\nThe `TRAMP-METHOD` is a method string as used by tramp (e.g., `\"ssh\"`).\nUse t as `TRAMP-METHOD` to specify a default shell for all methods.\nSpecific methods always take precedence over `t`.\n\nSet SHELL to `'login-shell` to use the user's login shell on the remote host.\nThe login-shell detection currently works for POSIX-compliant remote hosts that\nhave the `getent` command (regular GNU/Linux distros, *BSDs, but not MacOS X\nunfortunately).\nYou can specify an additional second `SHELL` command as a fallback\nthat is used when the login-shell detection fails, e.g.,\n`'((\"ssh\" login-shell \"/bin/bash\") ...)`\nIf no second `SHELL` command is specified with `'login-shell`, vterm will\nfall back to tramp's shell.\n\nExamples:\n- Usee the default login shell for all methods, except for docker.\n  `'((t login-shell) (\"docker\" \"/bin/sh\"))`\n- Use the default login shell for ssh and scp, fall back to \"/bin/bash\".\n  Use tramp's default shell for all other methods.\n  `'((\"ssh\" login-shell \"/bin/bash\") (\"scp\" login-shell \"/bin/bash\"))`\n\n## Keybindings\n\nIf you want a key to be sent to the terminal, bind it to `vterm--self-insert`,\nor remove it from `vterm-mode-map`. By default, `vterm.el` binds most of the\n`C-\u003cchar\u003e` and `M-\u003cchar\u003e` keys, `\u003cf1\u003e` through `\u003cf12\u003e` and some special keys\nlike `\u003cbackspace\u003e` and `\u003creturn\u003e`. Sending a keyboard interrupt is bound to `C-c\nC-c`.\n\nIn order to send a keypress that is already recognized by Emacs, such as `C-g`,\nuse the interactive function `vterm-send-next-key`. This can be bound to a key\nin the `vterm-mode-map` like `C-q`, in which case pressing `C-q C-g` will send a\n`C-g` key to the terminal, and so on for other modified keys:\n\n```elisp\n(define-key vterm-mode-map (kbd \"C-q\") #'vterm-send-next-key)\n```\n\nThis can be useful for controlling an application running in the terminal, such\nas Emacs or Nano.\n\n## Fonts\n\nYou can change the font (the _face_) used in a vterm with the following code:\n\n```elisp\n(add-hook 'vterm-mode-hook\n          (lambda ()\n            (set (make-local-variable 'buffer-face-mode-face) 'fixed-pitch)\n                 (buffer-face-mode t)))\n```\n\nWhere instead of `'fixed-pitch` you specify the face you want to use. The\nexample reported here can be used to force vterm to use a mono-spaced font (the\n`fixed-pitch` face). This is useful when your default font in Emacs is a\nproportional font.\n\nIn addition to that, you can disable some text properties (bold, underline,\nreverse video) setting the relative option to `t` (`vterm-disable-bold`,\n`vterm-disable-underline`, or `vterm-disable-inverse-video`).\n\nYou can use another font for vterm buffer\n\n``` elisp\n(add-hook 'vterm-mode-hook\n          (lambda ()\n               (set (make-local-variable 'buffer-face-mode-face) '(:family \"IosevkaTerm Nerd Font\"))\n               (buffer-face-mode t))\n```\n## Blink cursor\n\nWhen `vterm-ignore-blink-cursor` is `t`, vterm will ignore request from application to turn on or off cursor blink.\n\nIf `nil`, cursor in any window may begin to blink or not blink because `blink-cursor-mode`\nis a global minor mode in Emacs, you can use `M-x blink-cursor-mode` to toggle.\n\n## Colors\n\nCustomize the following faces to your liking. It is possible to specify\ndifferent colors for foreground and background via the `:foreground` and\n`:background` attributes.\n\n- vterm-color-black\n- vterm-color-red\n- vterm-color-green\n- vterm-color-yellow\n- vterm-color-blue\n- vterm-color-magenta\n- vterm-color-cyan\n- vterm-color-white\n- vterm-color-bright-black\n- vterm-color-bright-red\n- vterm-color-bright-green\n- vterm-color-bright-yellow\n- vterm-color-bright-blue\n- vterm-color-bright-magenta\n- vterm-color-bright-cyan\n- vterm-color-bright-white\n\n## Directory tracking and Prompt tracking\n\n`vterm` supports _directory tracking_. If this feature is enabled, the default\ndirectory in Emacs and the current working directory in `vterm` are synced. As a\nresult, interactive functions that ask for a path or a file (e.g., `dired` or\n`find-file`) will do so starting from the current location.\n\nAnd `vterm` supports _prompt tracking_. If this feature is enabled, Emacs knows\nwhere the prompt ends, you needn't  customize `term-prompt-regexp` any more.\nThen you can use `vterm-next-prompt` and `vterm-previous-prompt`\nmoving to end of next/previous prompt. The default keybinding is `C-c C-n` and `C-c C-p`.\n\nAnd `vterm-beginning-of-line` would move the point to the first character after the\nshell prompt on this line. If the point is already there, move to the beginning of the line.\nThe default keybinding is `C-a` in `vterm-copy-mode`.\n\nAnd `vterm--at-prompt-p` would check whether the cursor is at the point just after\nthe shell prompt.\n\nDirectory tracking and Prompt tracking requires some configuration, as the shell has to be\ninstructed to share the relevant information with Emacs. The following pieces of\ncode assume that you have the function `vterm_printf` as defined in section\n[shell-side configuration](#shell-side-configuration).\n\nFor `zsh`, put this at the end of your `.zshrc`:\n\n```zsh\nvterm_prompt_end() {\n    vterm_printf \"51;A$(whoami)@$(hostname):$(pwd)\"\n}\nsetopt PROMPT_SUBST\nPROMPT=$PROMPT'%{$(vterm_prompt_end)%}'\n```\n\nFor `bash`, put this at the end of your `.bashrc`:\n\n```bash\nvterm_prompt_end(){\n    vterm_printf \"51;A$(whoami)@$(hostname):$(pwd)\"\n}\nPS1=$PS1'\\[$(vterm_prompt_end)\\]'\n```\n\nFor `fish`, put this in your `~/.config/fish/config.fish`:\n\n```fish\nfunction vterm_prompt_end;\n    vterm_printf '51;A'(whoami)'@'(hostname)':'(pwd)\nend\nfunctions --copy fish_prompt vterm_old_fish_prompt\nfunction fish_prompt --description 'Write out the prompt; do not replace this. Instead, put this at end of your file.'\n    # Remove the trailing newline from the original prompt. This is done\n    # using the string builtin from fish, but to make sure any escape codes\n    # are correctly interpreted, use %b for printf.\n    printf \"%b\" (string join \"\\n\" (vterm_old_fish_prompt))\n    vterm_prompt_end\nend\n```\n\nHere we are using the function `vterm_printf` that we have discussed above, so make\nsure that this function is defined in your configuration file.\n\nDirectory tracking works on remote servers too. In case the hostname of your\nremote machine does not match the actual hostname needed to connect to that\nserver, change `$(hostname)` with the correct one. For example, if the correct\nhostname is `foo` and the username is `bar`, you should have something like\n\n```bash\nHOSTNAME=foo\nUSER=baz\nvterm_printf \"51;A$USER@$HOSTNAME:$(pwd)\"\n```\n\n## Message passing\n\n`vterm` can read and execute commands. At the moment, a command is\npassed by providing a specific escape sequence. For example, to evaluate\n\n```elisp\n(message \"Hello!\")\n```\n\nuse\n\n```sh\nprintf \"\\e]51;Emessage \\\"Hello\\!\\\"\\e\\\\\"\n# or\nvterm_printf \"51;Emessage \\\"Hello\\!\\\"\"\n```\n\nThe commands that are understood are defined in the setting `vterm-eval-cmds`.\n\nAs `split-string-and-unquote` is used the parse the passed string, double quotes\nand backslashes need to be escaped via backslash. A convenient shell function to\nautomate the substitution is\n\n`bash` or `zsh`:\n\n```sh\nvterm_cmd() {\n    local vterm_elisp\n    vterm_elisp=\"\"\n    while [ $# -gt 0 ]; do\n        vterm_elisp=\"$vterm_elisp\"\"$(printf '\"%s\" ' \"$(printf \"%s\" \"$1\" | sed -e 's|\\\\|\\\\\\\\|g' -e 's|\"|\\\\\"|g')\")\"\n        shift\n    done\n    vterm_printf \"51;E$vterm_elisp\"\n}\n```\n\n`fish`:\n\n```fish\nfunction vterm_cmd --description 'Run an Emacs command among the ones been defined in vterm-eval-cmds.'\n    set -l vterm_elisp ()\n    for arg in $argv\n        set -a vterm_elisp (printf '\"%s\" ' (string replace -a -r '([\\\\\\\\\"])' '\\\\\\\\\\\\\\\\$1' $arg))\n    end\n    vterm_printf '51;E'(string join '' $vterm_elisp)\nend\n```\n\nNow we can write shell functions to call the ones defined in `vterm-eval-cmds`.\n\n```sh\nfind_file() {\n    vterm_cmd find-file \"$(realpath \"${@:-.}\")\"\n}\n\nsay() {\n    vterm_cmd message \"%s\" \"$*\"\n}\n```\n\nOr for `fish`:\n\n```fish\nfunction find_file\n    set -q argv[1]; or set argv[1] \".\"\n    vterm_cmd find-file (realpath \"$argv\")\nend\n\nfunction say\n    vterm_cmd message \"%s\" \"$argv\"\nend\n```\n\nThis newly defined `find_file` function can now be used inside `vterm` as\n\n```sh\nfind_file name_of_file_in_local_directory\n```\n\nIf you call `find_file` without specifying any file (you just execute `find_file` in your shell),\n`dired` will open with the current directory.\n\nAs an example, say you like having files opened below the current window. You\ncould add the command to do it on the lisp side like so:\n\n```elisp\n(push (list \"find-file-below\"\n            (lambda (path)\n              (if-let* ((buf (find-file-noselect path))\n                        (window (display-buffer-below-selected buf nil)))\n                  (select-window window)\n                (message \"Failed to open file: %s\" path))))\n      vterm-eval-cmds)\n```\n\nThen add the command in your `.bashrc` file.\n\n```sh\nopen_file_below() {\n    vterm_cmd find-file-below \"$(realpath \"${@:-.}\")\"\n}\n```\n\nThen you can open any file from inside your shell.\n\n```sh\nopen_file_below ~/Documents\n```\n\n## Shell-side configuration files\n\nThe configurations described in earlier sections are combined in\n[`etc/`](./etc/). These can be appended to or loaded into your user\nconfiguration file. Alternatively, they can be installed system-wide, for\nexample in `/etc/bash/bashrc.d/`, `/etc/profile.d/` (for `zsh`), or\n`/etc/fish/conf.d/` for `fish`.\n\nWhen using vterm Emacs sets the environment variable INSIDE_EMACS in the subshell to ‘vterm’.\nUsually the programs check this variable to determine whether they are running inside Emacs.\n\nVterm also sets an extra variable EMACS_VTERM_PATH to the place where the vterm library is installed.\nThis is very useful because when vterm is installed from melpa the Shell-side configuration files are\nin the EMACS_VTERM_PATH inside the /etc sub-directory. After a package update, the directory name changes,\nso, a code like this in your bashrc could be enough to load always the latest version of the file\nfrom the right location without coping any file manually.\n\n```sh\nif [[ \"$INSIDE_EMACS\" = 'vterm' ]] \\\n    \u0026\u0026 [[ -n ${EMACS_VTERM_PATH} ]] \\\n    \u0026\u0026 [[ -f ${EMACS_VTERM_PATH}/etc/emacs-vterm-bash.sh ]]; then\n\tsource ${EMACS_VTERM_PATH}/etc/emacs-vterm-bash.sh\nfi\n```\n\n## Frequently Asked Questions and Problems\n\n### How can I increase the size of the scrollback?\n\nBy default, the scrollback can contain up to 1000 lines per each vterm buffer.\nYou can increase this up to 100000 by changing the variable\n`vterm-max-scrollback`. If you want to increase it further, you have to edit the\nfile `vterm-module.h`, change the variable `SB_MAX`, and set the new value for\n`vterm-max-scrollback`. The potential maximum memory consumption of vterm\nbuffers increases with `vterm-max-scrollback`, so setting `SB_MAX` to extreme\nvalues may lead to system instabilities and crashes.\n\n### How can I automatically close vterm buffers when the process is terminated?\n\nThere is an option for that: set `vterm-kill-buffer-on-exit` to `t`.\n\n### The package does not compile, I have errors related to `VTERM_COLOR`.\n\nThe version of `libvterm` installed on your system is too old. You should let\n`emacs-libvterm` download `libvterm` for you. You can either uninstall your\nlibvterm, or instruct Emacs to ignore the system libvterm. If you are compiling\nfrom Emacs, you can do this by setting:\n\n```elisp\n(setq vterm-module-cmake-args \"-DUSE_SYSTEM_LIBVTERM=no\")\n```\n\nand compile again. If you are compiling with CMake, use the flag\n`-DUSE_SYSTEM_LIBVTERM=no`.\n\n### `\u003cC-backspace\u003e` doesn't kill previous word.\n\nThis can be fixed by rebinding the key to what `C-w` does:\n\n```elisp\n(define-key vterm-mode-map (kbd \"\u003cC-backspace\u003e\")\n    (lambda () (interactive) (vterm-send-key (kbd \"C-w\"))))\n```\n\n### `counsel-yank-pop` doesn't work.\n\nAdd this piece of code to your configuration file to make `counsel` use\nthe correct function to yank in vterm buffers.\n\n```elisp\n(defun vterm-counsel-yank-pop-action (orig-fun \u0026rest args)\n  (if (equal major-mode 'vterm-mode)\n      (let ((inhibit-read-only t)\n            (yank-undo-function (lambda (_start _end) (vterm-undo))))\n        (cl-letf (((symbol-function 'insert-for-yank)\n               (lambda (str) (vterm-send-string str t))))\n            (apply orig-fun args)))\n    (apply orig-fun args)))\n\n(advice-add 'counsel-yank-pop-action :around #'vterm-counsel-yank-pop-action)\n```\n\n### How can I get the local directory without shell-side configuration?\n\nWe recommend that you set up shell-side configuration for reliable directory\ntracking. If you cannot do it, a possible workaround is the following.\n\nOn most GNU/Linux systems, you can read current directory from `/proc`:\n\n```elisp\n(defun vterm-directory-sync ()\n  \"Synchronize current working directory.\"\n  (interactive)\n  (when vterm--process\n    (let* ((pid (process-id vterm--process))\n           (dir (file-truename (format \"/proc/%d/cwd/\" pid))))\n      (setq default-directory dir))))\n```\n\nA possible application of this function is in combination with `find-file`:\n\n```elisp\n(advice-add #'find-file :before #'vterm-directory-sync)\n```\n\nThis method does not work on remote machines.\n\n### How can I get the directory tracking in a more understandable way?\n\nIf you looked at the recommended way to set-up directory tracking, you will have\nnoticed that it requires printing obscure code like `\\e]2;%m:%2~\\a` (unless you\nare using `fish`).\n\nThere is another way to achieve this behavior. Define a shell function, on a\nlocal host you can simply use\n\n```sh\nvterm_set_directory() {\n    vterm_cmd update-pwd \"$PWD/\"\n}\n```\n\nOn a remote one, use instead\n\n```sh\nvterm_set_directory() {\n    vterm_cmd update-pwd \"/-:\"\"$USER\"\"@\"\"$HOSTNAME\"\":\"\"$PWD/\"\n}\n```\n\nThen, for `zsh`, add this function to the `chpwd` hook:\n\n```zsh\nautoload -U add-zsh-hook\nadd-zsh-hook -Uz chpwd (){ vterm_set_directory }\n```\n\nFor `bash`, append it to the prompt:\n\n```bash\nPROMPT_COMMAND=\"${PROMPT_COMMAND:+$PROMPT_COMMAND; }vterm_set_directory\"\n```\n\nFinally, add `update-pwd` to the list of commands that Emacs\nis allowed to execute from vterm:\n\n```elisp\n(add-to-list 'vterm-eval-cmds '(\"update-pwd\" (lambda (path) (setq default-directory path))))\n```\n\n### When evil-mode is enabled, the cursor moves back in normal state, and this messes directory tracking\n\n`evil-collection` provides a solution for this problem. If you do not want to\nuse `evil-collection`, you can add the following code:\n\n```elisp\n(defun evil-collection-vterm-escape-stay ()\n\"Go back to normal state but don't move\ncursor backwards. Moving cursor backwards is the default vim behavior but it is\nnot appropriate in some cases like terminals.\"\n(setq-local evil-move-cursor-back nil))\n\n(add-hook 'vterm-mode-hook #'evil-collection-vterm-escape-stay)\n```\n\n\n## Related packages\n\n- [vterm-toggle](https://github.com/jixiuf/vterm-toggle): Toggles between a\n  vterm and the current buffer\n- [multi-libvterm](https://github.com/suonlight/multi-libvterm): Multiterm for emacs-libvterm\n\n## Appendix\n\n### Breaking changes\n\nObsolete variables will be removed in version 0.1.\n\n#### August 2022\n* `vterm-send-C-[a-z]` `vterm-send-M-[a-z]` `vterm-define-key`\n `vterm-send-{up/down/left/right/prior/next/meta-dot/meta-comma/ctrl-slash}`\n were obsolete, please use `vterm-send` or `vterm-send-key` or\n `vterm--self-insert` instead.\n\n#### October 2020\n\n* `vterm-disable-bold-font` was renamed to `vterm-disable-bold` to uniform it\n   with the other similar options.\n\n#### July 2020\n\n* `vterm-use-vterm-prompt` was renamed to `vterm-use-vterm-prompt-detection-method`.\n* `vterm-kill-buffer-on-exit` is set to `t` by default.\n\n#### April 2020\n\n* `vterm-clear-scrollback` was renamed to `vterm-clear-scrollback-when-clearning`.\n* `vterm-set-title-functions` was removed. In its place, there is a new custom\n  option `vterm-buffer-name-string`. See\n  [vterm-buffer-name-string](vterm-buffer-name-string) for documentation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakermu%2Femacs-libvterm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakermu%2Femacs-libvterm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakermu%2Femacs-libvterm/lists"}