Skip to content

EvergreenManual

Jump to bottom
Phil Norman edited this page May 28, 2021 · 10 revisions

Evergreen User Manual

Note: the keystrokes in this manual correspond to the Linux version. Some keystrokes may be slightly different on Cygwin or Mac OS, to better fit that platform.

Workspaces

Some simple text editors work primarily on one file at a time. Some IDEs effectively require that your project be created and managed by them. Evergreen falls somewhere in between. If you work primarily with single files, Evergreen may seem cumbersome; if, on the other hand, you primarily work on projects at least large enough to have more than one directory of source, you should find Evergreen comfortably lightweight.

You will, however, need to learn about and create "workspaces". Creating a workspace is basically just telling Evergreen the root directory of a project. That's probably the directory with the top-level build file (Makefile or build.xml or whatever). Evergreen will automatically choose a name for the workspace, but you can override it; useful if your projects are all stored in Subversion repositories and you choose the checked-out 'trunk' directory as the root of each one. The name is for your convenience, and you can change it later.

A workspace is also a way to work on multiple projects in the same editor. You can have as many workspaces as you like, and each will have its own tab in the main window.

To create a workspace, choose "Workspace" > "New Workspace..." from the menu. A dialog will appear where you can choose a root directory, maybe customize the workspace's name, and maybe choose a custom build target (described later).

Each workspace gets a tab. You can switch between workspaces by clicking on the tab or, for the first ten workspaces, jump to the n th workspace with alt-n (where n goes from 1 to 9 and then to 0, so that keyboard order matches tab order). You can also move to the previous and next workspaces from the keyboard with control-shift-[ and control-shift-].

If you need to change a workspace's root, name, or build target at any time, choose "Workspace" > "Edit Workspace..." from the menu. This option is also available by right-clicking on a workspace's tab.

If you no longer need a workspace, select that workspace and choose "Workspace" > "Close Workspace" from the menu. This option is also available by right-clicking on a workspace's tab. Closing a workspace does not affect the files and directories in that workspace; it simply makes Evergreen forget about them. Everything is still there on disk unless you remove it yourself.

Workspace configuration is stored in Evergreen's dot-directory in your home directory, not under the workspace root itself, so you don't need to worry about telling your version control system to ignore anything.

If you want a workspace's root to be a directory that contains a collection of related projects, it can sometimes be useful to create a simple Makefile to build all the contained projects.

Workspace Indexing

One reason why Evergreen asks you to name workspaces up front is that it indexes all the source files. It doesn't index their content, just their names. The index is updated when you start Evergreen, and when you manually ask for a rescan. Additionally, if your operating system supports applications being notified of filesystem changes, any pertinent changes within the workspace will trigger a partial rescan. Note that such support may vary by filesystem - for example, normal filesystems on Linux support this, but some Fuse-based filesystems do not.

To ask Evergreen to rescan a workspace, select that workspace and choose "Workspace" > "Rescan Files" from the menu. This option is also available by right-clicking on a workspace's tab.

Any dialog whose functionality relies on the index will also offer a "Rescan" button, accessible from the keyboard with alt-r.

When indexing, symbolic links are followed, even if they point outside the workspace directory. This can be useful when working on a few small parts of a very large source tree, as it allows you to use symlinks to map certain sub-trees into an Evergreen workspace, while avoiding the cost of a recursive scan of the entire tree.

There's more about configuring indexing later.

Opening Files

There are several ways to open files in Evergreen.

Open Quickly

To open a file by name, choose "File" > "Open Quickly..." from the menu, accessible from the keyboard with control-o. This option is also available by right-clicking in a file.

The Open Quickly dialog shows the files in the workspace whose names match the regular expression you type. Hitting return will open any selected files in the list.

If you Open Quickly with a non-empty selection, the regular expression will default to the contents of the selection. This is handy if you select the name of a Java class, say, and know that it's stored in a file with a matching name.

Find in Files

To open a file containing a search string, choose "Find" > "Find in Files...", accessible from the keyboard with control-shift-g. This option is also available by right-clicking in a file. If the selection is non-empty, the regular expression will default to the contents of the selection.

