README
¶
Elvish: Expressive Programming Language + Versatile Interactive Shell
Elvish is a powerful scripting language and a versatile interactive shell. It runs on Linux, macOS, BSDs and Windows.
Elvish is pre-1.0. This means that the features set will change between versions, but it's quite stable for both scripting and interactive use.
User groups (all connected thanks to Matrix):
Documentation
Documentation for Elvish lives on the official website https://elv.sh, including:
-
Reference docs, including the language reference, the
elvishcommand, and all the modules in the standard library -
Blog posts, including release notes
The source for the documentation is in the website directory.
License
All source files use the BSD 2-clause license (see LICENSE), except for the following:
-
Files in pkg/diff and pkg/rpc are released under the BSD 3-clause license, since they are derived from Go's source code. See pkg/diff/LICENSE and pkg/rpc/LICENSE.
-
Files in pkg/persistent and its subdirectories are released under EPL 1.0, since they are partially derived from Clojure's source code. See pkg/persistent/LICENSE.
-
Files in pkg/md/spec are released under the Creative Commons CC-BY-SA 4.0 license, since they are derived from the CommonMark spec. See pkg/md/spec/LICENSE.
Building Elvish
Most users do not need to build Elvish from source. Prebuilt binaries for the latest commit are provided for Linux amd64, macOS amd64, macOS arm64, Windows amd64 and many other platforms.
To build Elvish from source, you need
-
A supported OS: Linux, {Free,Net,Open}BSD, macOS, or Windows 10. Windows 10 support is experimental.
-
Go >= 1.21.0.
To build Elvish from source, run one of the following commands:
go install src.elv.sh/cmd/elvish@master # Install latest commit
go install src.elv.sh/cmd/elvish@latest # Install latest released version
go install src.elv.sh/cmd/elvish@v0.18.0 # Install a specific version
Controlling the installation location
The
go install
command installs Elvish to $GOBIN; the binary name is elvish. You can
control the installation location by overriding $GOBIN, for example by
prepending env GOBIN=... to the go install command.
If $GOBIN is not set, the installation location defaults to $GOPATH/bin,
which in turn defaults to ~/go/bin if $GOPATH is also not set.
The installation directory is probably not in your OS's default $PATH. You
should either either add it to $PATH, or manually copy the Elvish binary to a
directory already in $PATH.
Building a variant
Elvish has several build variants with slightly different feature sets. For
example, the withpprof build variant has
profiling support.
These build variants are just alternative main packages. For example, to build
the withpprof variant, run the following command (change the part after @ to
get different versions):
go install src.elv.sh/cmd/withpprof/elvish@master
Building from a local source tree
If you are modifying Elvish's source code, you will want to clone Elvish's Git repository and build Elvish from the local source tree instead. To do this, run the following from the root of the source tree:
go install ./cmd/elvish
There is no need to specify a version like @master; when inside a source tree,
go install will always use the whatever source code is present.
See CONTRIBUTING.md for more notes for contributors.
Building with experimental plugin support
Elvish has experimental support for building and importing plugins, modules written in Go. It relies on Go's plugin support, which is only available on a few platforms.
Plugin support requires building Elvish with cgo. The official prebuilt binaries are built without cgo for compatibility and reproducibility, but by default the Go toolchain builds with cgo enabled.
If you have built Elvish from source on a platform with plugin support, your Elvish build probably already supports plugins. To force cgo to be used when building Elvish, you can do the following:
env CGO_ENABLED=1 go install ./cmd/elvish
To build a plugin, see this example.
Packaging Elvish
See PACKAGING.md for notes for packagers.
Contributing to Elvish
See CONTRIBUTING.md for notes for contributors.
Reporting security issues
See SECURITY.md for how to report security issues.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
elvish
Elvish is a cross-platform shell, supporting Linux, BSDs and Windows.
|
Elvish is a cross-platform shell, supporting Linux, BSDs and Windows. |
|
elvmdfmt
Command elvmdfmt reformats Markdown sources.
|
Command elvmdfmt reformats Markdown sources. |
|
nodaemon/elvish
Command elvish is an alternative main program of Elvish that does not include the daemon subprogram.
|
Command elvish is an alternative main program of Elvish that does not include the daemon subprogram. |
|
withpprof/elvish
Command elvish is an alternative main program of Elvish that supports writing pprof profiles.
|
Command elvish is an alternative main program of Elvish that supports writing pprof profiles. |
|
Package pkg is the root of packages that implement Elvish.
|
Package pkg is the root of packages that implement Elvish. |
|
buildinfo
Package buildinfo contains build information.
|
Package buildinfo contains build information. |
|
cli
Package cli implements a generic interactive line editor.
|
Package cli implements a generic interactive line editor. |
|
cli/clitest
Package clitest provides utilities for testing cli.App.
|
Package clitest provides utilities for testing cli.App. |
|
cli/examples/e3bc
Command e3bc ("Elvish-editor-enhanced bc") is a wrapper for the bc command that uses Elvish's cli library for an enhanced CLI experience.
|
Command e3bc ("Elvish-editor-enhanced bc") is a wrapper for the bc command that uses Elvish's cli library for an enhanced CLI experience. |
|
cli/examples/nav
Command nav runs the navigation mode of the line editor.
|
Command nav runs the navigation mode of the line editor. |
|
cli/examples/widget
Command widget allows manually testing a single widget.
|
Command widget allows manually testing a single widget. |
|
cli/histutil
Package histutil provides utilities for working with command history.
|
Package histutil provides utilities for working with command history. |
|
cli/lscolors
Package lscolors provides styling of filenames based on file features.
|
Package lscolors provides styling of filenames based on file features. |
|
cli/modes
Package mode implements modes, which are widgets tailored for a specific task.
|
Package mode implements modes, which are widgets tailored for a specific task. |
|
cli/prompt
Package prompt provides an implementation of the cli.Prompt interface.
|
Package prompt provides an implementation of the cli.Prompt interface. |
|
cli/term
Package term provides functionality for working with terminals.
|
Package term provides functionality for working with terminals. |
|
cli/tk
Package tk is the toolkit for the cli package.
|
Package tk is the toolkit for the cli package. |
|
daemon
Package daemon implements a service for mediating access to the data store, and its client.
|
Package daemon implements a service for mediating access to the data store, and its client. |
|
daemon/daemondefs
Package daemondefs contains definitions used for the daemon.
|
Package daemondefs contains definitions used for the daemon. |
|
daemon/internal/api
Package api defines types and constants useful for the API between the daemon service and client.
|
Package api defines types and constants useful for the API between the daemon service and client. |
|
diag
Package diag contains building blocks for formatting and processing diagnostic information.
|
Package diag contains building blocks for formatting and processing diagnostic information. |
|
edit
Package edit implements the line editor for Elvish.
|
Package edit implements the line editor for Elvish. |
|
edit/complete
Package complete implements the code completion algorithm for Elvish.
|
Package complete implements the code completion algorithm for Elvish. |
|
edit/filter
Package filter implements the Elvish filter DSL.
|
Package filter implements the Elvish filter DSL. |
|
edit/highlight
Package highlight provides an Elvish syntax highlighter.
|
Package highlight provides an Elvish syntax highlighter. |
|
elvdoc
Package elvdoc extracts doc comments of Elvish variables and functions.
|
Package elvdoc extracts doc comments of Elvish variables and functions. |
|
env
Package env keeps names of environment variables with special significance to Elvish.
|
Package env keeps names of environment variables with special significance to Elvish. |
|
errutil
Package errutil contains common error-related utilities.
|
Package errutil contains common error-related utilities. |
|
eval
Package eval handles evaluation of parsed Elvish code and provides runtime facilities.
|
Package eval handles evaluation of parsed Elvish code and provides runtime facilities. |
|
eval/errs
Package errs declares error types used as exception causes.
|
Package errs declares error types used as exception causes. |
|
eval/evaltest
Package evaltest supports testing the Elvish interpreter and libraries.
|
Package evaltest supports testing the Elvish interpreter and libraries. |
|
eval/vals
Package vals contains basic facilities for manipulating values used in the Elvish runtime.
|
Package vals contains basic facilities for manipulating values used in the Elvish runtime. |
|
eval/vars
Package vars contains basic types for manipulating Elvish variables.
|
Package vars contains basic types for manipulating Elvish variables. |
|
fsutil
Package fsutil provides filesystem utilities.
|
Package fsutil provides filesystem utilities. |
|
getopt
Package getopt implements a command-line argument parser.
|
Package getopt implements a command-line argument parser. |
|
glob
Package glob implements globbing for elvish.
|
Package glob implements globbing for elvish. |
|
logutil
Package logutil provides logging utilities.
|
Package logutil provides logging utilities. |
|
lsp
Package lsp implements a language server for Elvish.
|
Package lsp implements a language server for Elvish. |
|
md
Package md implements a Markdown parser.
|
Package md implements a Markdown parser. |
|
md/mdrun
Command mdrun can be used to test the md package.
|
Command mdrun can be used to test the md package. |
|
mods
Package mods collects standard library modules.
|
Package mods collects standard library modules. |
|
mods/daemon
Package daemon implements the builtin daemon: module.
|
Package daemon implements the builtin daemon: module. |
|
mods/doc
Package doc implements the doc: module.
|
Package doc implements the doc: module. |
|
mods/math
Package math exposes functionality from Go's math package as an elvish module.
|
Package math exposes functionality from Go's math package as an elvish module. |
|
mods/md
Package md exposes functionality from src.elv.sh/pkg/md.
|
Package md exposes functionality from src.elv.sh/pkg/md. |
|
mods/os
Package os exposes functionality from Go's os package as an Elvish module.
|
Package os exposes functionality from Go's os package as an Elvish module. |
|
mods/path
Package path provides functions for manipulating filesystem path names.
|
Package path provides functions for manipulating filesystem path names. |
|
mods/platform
Package platform exposes variables and functions that deal with the specific platform being run on, such as the OS name and CPU architecture.
|
Package platform exposes variables and functions that deal with the specific platform being run on, such as the OS name and CPU architecture. |
|
mods/re
Package re implements a regular expression module.
|
Package re implements a regular expression module. |
|
mods/runtime
Package runtime implements the runtime module.
|
Package runtime implements the runtime module. |
|
mods/str
Package str exposes functionality from Go's strings package as an Elvish module.
|
Package str exposes functionality from Go's strings package as an Elvish module. |
|
mods/unix
Package unix exports an Elvish namespace that contains variables and functions that deal with features unique to Unix-like operating systems.
|
Package unix exports an Elvish namespace that contains variables and functions that deal with features unique to Unix-like operating systems. |
|
must
Package must contains simple functions that panic on errors.
|
Package must contains simple functions that panic on errors. |
|
parse
Package parse implements the elvish parser.
|
Package parse implements the elvish parser. |
|
parse/cmpd
Package cmpd contains utilities for working with compound nodes.
|
Package cmpd contains utilities for working with compound nodes. |
|
parse/np
Package np provides utilities for working with node paths from a leaf of a parse tree to the root.
|
Package np provides utilities for working with node paths from a leaf of a parse tree to the root. |
|
parse/parseutil
Package parseutil contains utilities built on top of the parse package.
|
Package parseutil contains utilities built on top of the parse package. |
|
persistent
Package persistent contains subpackages for persistent data structures, similar to those of Clojure.
|
Package persistent contains subpackages for persistent data structures, similar to those of Clojure. |
|
persistent/hash
Package hash contains some common hash functions suitable for use in hash maps.
|
Package hash contains some common hash functions suitable for use in hash maps. |
|
persistent/hashmap
Package hashmap implements persistent hashmap.
|
Package hashmap implements persistent hashmap. |
|
persistent/list
Package list implements persistent list.
|
Package list implements persistent list. |
|
persistent/vector
Package vector implements persistent vector.
|
Package vector implements persistent vector. |
|
pprof
Package pprof adds profiling support to the Elvish program.
|
Package pprof adds profiling support to the Elvish program. |
|
prog
Package prog provides the entry point to Elvish.
|
Package prog provides the entry point to Elvish. |
|
prog/progtest
Package progtest provides a framework for testing subprograms.
|
Package progtest provides a framework for testing subprograms. |
|
rpc
Package rpc is a trimmed down version of net/rpc in the standard library.
|
Package rpc is a trimmed down version of net/rpc in the standard library. |
|
shell
Package shell is the entry point for the terminal interface of Elvish.
|
Package shell is the entry point for the terminal interface of Elvish. |
|
store
Package store defines the permanent storage service.
|
Package store defines the permanent storage service. |
|
store/storedefs
Package storedefs contains definitions of the store API.
|
Package storedefs contains definitions of the store API. |
|
store/storetest
Package storetest keeps test suites against storedefs.Store.
|
Package storetest keeps test suites against storedefs.Store. |
|
strutil
Package strutil provides string utilities.
|
Package strutil provides string utilities. |
|
sys
Package sys provide system utilities with the same API across OSes.
|
Package sys provide system utilities with the same API across OSes. |
|
sys/eunix
Package eunix provides extra Unix-specific system utilities.
|
Package eunix provides extra Unix-specific system utilities. |
|
sys/ewindows
Package ewindows provides extra Windows-specific system utilities.
|
Package ewindows provides extra Windows-specific system utilities. |
|
testutil
Package testutil contains common test utilities.
|
Package testutil contains common test utilities. |
|
transcript
Package transcript contains utilities for working with Elvish transcripts.
|
Package transcript contains utilities for working with Elvish transcripts. |
|
tt
Package tt supports table-driven tests with little boilerplate.
|
Package tt supports table-driven tests with little boilerplate. |
|
ui
Package ui contains types that may be used by different editor frontends.
|
Package ui contains types that may be used by different editor frontends. |
|
ui/styledown
Styledown is a simple markup language for representing styled text.
|
Styledown is a simple markup language for representing styled text. |
|
wcwidth
Package wcwidth provides utilities for determining the column width of characters when displayed on the terminal.
|
Package wcwidth provides utilities for determining the column width of characters when displayed on the terminal. |
|
website
module
|