External Tools

Overview

The goal of this plugin is to allow users to execute external commands from gedit interface. This allow the user to do two things: either to pipe some content into a command and to exploit its output (for example, sed), or to simply launch some predefined command (for example, make).

Using External Tools

1. To install the plugin, go to Edit -> Preferences -> Plugins -> External Tools.

2. To configure the plugin, go to Tools -> Manage External Tools.... A dialog will appear and you can start adding tools.

3. To run tools, go to Tools -> External Tools or use (if applicable) associated shortcut keys.

External Tools dialog

The name of the current tool can be edited directly using the list on the left side of the dialog.

Here is a short description of the editable properties for a given tool:

• Edit: the actual commands to be ran.

• Shortcut Key: the key binding associated to the current tool.

• Save: saving or not (current document or all documents) before running the tool.

• Input: what content to give to the commands (as stdin).

• Output: what to do with the commands output.

• Applicability: what documents can be affected by that tool? Criteria are: saved or not, local or remote, language.

You can add and remove custom tools, and customize system-provided tools. You can revert latter ones to the upstream version in one click.

Available Environment Variables

• GEDIT_CURRENT_DOCUMENT_DIR

• GEDIT_CURRENT_DOCUMENT_NAME

• GEDIT_CURRENT_DOCUMENT_PATH

• GEDIT_CURRENT_DOCUMENT_SCHEME

• GEDIT_CURRENT_DOCUMENT_TYPE

• GEDIT_CURRENT_DOCUMENT_URI

• GEDIT_CURRENT_DOCUMENT_LANGUAGE

• GEDIT_CURRENT_LINE

• GEDIT_CURRENT_LINE_NUMBER

• GEDIT_CURRENT_WORD

• GEDIT_CWD

• GEDIT_DOCUMENTS_PATH

• GEDIT_DOCUMENTS_URI

• GEDIT_FILE_BROWSER_ROOT (new in gedit 3.9)

• GEDIT_SELECTED_TEXT

Storage and hand-editing of tools

(Note: when upgrading to gedit 3, the user generated external tools may not be moved automatically.)

Each tool consists on an executable script file (in Bash, Perl, Python, Ruby, etc.) containing a metadata section that resembles usual desktop files.

The metadata section starts with a # [Gedit Tool] line, and each following line from the metadata section should start with # . Those lines contain key/value pairs, in the form of key=value. Current keys are:

• Name: the tool name, as displayed in the menu.

• Shortcut: the keyboard shortcut, in usual gtk format.

•  Save-files: nothing, document or all.

• Input: the input (nothing, document, selection, selection-document, line or word)

• Output: the output (nothing, output-panel, new-document, append-document, replace-document, replace-selection or insert).

• Applicability: all, titled, local, remote, or untitled.

The rest of the file is the script to be ran. Note that it is good practice to begin the file with a shebang (ex: #!/bin/perl) so that the system knows which interpretor it should use.

You can also share your home-grown tools by copying the relevant file in your home directory.

Tips and tricks

You can use xargs (combined to the Selection input) to use the selected text as an argument for you command. Here is an exemple using that facility to show the manpage of the selected term:

• Label: Manpage

• Edit: xargs man

• Input: Current word

• Output: Output panel

Current Features

An awful lot ;-).

Possible Features

• bind tools to a particular set of mime-type
• organize the tools using a tree hierarchy instead of a flat list
• save accelerators updated through direct editing from menu
• quiet mode (no logging of stderr nor status info) for X apps launching

Screenshots

The External Tools Manager dialog showing the Build tool:

• with gedit 2

• with gedit 3