You can filter on file content or file name in the Find in Files dialog, so if you want to find "some_function" but only in .cpp files, for example, that's trivial.

The results are shown as a tree with branches indicating the directory structure, and (assuming you actually specified a regular expression for the files' content) with a leaf for every match. Click on a match to open the file and jump to the match. The regular expression you used in the Find in Files dialog will automatically be applied to the file, so you'll be able to use the usual navigation keystrokes to move to the other matches in that file without needing to return to the Find in Files dialog.

Files that seem to contain a definition for the search term will have their name shown in bold in the results, so the definition stands out from the uses.

Creating a New File

To create and open a new "File" > "New File...", accessible from the keyboard with control-n. A dialog will prompt you for a pathname, defaulting to the directory containing the current file (or the root of the workspace if there is no current file).

If the file already exists, you're alerted to the fact and the file is opened anyway. Otherwise, the file is created.

The script evergreen-boilerplate-generator is run to automatically fill the new file with default content (such as the basic "public class X { }" boilerplate in Java). There's more on configuring boilerplate generation later.

Regular Expressions

Evergreen uses regular expressions all over; if it's asking for input, chances are it's asking for a regular expression. You can learn about the specific dialect used by reading Sun's Pattern documentation (also accessible by choosing "Documentation" > "Regular Expression Documentation" from the menu).

If you enter an all-lowercase regular expression, Evergreen assumes you want a case-insensitive match. Any use of uppercase implies that a case-sensitive match. You can use (?i) or (?-i) to explicitly select case (in-)sensitivity.

Note that the use of regular expressions even for filename matching (where you might otherwise expect to see shell-like "glob" patterns) means that . matches any character (use \. for glob behavior), * matches zero or more of the preceding character (use .*), and ? matches zero or one of the preceding character (use .). The regular expression anchors ^ and $ apply to the whole path, so $ is mainly useful for matching only extensions, and / is often useful if you're trying to match a particular path segment. Don't worry too much about all this: in practice, you won't usually need to worry about this; most of the time, you'll just type a few literal characters.

Navigation

Basic Navigation

The arrow keys move the caret by one character in the relevant direction. To move left or right by one word, use control-left and control-right.

The home and end keys move to the beginning and end of the current line. To move to the beginning or end of the current file, use control-home and control-end.

If the caret is next to a bracket character, control-5 will jump to the matching bracket (like % in Vim).

The page up and page down keys move the scroll bar, but not the caret.

If you've lost the caret, "Find" > "Scroll to Selection", accessible from the keyboard with control-j, will take you back to it. It will also briefly display a massive red arrow pointing to where the caret is.

Find

To search for a string, choose "Find" > "Find..." from the menu, accessible with control-f from the keyboard. If there's a selection, it's used as the search term. Regardless, you can edit the regular expression in the text field that appears at the bottom of the main window.

All matches in the current file will be highlighted, and tiny notches next to the scroll bar will show the distribution of matches throughout the file. (You can click on a notch to jump to that match.)

Most conveniently, the keys either side of 'f' can be used to rapidly scan backwards and forwards through the matches. Use control-d to move to the previous match, and control-g to move to the next match. These operations don't wrap, so you can tell when you've hit the first or last match. (These operations are also available from the "Find" menu, but they're only there to help you learn the keystrokes.)

You can keep a find active by dismissing the text field with return. (Pressing control-d or control-g also dismisses the text field while keeping the find active.)

You can cancel the find (and remove the highlighting) by dismissing the text field with escape. While a find is active, the matches will be updated as you edit the file. The status bar will show the currently active find, and the current number of matches.

Symbols (Tags)

If Exuberant Ctags is installed, and the language you're editing is supported by it, Evergreen will show a tree on the right-hand side of the main window. You can click on an item in the tree to jump straight to the corresponding line in the source.

The shape of the icons next to the names tell you what kind of symbol they represent: classes (circles), methods/functions (squares), and fields/variables (triangles). Icons for abstract classes or methods are hollow.

The color of the icons denote their symbol's accessibility: public (green), protected (orange), private (red), and default or unknown accessibilities (gray).

Public static symbols have their names in bold.

If you have a "tags" file in the workspace root, you can also jump to a tag in a different file. Choose "Find" > "Go to Tag" from the menu, accessible with control-t from the keyboard. If there's a selection, it's used as the search term. Otherwise, the word around the caret is used. If there's a single match, you're taken straight to it. If there are multiple matches, you're shown a dialog from which you can choose.

Evergreen currently has no support for creating or updating the "tags" file itself, though you could create an external tool as a work-around.

Go to Line

Choose "Find" > "Go to Line...", accessible from the keyboard with control-l, to jump straight to a given line number.

Selection

If a given keystroke moves the caret (see Basic Navigation), holding down shift at the same time will extend the selection to the new caret position.

You can also set the selection by pressing the left mouse button at the caret position at one end of the desired selection and dragging to the other caret position. Alternatively (and more conveniently if you wish to select a large amount of text), you can place the caret at one end of the desired selection, and shift-click at the other caret position.

To select the entire file, use "Edit" > "Select All", accessible from the keyboard with control-a.

Editing

Basic Editing

Typing characters inserts them at the caret position. If there's a selection, typing replaces the selection.

The backspace key removes the character to the left of the caret (or removes the selection). To remove everything to the beginning of the current line, use alt-backspace.

To remove the preceding run of whitespace or non-whitespace, use control-backspace. (This is deliberately less eager than Unix shells' control-w so that you can use it both to delete words and to tidy up whitespace.)

The delete key removes the character to the right of the caret (or removes the selection). Use control-shift-delete or control-shift-k to remove the entire line.

The usual control-x, control-c, control-v behaviors (cut, copy, and paste) apply. For the benefit of Windows users, shift-del, ctrl-insert and shift-insert also cut, copy and paste on all platforms.

Undo with control-z, redo with control-shift-z. Undo is unlimited, but isn't persistent: if you quit, you lose your undo history.

To join the next line onto the end of the current line, use control-shift-j.

Find/Replace

To perform a find and replace operation on the current file, choose "Find" > "Find/Replace...", accessible from the keyboard with control-r.

The replacement string in the "Replace With:" field can either be a simple literal, or can refer to the capturing groups in the "Find:" regular expression using $n where n is the index of the capturing group, starting with $1. (Whether or not your regular expression contains capturing groups, $0 always refers to the entire match.)

If there's a selection that spans multiple lines, the operation will only apply to those lines. If there's a selection within a single line, that's taken to be the search term.

Matching lines are shown in one list, with the matching substring highlighted. Suggested replacements are shown in a second list, with the replacement substring highlighted. Hovering over a line in either list brings up a tool tip showing the explicit capturing groups (along the lines of $1="red", $2="0xff0000"). Put together, these features make it easy to experiment until you've got the right regular expression and the right replacement string.

Indentation

Evergreen will auto-indent as you edit. The exact details vary from language to language.

If for some reason a line's indentation needs to be fixed, use "Edit" > "Correct Indentation", accessible from the keyboard with control-i.

When pasting, Evergreen will reindent the pasted text.

Sorting

To sort multiple lines, select them and choose "Tools" > "Sort". To remove any duplicates at the same time, choose "Tools" > "Sort and Remove Duplicates".

Windows

Each workspace's tab contains zero or more "windows" for editing files. When a new file is opened in a given workspace, a new window is inserted taking half the space of the current largest window.

You can cause a window to expand to take up all available space (shrinking all other windows) by double-clicking on the title bar, or by choosing "View" > "Expand Window", accessible from the keyboard with control-1.

You can drag a window's title bar to make the window take more or less space.

A window's title bar shows the file's pathname on the left, and has a close button on the right. You can also use "File" > "Close", accessible from the keyboard with control-w. A file whose content has been edited since it was last saved has a red close button, and you'll be shown a patch and asked if you really want to throw away those changes.

A window's title bar may also contain a double-headed arrow next to the close button. The presence of this button indicates that the file has a counterpart file (if it's a C++ source file, probably the corresponding header file, for example). To open the counterpart file, click the button, or choose "View" > "Switch to Header/Source", accessible from the keyboard with control-shift-p.

To cycle back and forth between windows, click on them with the mouse, or use "View" > "Next Window", accessible from the keyboard with control-, and "View" > "Previous Window", accessible from the keyboard with control-shift-.

Building Projects

Basic Building

To build the current project, use "Workspace" > "Build Project", accessible from the keyboard with control-b. Evergreen will search up from the directory containing the current file until it finds build instructions (by default, Makefile or build.xml). It will run the appropriate build tool in that directory. This works great if you have a single file of build instructions, at the top of your project. If you have, say, makefiles at multiple levels, you'll have to bear in mind that what file you have selected when you start a build will influence which subtree of your project is rebuilt. This is sometimes useful (because projects large enough to have multiple sets of build instructions are usually large enough to be too expensive to totally rebuild), but it's sometimes annoying (because at some point you may want to rebuild a larger part of the system than the part you're currently working on). Two common workarounds are to have the top-level makefile open, and start a build from there when need be, or to use the shell to do top-level builds.

To build the equivalent "test" target, use "Workspace" > "Build and Test Project", accessible from the keyboard with control-shift-b. This behaves the same as "Build Project" but adds " test" to the end of the command line.

To see what build instructions Evergreen would use (or to edit them), choose "File" > "Open Makefile".

Build output appears in a new window. Error messages that use grep(1)-style filename:line: output will be hyperlinked so you can jump straight to the source. You can clear the build output and close the window with "Tools" > "Clear Errors", accessible from the keyboard with control-k.

There's more on configuring custom build tools later.

Checking For Lint

Many languages have a "lint" tool that checks source code for problems that the compiler may not warn about. Some groups use lint tools to check for adherence to a particular coding style. Evergreen will run a lint check on the current file if you choose "Tools" > "Check For Lint", accessible from the keyboard with control-shift-l. Any output will appear in a build output window, and can be disposed of in the usual manner. There's more on configuring custom lint checkers later.

Command-line Use

Launching Evergreen

Normally, you'll have an icon on your desktop, your Applications menu, or in your Applications folder (depending on platform) from which you can launch Evergreen, but you can also use the evergreen command from the shell.

Opening Files

The evergreen command also lets you tell a running instance to open a file. You can supply addresses such as "file.cpp:12" in order to go straight to line 12 of "file.cpp". To facilitate the easy pasting of entire grep(1) matches collected via selection of the entire line, anything after the address is ignored. For this reason, it is not possible to open more than one file in one command.

The --block option makes the evergreen command wait until the user closes the file that was opened. This is useful if you're trying to have a program call on Evergreen to edit a file, for example by setting the EDITOR environment variable. Another command, edit-and-block is provided for use with crontab(1), which is too stupid to cope with an editor that takes arguments.

Creating a new Workspace

Use evergreen --new-workspace <root> <name> to create a workspace with the given root directory and name.

Closing a Workspace

Use evergreen --close-workspace <name> to close the workspace with the given name.

Documentation

The "Documentation" menu contains links to various bits of useful documentation on the web, that will open in your regular browser.

Configuration

Preferences

There's a preferences dialog available by choosing "Edit" > "Preferences...".

Scripts

Some of the later sections describe customizing Evergreen using external scripts. These can be written in any language you like or can be native binaries for all Evergreen cares. Most communication is via environment variables. Unless otherwise stated, you can expect to have access to:

  • EVERGREEN_CURRENT_DIRECTORY: The equivalent of dirname $EVERGREEN_CURRENT_FILENAME.
  • EVERGREEN_CURRENT_FILENAME: The full pathname of the file containing the caret, if there is a current file.
  • EVERGREEN_CURRENT_LINE_NUMBER: The line number containing the caret, counted from 1, if there is a current file.
  • EVERGREEN_CURRENT_CHAR_OFFSET: The offset (from 0) of the current caret position within the current line. The offset is measured in complete characters, not bytes.
  • EVERGREEN_SELECTION_END_LINE_NUMBER: The line number containing the end of the selection. If there is no selection, this is the same as EVERGREEN_CURRENT_LINE_NUMBER.
  • EVERGREEN_SELECTION_END_CHAR_OFFSET: The offset (from 0) of the end of the selection, measured in full characters. If there is no selection, this is the same as EVERGREEN_CURRENT_CHAR_OFFSET.
  • EVERGREEN_CURRENT_SELECTION: The current selection, if less than 1024 characters. This is a convenience for simple tools/scripts. If you really want to work on the selection, ask for the whole selection to be passed to you on standard input.
  • EVERGREEN_CURRENT_WORD: The word containing the caret.
  • EVERGREEN_LAUNCHER: The path to evergreen, so you can ask it to open files. (See Command-line Use.) This is safer than assuming that evergreen is on the path.
  • EVERGREEN_WORKSPACE_ROOT: The root directory of the workspace the command was run from.

Note that those environment variables relating to a file won't exist if there is no current file.

Properties

Many of the configuration options not presented in the UI are available by setting 'properties'. These are read from the ~/.e.edit.Edit/evergreen.properties file. If you want to keep your local modifications separate, or share them more conveniently, you can include other files. Say you have a /home/enh/config/evergreen.properties file, just add a line </home/enh/config/evergreen.properties to the main file.

Additionally, Evergreen will try to read /usr/lib/software.jessies.org/evergreen/evergreen.properties and then /usr/local/software.jessies.org/evergreen/evergreen.properties to pick up system-wide configuration. Your user-specific configuration is read last, so your settings override anything else.

There is a list of supported properties.

Advanced Indexing

If Evergreen finds an executable called echo-local-directories-evergreen-should-not-index on your path, it will be run at start-up. The output is interpreted as a regular expression pattern per line describing the names of directories that Evergreen shouldn't scan when indexing your workspace. Evergreen already knows about most version control systems and about the autotools directories, so you shouldn't have to worry about those. Evergreen also assumes that there's nothing interesting in "dot directories" (directories whose names begin with a "."). The ability to add custom directory patterns is useful in a variety of cases. The most common example is when your object files (or your test data, or whatever it is you don't want Evergreen to index/search) live under your workspace root but are segregated into directories with distinctive names. You should make sure Evergreen knows the name of the directories containing such files, for performance.

If you can't help Evergreen out, perhaps because keep your object files in the same directory as your source, Evergreen will ignore each file one by one. This has a similar end result, but it's much less efficient, and it's your time you're wasting.

Evergreen already knows about most common build artifacts (object files and their friends) and recognizes them by their filename extension. If you have an unusual one (and it isn't already hidden in a directory that Evergreen won't scan) you can add the extension to Evergreen's list in the GUI preferences dialog.

Evergreen will also look for echo-local-extensions-evergreen-should-not-index on your path. The output is interpreted as a list of filename endings. Filenames whose endings are in the list are not indexed. Normally you'd use the preferences dialog for this, but the script lets you set up site-wide preferences.

If you think the extension is a common one that Evergreen should automatically ignore, please let us know so that we can add it to the built-in list so everyone benefits.

Both echo-local-directories-evergreen-should-not-index and echo-local-extensions-evergreen-should-not-index are run once for each workspace, when the workspace is scanned or rescanned, with a current directory of the workspace root.

Lint Checkers

If you dislike Evergreen's default choice of lint checker for a given language, or have a lint checker for a language Evergreen doesn't have a default for, you can override or supplement Evergreen's choices. Say you have a C++ static analysis tool you want Evergreen to use. Add the property C++.lintChecker=cpplint (include any necessary arguments). The bit before the "." is the value shown for File Type in the File Properties dialog. If lint checking for HTML weren't built in, for example, the current behavior could be specified with XML.lintChecker=tidy -qe. Note that we use the file type mode's name ("XML") rather than, say, the specific file extension or specific dialect.

Boilerplate Generation

You can set the boilerplateGenerator property to point to your own script. Use /usr/bin/evergreen-boilerplate-generator as a template, but don't be tempted to edit it in place, because it will be overwritten each time you install a newer version of Evergreen. Note that currently, a single script must handle all file types (though you could make that script call solely responsible for deciding which of a variety of other scripts to call to handle the current case).

Right-hand Margins

You can tell Evergreen to draw a right-hand margin at any column position (when using a fixed font) on a per-file-type basis. To set the margin to 132 columns for Java, say, set Java.margin=132. As with lint checkers above, use the file type mode's name. As an extension, you can set default.margin to cover all file types except those you've explicitly set. As a further extension, you can set the margin to -1 to disable the margin for the file type in question (or "default").

Build Tools

If you don't use make(1) or ant(1), Evergreen has limited support for alternatives. You can set the build.<file>=<tool> properties to educate it.

For example, to add support for calling mk(1) when Evergreen finds a mkfile, you'd use build.mkfile=mk.

Your tool will be started in the directory containing the build instructions. You may find it necessary to actually call a script that works out the appropriate arguments for the real build tool.

If you think the tool is a common one that Evergreen should automatically support, please let us know so that we can add it to the built-in list so everyone benefits.

External Tools

You can add your own tools to the "Tools" menu, and optionally to the pop-up menu.

On launch, Evergreen scans the ~/.e.edit.Edit/tools/ directory. The scan is recursive and will follow symbolic links (so you can keep your tools elsewhere, under version control). The files are sorted by filename before being presented to the user, so use the Unix rc.d trick of prepending a number if you want meaningful names but non-alphabetic ordering.

Additionally, Evergreen will try to scan /usr/lib/software.jessies.org/evergreen/tools/ and then /usr/local/software.jessies.org/evergreen/tools/ to pick up system-wide configuration.

Each file is parsed as a newline-separated sequence of key=value pairs.

A file containing just the line name=<separator> will appear as a separator.

The minimum information needed for an actual tool is a name and a command. You can add a keyboard equivalent if you like, either a function key or a single character; in the latter case, the keystroke will be control-shift-letter. To add a mnemonic, insert an underscore before the relevant character in the name property.

All tools and separators appear on the "Tools" menu. There's plenty of room there, but space on the pop-up menu is at a premium. The boolean showOnPopUpMenu determines whether a given tool or separator also appears on the pop-up menu.

The first character of the command can be '!', '|', '<', or '>':

'!' simply executes the command with nothing on stdin, and stdout/stderr sent to a "Build Output" window. '|' executes the command with stdin containing the selection (or the whole document if there's no selection), and replaces the selection with (or inserts) stdout/stderr. '<' executes the command with nothing on stdin, and stdout/stderr inserted at the caret. '>' executes the command with stdin containing the selection (or the whole document if there's no selection), and stdout/stderr sent to a "Build Output" window.

Here's what you could store in a file (wc.tool, say) to make f5 run wc on the current file:

name=wc current file
command=!wc $EVERGREEN_CURRENT_FILENAME
keyboardEquivalent=f5

If you work on scripts that take no arguments, and would like to be able to run them from the editor (with clickable links in any stack traces that are output, taking you back to the source), you can use something like this:

name=Execute Current File
command=!$EVERGREEN_CURRENT_FILENAME
keyboardEquivalent=f3

Here's how you'd make control-shift-e insert the current date (with mnemonic 'D'):

name=Insert _Date
command=<date --iso
keyboardEquivalent=e

There are also other boolean settings. You can cause the "some files are unsaved" dialog to appear by setting checkEverythingSaved=true. You can disable a tool if there's no current file with needsFile=true.

If you have a suitable icon in, say, /usr/share/icons/Tango/24x24/apps/user-info.png, you can set it with icon=/usr/share/icons/Tango/24x24/apps/user-info.png. Additionally, on Linux you can request one of the GTK+ stock icons thus: stockIcon=gtk-clear.

Clone this wiki locally