Snippets Plugin

The Snippets plugin allows you to store frequently-used pieces of text, called snippets, and insert them quickly into a document.

Snippets are specific to the language syntax of the current document. For example, when you are working with an HTML document, you can choose from a list of snippets that are useful for HTML. In addition, some snippets are global, and are available in all documents.

A number of built-in snippets are installed with gedit, which can be modified.

10.10.1. Inserting Snippets

To insert a snippet into a document, type its tab trigger and press Tab. A snippet's tab trigger is usually the first few letters of the snippet, or something else that is short and easy to remember.

Alternatively, press Ctrl+Space to see a list of snippets you can insert.

10.10.2. Adding Snippets

To create a new snippet, do the following:

  1. Choose Tools ▸ Manage Snippets. The Snippets Manager window opens.

  2. The list of snippets is grouped by language. Select the language you want to add a snippet to, or a snippet in that language group. To add a snippet for all languages, choose Global at the top of the list. The syntax of the document you are currently working with is shown by default.

  3. Click New. A new snippet appears in the list.

  4. Enter the following information for the new snippet:

    Nom

    Enter a name for the snippet in the text field within the snippet list. The name of a snippet serves only as a reminder of its purpose. You can change name of a snippet you create by clicking on it in the list.

    Snippet text

    Enter the text of the snippet in the Edit snippet text box. For special codes you can use, see Section 10.10.4 ― Snippet Substitutions.

    You can switch back to the document window to copy text without closing the Snippets Manager window.

    Tab Trigger

    Enter the tab trigger for the snippet. This is the text that you type before pressing Tab to insert the snippet.

    The tag must be either a single word comprising only letters, or any single character. The Tab trigger will highlight in red if an invalid tab trigger is entered.

    Shortcut key

    Type a shortcut key to use for inserting the snippet.

10.10.3. Editing and Removing Snippets

To edit a snippet, select it in the list and make changes to its text and activation properties.

To rename a snippet, click it again in the list.

To restore a built-in snippet that you have changed, press Revert.

To remove a snippet, select it in the list and press Remove. You can not remove built-in snippets, only those you have created yourself.

10.10.4. Snippet Substitutions

In addition to inserting stored text, a snippet can include customizable text, or mark spaces where you can add text once the snippet is inserted in your document.

You can use the following placeholder codes in snippet text:

Tab placeholders

$n defines a tab placeholder, where n is any number from 1 upwards.

${n:default} defines a tab placeholder with a default value.

A tab placeholder marks a place in the snippet text where you can add extra text after the snippet is inserted.

To use tab placeholders, insert the snippet as normal. The cursor is placed at the first tab placeholder. Type text, and press Tab to advance to the next tab placeholder. The number in the placeholder code defines the order in which tab advances to each place in the text.

Press Shift+Tab to return to the previous tab placeholder. Pressing Tab when there are no more tab placeholders moves the cursor to the end of the snippet text, or to the end placeholder if it exists.

Mirror placeholders

A repeated tab placeholder will mirror the placeholder already defined. This allows you to type in text only once that you want to appear several times in the snippet.

End placeholder

$0 defines the end placeholder. This allows you to finish working with the snippet with the cursor at a point other than the end of the snippet text.

Environmental variables

Environmental variable such as $PATH and $HOME are substituted in snippet text. The following variables specific to gedit can also be used:

$GEDIT_SELECTED_TEXT

The currently selected text.

$GEDIT_FILENAME

The full filename of the document, or an empty string if the document isn't saved yet.

$GEDIT_BASENAME

The basename of the filename of the document, or an empty string if the document isn't saved yet.

$GEDIT_CURRENT_WORD

The word at the cursor's location in the document. When this variable is used, the current word will be replaced by the snippet text.

Shell placeholders

$(cmd) is replaced by the result of executing cmd in a shell.

$(n:cmd) allows you to give this placeholder a reference, where n is any number from 1 upwards. Use $n to use the output from one shell placeholder as input in another.

Python placeholders

$<cmd> is replaced by the result of evaluating cmd in the python interpreter.

$<a:cmd> specifies another python placeholder as a dependency, where a gives its order in the snippet. This allows you to use python functions defined in another snippet. To specify several dependencies, separate the numbers with commas thus: $<a,b:cmd>

To use a variable in all other python snippets, declare it as global.