jEdit SshConsole plugin

Version 1.0.6 (May 31 2013)

Alan Ezust

Table of Contents


This plugin is designed to allow you to easily compile files you are editing remotely via sftp:// and parse the errors for ErrorList. It has no user interface of its own, because it is an extension of three other plugins: Console, FTP, and ErrorList. It also uses a dockable jEdit File System Browser or ProjectViewer for navigation.

SshConsole has no option pane of its own. The customizations possible for this plugin are in Console or ErrorList options.

Console provides jEdit with a dockable command line interface to the System Shell and the BeanShell, and an open interface for adding new shells. SshConsole adds a jEdit Shell Service to Console called ssh.

Console parses the output of the commands through its own error parsers which are configurable from Plugin Options - Console - Error Parsers. When Console adds detected errors to the ErrorList dockable, you can click on the error, and jEdit will open the remote file for you if necessary, and position your caret at the error location.

The FTP plugin defines a virtual file system (VFS) called "sftp://", which allows the user to make secure sftp:// connections to remote hosts, and browse their file systems using jEdit's File System Browser, also known as FSB or VFSBrowser. At any time, the user can select, and then manipulate selected files from the FSB or jEdit. Since the FTP plugin handles prompting and remembering username/passwords, the SshConsole initially tries to to ssh into the same host using the same port and creds as the current buffer's path.


Initially, the SshConsole does not know where to connect. If you activate the Console and select the "Ssh" shell from the combobox, you will initially see a prompt like this:

[no sftp:// connections?] >

At this point, any commands you type will be ignored. To tell the plugin to connect somewhere, and open a remote file.

Once you are editing a remote file, type something into SshConsole and you will see your response from the server's shell.

Instructions for first-time users:

  1. Go to Plugin Options - Console - System Shell and find the section Events to Chdir.

    Ssh can also be considered a System Shell since it can be used for executing system commands.

    SshConsole always responds to When TextArea buffer dir changes, cd to it, regardless of the checkbox setting here. This will help ensure that SshConsole is always executing commands in the buffer's directory.

    SshConsole can also respond to the other checked events, (project change, or tree node selection) if you check those options here.

  2. Go to Plugin Options - Console - Error Matchers and disable all error matchers that you do not need. Having too many or too general matchers enabled here may result in false positives in ErrorList.

  3. Show the dockable FSB: Utilities - File System Browser .

  4. Plugins - SshConsole - Show SshConsole

  5. With FSB: navigate to a remote host by entering a path that begins with sftp://.

  6. If this is your first time connecting, Enter your user/password/key/passphrase there.

  7. After you're connected, if you plan to connect often to this host, Favorites - Add to Favorites from the FSB.

  8. With FSB: Open the remote file that you want to compile.

  9. Enter commands in the ssh console. Initially, it will connect and show you the message of the day.

  10. Open a buffer in a different folder, or invoke a console chdir event. Notice that "cd" commands get sent over to the remote machine in response to certain events.

  11. Compile something with errors in it.

  12. Look at the ErrorList dockable. Click on an error in the dockable.

If later, you connect to a different remote sftp host and open a file from there, then the next time SshConsole executes a command, it should logout of the old ssh session, create a new shell connection to the same host you just logged into via sftp, and send your shell commands there.

ProjectViewer Integration

ProjectViewer permits you to have projects rooted at a sftp:// directory. If you switch to such a project and Plugin Options - Console - System Shell - On project change, cd to PV root dir is checked, then the ssh shell should be selected in Console and the project root directory should be the current working directory.

The Console actions, Compile Project and Run Project also automatically switch to use the most appropriate shell (ssh) before changing to the project root directory, when building/running an sftp project.

Furthermore, the node selection events that Console responds to from the File System Browser are also sent from the ProjectViewer tree and passed onto the ssh shell when the chdir event option is checked.

Job Control

Sending Ctrl-D (EOF), or Ctrl-Z (DETACH), work the way you would expect them to on a unix shell. EOF will close the connection and terminate the corresponding stream task. To send a Ctrl-C, click on the "X" button in the Console pane (Ctrl-C is still a "copy to clipboard" shortcut). Other control keys typed during the execution of your program are not sent to the remote host.

Built-in Commands

The following built-in commands which work in the System shell also work in the ssh shell:

  • %browse [path]

    tells your FSB to browse a given relative path, defaults to your current working directory.

  • %edit fileName

    tells jEdit to open given remote file as a buffer in the View's EditPane. Relative paths are possible here.


If you are getting lots of false errors in ErrorList which do not correspond to filenames and line numbers, this could mean you have too many or too general Console error matchers. Disable the ones you are not using from Plugin Options - Console - Error Matchers.

If you are typing "cd" directly to change directories from SshConsole, it is possible the console shell state will not realize this and think errors are from files in an incorrect path. Change directories using the chdir events you selected in Console's plugin options. to ensure the SshConsole knows where you are.

Sometimes an ssh connection will timeout while you are using the SshConsole. If this happens, you will see an IOException in your activity log when you attempt to execute the next command. At this point, the console should automatically close its existing connection and open a new one when you enter the next command.

It may be necessary to cause another Console chdir event before the SshConsole "wakes up" again.

If for some reason, after a timeout, your SshConsole is non-responsive, you can explicitly close all open connections from the Plugins - SshConsole - Close Connections menu action. This has the effect of restarting the plugin from scratch.

Future Ideas

These are things I'd like to have in this plugin at some point, but I don't feel like doing them myself. Any volunteers?

  • Check the VFS to determine if a "cd" is given a valid directory, and don't call ConsoleState.setPath() to update the sshconsole's path unless it is valid.

  • Use VFS and existing sftp:// VFS connection to calculate possible completions.

Enjoy! This is free software, released under a modified version of wtfpl. Feel free to contribute to it (or other plugins) too. Start by joining the mailing list and submitting patches or suggestions.

  • Version 1.0.6 - Requires JDK 1.6, jEdit 5.0, ErrorList 2.1, Ftp 1.0.2, Console 5.1.

    • Fix #3604654: NPE when changing to invalid folder.

    • Fix #3604790: Initial connect when opening a project

  • Version 1.0.5 - Requires JDK 1.6, jEdit 5.0, ErrorList 2.1, Ftp 1.0.2, Console 5.1.

    • Parses Vt100 colors (Artem Bryantsev)

    • Now responds to "chdir to projectviewer root" action from Console.

    • Refactored to use Console 5.1 handlesVFS/chDir API.

    • German Localization (rschwenn)

    • Displays open connections as long-running tasks in task monitor

    • Fix #2873889: Stop leaking connections and properly close them.

    • Enable x11 forwarding

  • Version 1.0.3 - Requires JDK 1.6, jEdit 5.0, ErrorList 2.0, Ftp 1.0, Console 5.0.

    • No longer sends errors to all views.

    • Catch a NumberFormatException when creating errors with invalid paths and ignore invalid paths. (#3575850 - ErrorList 2.0 breaks SshConsole)

  • Version 1.0.2 - Requires JDK 1.5, jEdit 4.3, ErrorList 1.7, FTP plugin 0.9.2, Console plugin 4.3.5.

    • Fixed ConcurrentModificationException (# 2491847 - M. Casanova)

    • Fixed broken close connections action (broken due to changes in accessibility by beanshell macros in core)

  • Version 1.0.1 - Requires JDK 1.5, jEdit 4.3pre12, ErrorList 1.7, FTP plugin 0.9.2, Console plugin 4.3.5.

    • sets TERM="dumb".

  • Version 1.0 (initial release) - Requires JDK 1.5, jEdit 4.3pre12, ErrorList 1.7, FTP plugin 0.9.2, Console plugin 4.3.5.