--- name: "elvis" section: "1" platform: "linux" package: "elvis-common" version: "2.2.0-11.1" release: "Debian 7 (Wheezy)" platforms: ["linux"] url: "https://new.carta.tech/elvis" --- # elvis(1) a clone of the ex/vi text editor ## NAME elvis - a clone of the ex/vi text editor ## SYNOPSIS **elvis** \[**-V**...\] \[**-a**\] \[**-r**\] \[**-e**\] \[**-i**\] \[**-s**\|**-**\] \[**-b**\] \[**-R**\] \[**-S**\|**-SS**\] \[**-f** *session*\] \[**-o** *logfile*\] \[**-G** *gui*\] \[**-c *command***\|**+*command***\] \[**-t** *tag*\] \[**-w** *scroll*\] \[**-B** *blksize*\] \[*file*\]... ## VERSION Elvis 2.2\_0 ## DESCRIPTION **Elvis** is a text editor. It is intended to be a modern replacement for the classic *ex*/*vi* editor of UNIX fame. **Elvis** supports many new features, including multiple edit buffers, multiple windows, multiple user interfaces (including an X11 interface), and a variety of display modes. To exit **Elvis,** you can give the command ":q" in each of its windows. If you've modified the buffer in a window, and you want to abandon those changes, then give the command ":q!" instead. ## HELP PAGES For more information please take a look at **Elvis**' help pages. These pages should have been installed together with **Elvis**. To view the help pages, start **Elvis** and give the command ":help". If this does not show you the main help file then something is wrong. Perhaps the help pages were installed in the wrong place. In that case, search for a file named "elvis.html" using either GNU's [**locate**(1)](/locate/1.md) or the standard [**find**(1)](/find/1.md) program. Hopefully this will show you where the file is located. You can then view it with... ``` :sp /directory/elvis.html ``` If the help pages aren't installed on your system but you have access to the Internet, then you can view the help pages via HTTP by running... ``` :sp http://elvis.vi-editor.org/elvisman/elvis.html ``` ## OPTIONS - **-V** "Verbose" mode, causes **Elvis** to output more status messages. You can use multiple **-V** flags to get even more detailed information. **-VVV** can be handy when **Elvis** isn't initializing itself quite the way you expected. See also the **-o***logfile* option, described below. - **-a** Instructs **Elvis** to load all files named on the command line *simultaneously* with a separate window for each. - **-r** This is used for recovering an edit session after a crash. Each **Elvis** process uses a single "session file" to store the contents of all edit buffers. While **Elvis** is running, a flag is set near the beginning of the session file so that other **Elvis** processes won't try to use it at the same time. If an **Elvis** process dies abnormally, though, it will leave the session file lying around with that flag set; the **-r** flag allows **Elvis** to open a session file even if it is marked as being in use. - **-e** Causes **Elvis** to start each window in ex mode, instead of visual command mode. Invoking **Elvis** as "ex" implies this. - **-i** Causes **Elvis** to start each window in input mode, instead of visual command mode. Novice users may prefer this. - **-b** This sets the "binary" option, which causes new buffers to be marked as "readeol=binary". Without **-b**, **Elvis** will try to guess the format by examining the first hundred bytes or so of the file. - **-R** This sets the "defaultreadonly" option, which causes all new buffers to be marked as "readonly" so you won't accidentally overwrite the original file. - **-S** Sets security=safer, making **Elvis** paranoid about certain potentially harmful commands. The intent is to protect the user against writing by malicious scripts. The ./.exrc file and modelines are executed with security=safer temporarily regardless of whether **-S** was given. The **-S** flag is just used to make **Elvis** permanently paranoid, for the duration of this process. - **-SS** Sets security=restricted. This is more extreme security than "-S". The intent is to protect the system against reading by malicious users. - **-f** *session* Makes **Elvis** use the session file named "*session*" instead of the default file. Session files are discussed in the description of the **-r** flag, above. - **-o** *logfile* Redirects messages and trace information out to *logfile* instead of going to stdout/stderr as usual. This is useful under Windows95, where stdout/stderr don't show anywhere. If you're having trouble configuring WinElvis, try running "WinElvis -VVV -o log" and then you can find the trace and error messages in the file "log". - **-G** *gui* Makes **Elvis** use the named *gui* user interface instead of the default. To see a list of supported user interfaces, give the command "elvis -?". - **-c** *command* After loading the first file, interpret *command* as an ex command line. Several ex command lines can be sent in one line, separated by "\|". This is good to know, because only a single **-c***command* or **+***command* flag can be used. - **-s** Read an *ex* script from stdin, and execute it. This is similar to the **-Gscript** flag, except that **-s** has the additional side-effect of bypassing all initialization scripts. - **-t** *tag* Causes editing to begin at the location where the given *tag* is defined. See the [**ctags**(1)](/ctags/1.md) command for more information about tags. - **-w** *scroll* This sets the "window" option, which has very little effect in **Elvis**. - **-B** *blksize* If a new session file is created, this causes it to use blocks of size *blksize*. In addition, the following options are also supported to maintain backward compatibility, although their future use is discouraged. - **+***command* Like **-c** *command*, this causes the ex *command* to be executed after the first file is loaded. If the *command* is omitted, it is understood to be "$", which causes the cursor to move to the last line of the file. - **-** Like **-s**, this causes **Elvis** to read a script from stdin and execute it. ## TERMCAP INTERFACE The termcap interface is the one you'll use most often on non-graphic terminals. It looks and acts a heck of a lot like the traditional vi. The biggest addition is the support for multiple windows. For more information on how to use multiple windows, start **Elvis** and give the command ":help ^W". The short form of that help is: ^Ws splits the screen to form an additional window, ^Wq closes the window, and ^W^W switches the cursor from one window to another. If your terminal supports ANSI color escape sequences, then you can use the ":color" command to assign different colors to various fonts. You must assign a "normal" color first, e.g., ":color normal yellow on blue". The DOS and (text mode) Win32 version of the termcap interface support the mouse. The mouse behaves almost exactly like the X11 mouse, described below. The only differences are that the mouse can't be used to cut & paste to the clipboard, and on a two-button mouse you can simulate a middle button by simultaneously pressing the left and right buttons. ## X11 INTERFACE The x11 interface is used under X-Windows on UNIX systems. It provides a scrollbar and mouse support, and allows you to select which fonts to use. ### X11 Options To specify a normal font, use **-font** *fontname* or **-fn** *fontname.* Proportional fonts are not properly supported, but they aren't rejected with an error message either. If you don't specify a normal font, then **Elvis** will use a font named "fixed" by default. (This default can be overridden by a "set font=..." command in the *elvis.ini* file. The default *elvis.ini* file does this, making the new default font be 18-point Courier.) To specify a bold font, use **-fb** *fontname.* The specified font should have the same size character cell as the normal font, but **Elvis** does not verify this. If you don't specify a bold font, then **Elvis** will fake it by smearing the normal font rightward one pixel. To specify an italic font, use **-fi** *fontname.* The specified font should have the same size character cell as the normal font, but **Elvis** does not verify this. If you don't specify an italic font, then **Elvis** will fake it by sliding the top half of the normal font rightward one pixel. If you want to use Courier fonts, there is a shortcut: **-courier** *size* will use the normal, bold, and italic versions of the Courier font in the requested size. You can force **Elvis** to use only black and white with the **-mono** flag; this is the default if your display only has one bitplane. For color displays, **-fg** *color* and **-bg** *color* can be used to set the normal text color and the background color, respectively. **Elvis** has a built-in icon, which is generally a good thing. Some window managers won't allow you to assign a new icon to a program that has a built-in one, so **Elvis** has a **-noicon** flag which disables the built-in icon. The **-fork** client causes **Elvis** to run in the background, so that your shell prompt returns immediately. The **-client** option causes **Elvis** to look for an already-running **Elvis** process on the same X server and, if there is one, send the new arguments to it. This causes the old **Elvis** process to create new windows for file arguments. The new **Elvis** process then exits, leaving the old one to do the real work and allowing your shell program to prompt for a new command immediately. For the sake of uniformity, if **-client** fails to find an existing **Elvis** process, then a new **Elvis** process starts up as though you had used the **-fork** argument instead. The **-client** option is implemented in an interesting way: the client **Elvis** simply sends a series of ex commands to an existing window of the server **Elvis**. For each file name argument, the client **Elvis** sends a ":split *file*" command. For **-t***tag*, the client **Elvis** sends a ":stag *tag*" command. For **-c***command*, the client **Elvis** simply sends the *command*, and this results in some quirks. First, the server **Elvis** temporarily sets security=safer while the command is executed, for security reasons. Second, the command is executed by the server's existing window, not the new one, so (for example) "elvis -client -c 20 foo" creates a new window for the file "foo", and then moves the OLD WINDOW's cursor to line 20 of whatever file it was showing. ### X11 Mouse I've tried to reach a balance between the mouse behavior of [**xterm**(1)](/xterm/1.md) and what makes sense for an editor. To do this right, **Elvis** has to distinguish between clicking and dragging. Dragging the mouse always selects text. Dragging with button 1 pressed (usually the left button) selects characters, dragging with button 2 (the middle button) selects a rectangular area, and dragging with button 3 (usually the right button) selects whole lines. These operations correspond to **Elvis**' v, ^V, and V commands, respectively. When you release the button at the end of the drag, the selected text is immediately copied into an X11 cut buffer, so you can paste it into another application such as xterm. The text remains selected, so you can apply an operator command to it. Clicking button 1 cancels any pending selection, and moves the cursor to the clicked-on character. Clicking button 3 moves the cursor without canceling the pending selection; you can use this to extend a pending selection. Clicking button 2 "pastes" text from the X11 cut butter. If you're entering an ex command line, the text will be pasted into the command line as though you had typed it. If you're in visual command mode or input mode, the text will be pasted into your edit buffer. When pasting, it doesn't matter where you click in the window; **Elvis** always inserts the text at the position of the text cursor. Double-clicking button 1 simulates a ^\] keystroke, causing **Elvis** to perform tag lookup on the clicked-on word. If **Elvis** happens to be displaying an HTML document, then tag lookup pursues hypertext links so you can double-click on any underlined text to view the topic that describes that text. Double-clicking button 3 simulates a ^T keystroke, taking you back to where you did the last tag lookup. If your mouse has a scroll wheel, then **Elvis** can be configured to use it. For instructions on doing this, start **Elvis** and give the command ":howto scrollwheel". ## ENVIRONMENT VARIABLES **Elvis** has commands which can examine any environment variable. Because of this, a comprehensive list of environment variables isn't possible. The following list contains the environment variables which have hardcoded meaning in **Elvis**. - BASH or BASH\_VERSION Under Unix/Linux, **Elvis** tests for the presence of these variables to decide whether or not the /bin/sh shell supports process control, especially the ^Z key. The values of these variables doesn't matter, only the fact that they exist. - COLUMNS For the "termcap" user interface, this overrides the number of columns specified in the termcap/terminfo entry. - DISPLAY For the "x11" user interface, this indicates which display it should run on. - ELVISBG If set to "light" or "dark", its value is used as the default value for the background option. - ELVISGUI If set, its value is used to select the default user interface. You can still override it by using the **-G***gui* command line flag. - ELVISPATH If ELVISPATH is defined in the environment, then its value is copied into the elvispath option, which is a list of directories that **Elvis** should search through when looking for its support files. If ELVISPATH is undefined, **Elvis** will use a default list which usually includes the your home directory, and maybe a system-wide default location. - EXINIT If defined, the value of this option is typically interpreted as a series of EX commands when **Elvis** starts up. This behavior isn't built into **Elvis** though; it is handled by the standard *elvis.ini* file. - HOME This is your home directory. Its value is used as the default value for the home option, which is used in ~ substitution in file names. - HOMEDRIVE and HOMEPATH For Windows, if HOME is unset then HOMEDRIVE and HOMEPATH are checked; if they're set then they're concatenated to form the default value of the home option. - INCLUDE The "syntax" display mode uses this as a list of directories to search through when looking for a header file such as \. - LC\_ALL, LC\_MESSAGES, and LANG If LANG is defined, then **Elvis** will look for its message translations in *$LANG/elvis.msg*, and only use just plain *elvis.msg* if it can't find *$LANG/elvis.msg*. The LC\_MESSAGES and LC\_ALL environment variables work similarly, and take precedence over LANG. - LINES For the "termcap" user interface, this overrides the number of lines specified in the termcap/terminfo entry. - LOGNAME This stores your login name. It is used when reading via the FTP protocol, to choose the default login information. - OLDPWD This stores the name of the previous directory you were in. Its value is stored in the prevdir option, which is used for ~- substitution in file names. - PATH The usual search path for programs. - SESSIONPATH This is a list of directories where **Elvis** might be able to create the session file. **Elvis** uses the first writable directory from the list, and ignores all others. - SHELL or COMSPEC This is the name of your command-line interpreter. **Elvis** needs to know this so you can run programs from inside **Elvis**. SHELL is used in Unix/Linux, and COMSPEC is used in MS-DOS. - TAGPATH This is a path for *tags* files, used by the :tag command. For Microsoft it is semicolon-delimited; for all others it is colon-delimited. Each entry in the path can be either a filename, or the name of a directory containing a file named *tags*. - TERM For the termcap interface, this is the name of the terminal's termcap/terminfo entry. Also, if its value is "kvt" or ends with "-r" or "-rv", then the background option will be "light" by default; else it will be "dark". - TERMCAP For the termcap interface, this can either store the name of a termcap file or the actual contents of a termcap entry. - TMP This is where **Elvis** stores its temporary files other than session files. - WINDOWID **Elvis** uses this when choosing the default value of the background option. If the WINDOWID environment variable exists, then **Elvis** assumes it is running in an xterm-like terminal emulator, and those emulators usually have a light background. - XENVIRONMENT, XFILESEARCHPATH, and XUSERFILESEARCHPATH These are used by the "x11" user interface, when loading **Elvis**' resources. ## FILES - *~* This is your home directory. Whenever **Elvis** sees a ~ at the start of a pathname, it replaces the ~ with the value of the "home" option. The "home" option is initialized from the HOME environment variable; if HOME is unset then some operating systems will set "home" to the the directory where the **Elvis** program resides. - *lib* In this man-page, "lib" is a placeholder for the name of a directory in which **Elvis**' configuration files reside. The "elvispath" option's value is a list of directories that **Elvis** will check for each configuration file. - *elvis\*.ses* These are the default names for sessions files. Session files store the contents of all edit buffers for a given edit session. You can instruct **Elvis** to use a specific session file via the **-f***session* command-line flag. Note that sessions specified via **-f***session* normally reside in the current directory, but when **Elvis** chooses its own session file name, it will place it in the first writable directory named in the SESSIONPATH environment variable. - *tags* This file stores the tags for the files in a directory. It is used by the :tag command, among others. - *lib/elvis.ini* This file contains EX commands which are executed whenever **Elvis** starts up. **Elvis** searches through the ELVISPATH for the file. - *~/.exrc*, *~/.elvisrc*, or *~\\elvis.rc* The *.exrc* or *.elvisrc* (for UNIX) or *elvis.rc* (for non-UNIX) file in your home directory will generally be executed as a series of EX commands, unless the EXINIT environment variable is defined. This behavior isn't built into **Elvis** though; it is handled by the standard *elvis.ini* file. - *.exrc*, *.elvisrc*, or *elvis.rc* The *.exrc* or *.elvisrc* (for UNIX) or *elvis.rc* (for non-UNIX) file in the current directory is interpreted as a series of EX commands, but only if the **exrc** option has been set. This behavior isn't built into **Elvis**; it is handled by the standard *elvis.ini* file. - *lib/elvis.brf* This file contains EX commands which are executed **B**efore **R**eading a **F**ile. Typically this is used to distinguish a binary file from a text file by examining the file name extension of the file. The "readeol" option is then set accordingly. - *lib/elvis.arf* This file contains EX commands which are executed **A**fter **R**eading a **F**ile. If the current directory doesn't contain an *elvis.arf* file, then **Elvis** searches through the ELVISPATH for the file. Typically, this is used to set the **bufdisplay** option for a buffer, based on the file name extension of the file. - *lib/elvis.bwf* This file contains EX commands which are executed **B**efore **W**riting a **F**ile. Typically, *lib/elvis.bwf* is used to perform an RCS "checkout" command before writing a file. - *lib/elvis.lat* This contains a series of ":digraph" commands which set up the digraph table appropriately for the ISO Latin-1 symbol set. The *lib/elvis.ini* file executes this script during initialization, except under OS/2, MS-DOS, or text-mode Win32. - *lib/elvis.pc8* This contains a series of ":digraph" commands which set up the digraph table appropriately for the PC-8 symbol set. This is the normal symbol set for MS-DOS, OS/2, and text-mode Win32 (although the graphical Win32 uses *lib/elvis.lat*). The *lib/elvis.ini* file executes this script during initialization under MS-DOS. - *lib/elvis.msg* This file's data is used for mapping the **Elvis**' terse error messages into verbose messages. - *lib/elvistrs.msg* **Elvis** doesn't use this file directly; it is simply meant to serve as a resource from which you can extract the terse form of one of elvis' messages; you can then add the terse form and your own custom verbose form to the *lib/elvis.msg* file. - *lib/elvis.syn* This file controls how **Elvis**' "syntax" display mode highlights the text for a given language. - *lib/elvis.x11* This file contains a series of ex command. This file is sourced by *lib/elvis.ini* if **Elvis** is using its X11 user interface. It configures up the toolbar and default colors. - *lib/elvis.ali* This contains a set of aliases. If your copy of **Elvis** is configured to support aliases (i.e., if it isn't the MS-DOS version) then these aliases will be loaded automatically. They are partly intended to serve as examples of what aliases can do and how to write them, but mostly these aliases are intended to be truly useful. To see a list of the aliases, give the command ":alias". - *lib/elvis\*.html* These files contain the online documentation. - *lib/\*.man* These contain the man pages -- shorter summaries of the programs, with descriptions of the command-line flags. - *guix11/\*.xpm* and *guix11/elvis.xbm* These contain icon images for use with X-windows. The "elvis.xbm" image is a 2-color bitmap, and it is compiled into **Elvis**. The other files, such as "elvis.xpm," contain color images. The "insticon.sh" shell script (which is invoked as part of the "make install" operation) tries to copy these into appropriate directories. ## SEE ALSO [**ex**(1)](/ex/1.md), [**vi**(1)](/vi/1.md), [**ctags**(1)](/ctags/1.md) You should also view the on-line documentation, via ":help". ## AUTHOR Steve Kirkendall\ kirkenda@cs.pdx.edu