1<!-- toc number-sections --> 2 3# Introduction 4 5The Elvish command, `elvish`, contains the Elvish shell and is the main way for 6using the Elvish programming language. This documentation describes its behavior 7that is not part of the [language](language.html) or any of the standard 8modules. 9 10# Using Elvish interactively 11 12Invoking Elvish with no argument runs it in **interactive mode** (unless there 13are flags that suppress this behavior). 14 15In this mode, Elvish runs a REPL 16([read-eval-print loop](https://en.wikipedia.org/wiki/Read–eval–print_loop)) 17that evaluates input continuously. The "read" part of the REPL is a rich 18interactive editor, and its API is exposed by the [`edit:` module](edit.html). 19Each unit of code read is executed as a [code chunk](language.html#code-chunk). 20 21## RC file 22 23Before the REPL starts, Elvish will execute the **RC file**. Its path is 24determined as follows: 25 26- If the legacy `~/.elvish/rc.elv` exists, it is used (this will be ignored in 27 a future version). 28 29- Otherwise: 30 31 - On UNIX (including macOS), `$XDG_CONFIG_HOME/elvish/rc.elv` is used, 32 defaulting to `~/.config/elvish/rc.elv` if `$XDG_CONFIG_HOME` is unset 33 or empty. 34 35 - On Windows, `%AppData%\elvish\rc.elv` is used. 36 37If the RC file doesn't exist, Elvish does not execute any RC file. 38 39## Database file 40 41Elvish in interactive mode uses a database file to keep command and directory 42history. Its path is determined as follows: 43 44- If the legacy `~/.elvish/db` exists, it is used (this will be ignored in a 45 future version). 46 47- Otherwise: 48 49 - On UNIX (including macOS), `$XDG_DATA_HOME/elvish/db.bolt` is used, 50 defaulting to `~/.local/state/elvish/db.bolt` if `$XDG_DATA_HOME` is 51 unset or empty. 52 53 - On Windows, `%LocalAppData%\elvish\db.bolt` is used. 54 55# Running a script 56 57Invoking Elvish with one or more arguments will cause Elvish to execute a script 58(unless there are flags that suppress this behavior). 59 60If the `-c` flag is given, the first argument is executed as a single 61[code chunk](language.html#code-chunk). 62 63If the `-c` flag is not given, the first argument is taken as a filename, and 64the content of the file is executed as a single code chunk. 65 66The remaining arguments are put in [`$args`](builtin.html#args). 67 68# Module search directories 69 70When importing [modules](language.html#modules), Elvish searches the following 71directories: 72 73- On UNIX: 74 75 1. `$XDG_CONFIG_HOME/elvish/lib`, defaulting to `~/.config/elvish/lib` if 76 `$XDG_CONFIG_HOME` is unset or empty; 77 78 2. `$XDG_DATA_HOME/elvish/lib`, defaulting to `~/.local/share/elvish/lib` if 79 `$XDG_DATA_HOME` is unset or empty; 80 81 3. Paths specified in the colon-delimited `$XDG_DATA_DIRS`, followed by 82 `elvish/lib`, defaulting to `/usr/local/share/elvish/lib` and 83 `/usr/share/elvish/lib` if `$XDG_DATA_DIRS` is unset or empty. 84 85- On Windows: `%AppData%\elvish\lib`, followed by `%LocalAppData%\elvish\lib`. 86 87If the legacy `~/.elvish/lib` directory exists, it is also searched. 88 89# Other command-line flags 90 91Running `elvish -help` lists all supported command-line flags, which are not 92repeated here. 93