Autotools based build system

To compile Geany yourself, you just need the Make tool, preferably GNU Make.

Then run the following commands:

$ ./configure
$ make

Then as root:

% make install

Or via sudo:

% sudo make install

Custom installation

The configure script supports several common options, for a detailed list, type:

$ ./configure --help

You may also want to read the INSTALL file for advanced installation options.

• See also Compile-time options.

Dynamic linking loader support and VTE

In the case that your system lacks dynamic linking loader support, you probably want to pass the option --disable-vte to the configure script. This prevents compiling Geany with dynamic linking loader support for automatically loading libvte.so.4 if available.

Build problems

If there are any errors during compilation, check your build environment and try to find the error, otherwise contact the mailing list or one the authors. Sometimes you might need to ask for specific help from your distribution.

Sidebar Usage

The sidebar has a right click menu that can control what is visible and has actions specific to the tab (other tabs added by plugins are described by that plugin documentation):

• Symbols

  • expand/collapse the tree
  • control sorting order
  • control whether to group symbols by their type
  • locate the symbol in documents

  The symbols tab can also be filtered by typing a string into the entry at the top of the tab. All symbols that contain the entered string as a substring will be shown in the tree. Multiple filters can be separated by a space.

• Documents

  • expand/collapse the tree
  • save to or reload from files
  • search tree based at selected file
  • show or hide the document paths

Startup

At startup, Geany loads all files from the last time Geany was launched. You can disable this feature in the preferences dialog (see General Startup preferences).

You can start several instances of Geany, but only the first will load files from the last session. In the subsequent instances, you can find these files in the file menu under the Recent files item. By default this contains the last 10 recently opened files. You can change the number of recently opened files in the Files tab of the preferences dialog.

To run a second instance of Geany, do not specify any filenames on the command-line, or disable opening files in a running instance using the -i command line option.

Opening files

geany some_file.foo:55:4

Virtual terminal emulator widget (VTE)

If you have installed libvte.so on your system, it is loaded automatically by Geany, and you will have a terminal widget in the notebook at the bottom.

If Geany cannot find any libvte.so at startup, the terminal widget will not be loaded. So there is no need to install the package containing this file in order to run Geany. Additionally, you can disable the use of the terminal widget by command line option, for more information see the section called Command line options.

You can use this terminal (from now on called VTE) much as you would a terminal program like xterm. There is basic clipboard support. You can paste the contents of the clipboard by pressing the right mouse button to open the popup menu, and choosing Paste. To copy text from the VTE, just select the desired text and then press the right mouse button and choose Copy from the popup menu. On systems running the X Window System you can paste the last selected text by pressing the middle mouse button in the VTE (on 2-button mice, the middle button can often be simulated by pressing both mouse buttons together).

In the preferences dialog you can specify a shell which should be started in the VTE. To make the specified shell a login shell just use the appropriate command line options for the shell. These options should be found in the manual page of the shell. For zsh and bash you can use the argument --login.

It could be, that the library is called something else than libvte.so (e.g. on FreeBSD 6.0 it is called libvte.so.8). If so please set a link to the correct file (as root):

# ln -s /usr/lib/libvte.so.X /usr/lib/libvte.so

Obviously, you have to adjust the paths and set X to the number of your libvte.so.

You can also specify the filename of the VTE library to use on the command line (see the section called Command line options) or at compile time by specifying the command line option --with-vte-module-path to ./configure.

Switching between documents

The documents list and the editor tabs are two different ways to switch between documents using the mouse. When you hit the key combination to move between tabs, the order is determined by the tab order. It is not alphabetical as shown in the documents list (regardless of whether or not editor tabs are visible).

See the Notebook tab keybindings section for useful shortcuts including for Most-Recently-Used document switching.

Document list views

There are three different ways to display documents on the sidebar if Show documents list is active. To switch between views press the right mouse button on the documents list and select one of these items:

Documents Only

Show only file names of open documents in sorted order.

Show Paths

Show open documents as a two-level tree in which first level is the paths of directories containing open files and the second level is the file names of the documents open in that path. All documents with the same path are grouped together under the same first level item. Paths are in sorted order and documents are sorted within each group.

Show Tree

Show paths as above, but as a multiple level partial tree. The tree is only expanded at positions where two or more directory paths to open documents share the same prefix. The common prefix is shown as a parent level, and the remainder of those paths are shown as child levels. This applies recursively down the paths making a tree to the file names of open documents, which are grouped in sorted order as an additional level below the last path segment.

For convenience two common file locations are handled specially, open files below the users home directory and open files below an open project base path. Each of these is moved to its own top level tree instead of being in place in the normal tree. The top level of these trees are each labelled differently. For the home directory tree the path of the home directory is shown as ~, and for the project tree the path to the project base path is shown simply as the project name.

In all cases paths and file names that do not fit in the width available are ellipsised.

Cloning documents

The Document->Clone menu item copies the current document's text, cursor position and properties into a new untitled document. If there is a selection, only the selected text is copied. This can be useful when making temporary copies of text or for creating documents with similar or identical contents.

Automatic filename insertion on Save As...

If a document is saved via Document->Save As... then the filename is automatically inserted into the comment header replacing text like untitled.ext in the first 3 lines of the file. E.g. if a new .c file is created using File->New (with Template) then the text untitled.c in line 2 would be replaced with the choosen file name on Save As... (this example assumes the default file templates being used).

Using character sets

Geany provides support for detecting and converting character sets. So you can open and save files in different character sets, and even convert a file from one character set to another. To do this, Geany uses the character conversion capabilities of the GLib library.

Only text files are supported, i.e. opening files which contain NULL-bytes may fail. Geany will try to open the file anyway but it is likely that the file will be truncated because it can only be read up to the first occurrence of a NULL-byte. All characters after this position are lost and are not written when you save the file.

Geany tries to detect the encoding of a file while opening it, but auto-detecting the encoding of a file is not easy and sometimes an encoding might not be detected correctly. In this case you have to set the encoding of the file manually in order to display it correctly. You can this in the file open dialog by selecting an encoding in the drop down box or by reloading the file with the file menu item "Reload as". The auto-detection works well for most encodings but there are also some encodings where it is known that auto-detection has problems.

There are different ways to set different encodings in Geany:

• Using the file open dialog

  This opens the file with the encoding specified in the encoding drop down box. If the encoding is set to "Detect from file" auto-detection will be used. If the encoding is set to "Without encoding (None)" the file will be opened without any character conversion and Geany will not try to auto-detect the encoding (see below for more information).

• Using the "Reload as" menu item

  This item reloads the current file with the specified encoding. It can help if you opened a file and found out that the wrong encoding was used.

• Using the "Set encoding" menu item

  Contrary to the above two options, this will not change or reload the current file unless you save it. It is useful when you want to change the encoding of the file.

• Specifying the encoding in the file itself

  As mentioned above, auto-detecting the encoding of a file may fail on some encodings. If you know that Geany doesn't open a certain file, you can add the specification line, described in the next section, to the beginning of the file to force Geany to use a specific encoding when opening the file.

In-file encoding specification

Geany detects meta tags of HTML files which contain charset information like:

<meta http-equiv="content-type" content="text/html; charset=ISO-8859-15" />

and the specified charset is used when opening the file. This is useful if the encoding of the file cannot be detected properly. For non-HTML files you can also define a line like:

/* geany_encoding=ISO-8859-15 */

or:

# geany_encoding=ISO-8859-15 #

to force an encoding to be used. The #, /* and */ are examples of filetype-specific comment characters. It doesn't matter which characters are around the string " geany_encoding=ISO-8859-15 " as long as there is at least one whitespace character before and after this string. Whitespace characters are in this case a space or tab character. An example to use this could be you have a file with ISO-8859-15 encoding but Geany constantly detects the file encoding as ISO-8859-1. Then you simply add such a line to the file and Geany will open it correctly the next time.

Since Geany 0.15 you can also use lines which match the regular expression used to find the encoding string: coding[\t ]*[:=][\t ]*([a-z0-9-]+)[\t ]*

Some examples are:

# encoding = ISO-8859-15

or:

# coding: ISO-8859-15

Special encoding "None"

There is a special encoding "None" which uses no encoding. It is useful when you know that Geany cannot auto-detect the encoding of a file and it is not displayed correctly. Especially when the file contains NULL-bytes this can be useful to skip auto detection and open the file properly at least until the occurrence of the first NULL-byte. Using this encoding opens the file as it is without any character conversion.

Unicode Byte-Order-Mark (BOM)

Furthermore, Geany detects a Unicode Byte Order Mark (see https://en.wikipedia.org/wiki/Byte_Order_Mark for details). Of course, this feature is only available if the opened file is in a Unicode encoding. The Byte Order Mark helps to detect the encoding of a file, e.g. whether it is UTF-16LE or UTF-16BE and so on. On Unix-like systems using a Byte Order Mark could cause some problems for programs not expecting it, e.g. the compiler gcc stops with stray errors, PHP does not parse a script containing a BOM and script files starting with a she-bang maybe cannot be started. In the status bar you can easily see whether the file starts with a BOM or not.

If you want to set a BOM for a file or if you want to remove it from a file, just use the document menu and toggle the checkbox.

Folding

Geany provides basic code folding support. Folding means the ability to show and hide parts of the text in the current file. You can hide unimportant code sections and concentrate on the parts you are working on and later you can show hidden sections again. In the editor window there is a small grey margin on the left side with [+] and [-] symbols which show hidden parts and hide parts of the file respectively. By clicking on these icons you can simply show and hide sections which are marked by vertical lines within this margin. For many filetypes nested folding is supported, so there may be several fold points within other fold points.

If you don't like it or don't need it at all, you can simply disable folding support completely in the preferences dialog.

The folding behaviour can be changed with the "Fold/Unfold all children of a fold point" option in the preference dialog. If activated, Geany will unfold all nested fold points below the current one if they are already folded (when clicking on a [+] symbol). When clicking on a [-] symbol, Geany will fold all nested fold points below the current one if they are unfolded.

This option can be inverted by pressing the Shift key while clicking on a fold symbol. That means, if the "Fold/Unfold all children of a fold point" option is enabled, pressing Shift will disable it for this click and vice versa.

Column mode editing (rectangular selections)

There is basic support for column mode editing. To use it, create a rectangular selection by holding down the Control and Shift keys (or Alt and Shift on Windows) while selecting some text. Once a rectangular selection exists you can start editing the text within this selection and the modifications will be done for every line in the selection.

It is also possible to create a zero-column selection - this is useful to insert text on multiple lines.

Drag and drop of text

If you drag selected text in the editor widget of Geany the text is moved to the position where the mouse pointer is when releasing the mouse button. Holding Control when releasing the mouse button will copy the text instead. This behaviour was changed in Geany 0.11 - before the selected text was copied to the new position.

Indentation

Geany allows each document to indent either with a tab character, multiple spaces or a combination of both.

The Tabs setting indents with one tab character per indent level, and displays tabs as the indent width.

The Spaces setting indents with the number of spaces set in the indent width for each level.

The Tabs and Spaces setting indents with spaces as above, then converts as many spaces as it can to tab characters at the rate of one tab for each multiple of the Various preference setting indent_hard_tab_width (default 8) and displays tabs as the indent_hard_tab_width value.

The default indent settings are set in Editor Indentation preferences (see the link for more information).

The default settings can be overridden per-document using the Document menu. They can also be overridden by projects - see Project management.

The indent mode for the current document is shown on the status bar as follows:

TAB

Indent with Tab characters.

SP

Indent with spaces.

T/S

Indent with tabs and spaces, depending on how much indentation is on a line.

Auto-indentation

When enabled, auto-indentation happens when pressing Enter in the Editor. It adds a certain amount of indentation to the new line so the user doesn't always have to indent each line manually.

Geany has four types of auto-indentation:

None

Disables auto-indentation completely.

Basic

Adds the same amount of whitespace on a new line as on the previous line. For the Tabs and the Spaces indent types the indentation will use the same combination of characters as the previous line. The Tabs and Spaces indentation type converts as explained above.

Current chars

Does the same as Basic but also indents a new line after an opening brace '{', and de-indents when typing a closing brace '}'. For Python, a new line will be indented after typing ':' at the end of the previous line.

Match braces

Similar to Current chars but the closing brace will be aligned to match the indentation of the line with the opening brace. This requires the filetype to be one where Geany knows that the Scintilla lexer understands matching braces (C, C++, D, HTML, Pascal, Bash, Perl, TCL).

There is also XML-tag auto-indentation. This is enabled when the mode is more than just Basic, and is also controlled by a filetype setting - see xml_indent_tags.

Bookmarks

Geany provides a handy bookmarking feature that lets you mark one or more lines in a document, and return the cursor to them using a key combination.

To place a mark on a line, either left-mouse-click in the left margin of the editor window, or else use Ctrl-m. This will produce a small green plus symbol in the margin. You can have as many marks in a document as you like. Click again (or use Ctrl-m again) to remove the bookmark. To remove all the marks in a given document, use "Remove Markers" in the Document menu.

To navigate down your document, jumping from one mark to the next, use Ctrl-. (control period). To go in the opposite direction on the page, use Ctrl-, (control comma). Using the bookmarking feature together with the commands to switch from one editor tab to another (Ctrl-PgUp/PgDn and Ctrl-Tab) provides a particularly fast way to navigate around multiple files.

Code navigation history

To ease navigation in source files and especially between different files, Geany lets you jump between different navigation points. Currently, this works for the following:

• Go to symbol declaration
• Go to symbol definition
• Symbol list items
• Build errors
• Message items

When using one of these actions, Geany remembers your current position and jumps to the new one. If you decide to go back to your previous position in the file, just use "Navigate back a location". To get back to the new position again, just use "Navigate forward a location". This makes it easier to navigate in e.g. foreign code and between different files.

Sending text through custom commands

You can define several custom commands in Geany and send the current selection to one of these commands using the Edit->Format->Send Selection to menu or keybindings. The output of the command will be used to replace the current selection. This makes it possible to use text formatting tools with Geany in a general way.

The selected text will be sent to the standard input of the executed command, so the command should be able to read from it and it should print all results to its standard output which will be read by Geany. To help finding errors in executing the command, the output of the program's standard error will be printed on Geany's standard output.

If there is no selection, the whole current line is used instead.

To add a custom command, use the Send Selection to->Set Custom Commands menu item. Click on Add to get a new item and type the command. You can also specify some command line options. Empty commands are not saved.

Normal shell quoting is supported, so you can do things like:

• sed 's/\./(dot)/g'

The above example would normally be done with the Replace all function, but it can be handy to have common commands already set up.

Note that the command is not run in a shell, so if you want to use shell features like pipes and command chains, you need to explicitly launch the shell and pass it your command:

• sh -c 'sort | uniq'

Context actions

You can execute the context action command on the current word at the cursor position or the available selection. This word or selection can be used as an argument to the command. The context action is invoked by a menu entry in the popup menu of the editor and also a keyboard shortcut (see the section called Keybindings).

The command can be specified in the preferences dialog and also for each filetype (see "context_action_cmd" in the section called Filetype configuration). When the context action is invoked, the filetype specific command is used if available, otherwise the command specified in the preferences dialog is executed.

The current word or selection can be referred with the wildcard "%s" in the command, it will be replaced by the current word or selection before the command is executed.

For example a context action can be used to open API documentation in a browser window, the command to open the PHP API documentation would be:

firefox "https://www.php.net/%s"

when executing the command, the %s is substituted by the word near the cursor position or by the current selection. If the cursor is at the word "echo", a browser window will open(assumed your browser is called firefox) and it will open the address: https://www.php.net/echo.

Autocompletion

Geany can offer a list of possible completions for symbols defined in the tags files and for all words in open documents.

The autocompletion list for symbols is presented when the first few characters of the symbol are typed (configurable, see Editor Completions preferences, default 4) or when the Complete word keybinding is pressed (configurable, see Editor keybindings, default Ctrl-Space).

For some languages the autocompletion list is ordered by heuristics to attempt to show names that are more likely to be what the user wants close to the top of the list.

When the defined keybinding is typed and the Autocomplete all words in document preference (in Editor Completions preferences) is selected then the autocompletion list will show all matching words in the document, if there are no matching symbols.

If you don't want to use autocompletion it can be dismissed until the next symbol by pressing Escape. The autocompletion list is updated as more characters are typed so that it only shows completions that start with the characters typed so far. If no symbols begin with the sequence, the autocompletion window is closed.

The up and down arrows will move the selected item. The highlighted item on the autocompletion list can be chosen from the list by pressing Enter/Return. You can also double-click to select an item. The sequence will be completed to match the chosen item, and if the Drop rest of word on completion preference is set (in Editor Completions preferences) then any characters after the cursor that match a symbol or word are deleted.

struct
{
    int i;
    char c;
} foo;

Calltips

A handy tooltip is shown when typing ( after a symbol name when the symbol has a parameter list. The tag parser for the filetype must support parsing parameter lists. Calltips can also be shown with a keybinding.

When there is more than one matching symbol, arrows are shown which can be clicked to cycle through the signatures.

User-definable snippets

Snippets are small strings or code constructs which can be replaced or completed to a more complex string. So you can save a lot of time when typing common strings and letting Geany do the work for you. To know what to complete or replace Geany reads a configuration file called snippets.conf at startup.

Maybe you need to often type your name, so define a snippet like this:

[Default]
myname=Enrico Tröger

Every time you write myname <TAB> in Geany, it will replace "myname" with "Enrico Tröger". The key to start autocompletion can be changed in the preferences dialog, by default it is TAB. The corresponding keybinding is called Complete snippet.

Paths

You can override the default snippets using the user snippets.conf file. Use the Tools->Configuration Files->snippets.conf menu item. See also Configuration file paths.

This adds the default settings to the user file if the file doesn't exist. Alternatively the file can be created manually, adding only the settings you want to change. All missing settings will be read from the system snippets file.

Snippet groups

The file snippets.conf contains sections defining snippets that are available for particular filetypes and in general.

The two sections "Default" and "Special" apply to all filetypes. "Default" contains all snippets which are available for every filetype and "Special" contains snippets which can only be used in other snippets. So you can define often used parts of snippets and just use the special snippet as a placeholder (see the snippets.conf for details).

You can define sections with the name of a filetype eg "C++". The snippets in that section are only available for use in files with that filetype. Snippets in filetype sections will hide snippets with the same name in the "Default" section when used in a file of that filetype.

Substitution sequences for snippets

To define snippets you can use several special character sequences which will be replaced when using the snippet:

Snippet names must not contain spaces otherwise they won't work correctly. But beside that you can define almost any string as a snippet and use it later in Geany. It is not limited to existing constructs of certain programming languages(like if, for, switch). Define whatever you need.

Template wildcards

Since Geany 0.15 you can also use most of the available templates wildcards listed in Template wildcards. All wildcards which are listed as available in snippets can be used. For instance to improve the above example:

[Default]
myname=My name is {developer}
mysystem=My system: {command:uname -a}

this will replace myname with "My name is " and the value of the template preference developer.

Word characters

You can change the way Geany recognizes the word to complete, that is how the start and end of a word is recognised when the snippet completion is requested. The section "Special" may contain a key "wordchars" which lists all characters a string may contain to be recognized as a word for completion. Leave it commented to use default characters or define it to add or remove characters to fit your needs.

[Keybindings]
for=<Ctrl>7
block_cursor=<Ctrl>8

Inserting Unicode characters

You can insert Unicode code points by hitting Ctrl-Shift-u, then still holding Ctrl-Shift, type some hex digits representing the code point for the character you want and hit Enter or Return (still holding Ctrl-Shift). If you release Ctrl-Shift before hitting Enter or Return (or any other character), the code insertion is completed, but the typed character is also entered. In the case of Enter/Return, it is a newline, as you might expect.

In some earlier versions of Geany, you might need to first unbind Ctrl-Shift-u in the keybinding preferences, then select Tools->Reload Configuration or restart Geany. Note that it works slightly differently from other GTK applications, in that you'll need to continue to hold down the Ctrl and Shift keys while typing the code point hex digits (and the Enter or Return to finish the code point).

Inserting color values

You can insert a color value by selecting Tools->Color Chooser from the menu. A dialog appears to select the wanted color. If the cursor is placed inside a #RRGGBB format color value then the dialog will show that color after opening. On clicking on Apply or Select the code for the chosen color will be inserted in the format #RRGGBB. If text is selected, then it will be replaced with the color code on the first click on Apply or Select. If no text is selected or on subsequent clicks the color code is inserted at the current cursor position.

Toolbar entries

There are also two toolbar entries:

• Search bar
• Go to line entry

There are keybindings to focus each of these - see Focus keybindings. Pressing Escape will then focus the editor.

Find

The Find dialog is used for finding text in one or more open documents.

#GeanyDialogSearch GtkEntry /* GTK < 3.20 */,
#GeanyDialogSearch entry /* GTK >= 3.20 */ {
    font: 8pt monospace;
}

Find selection

The Find Next/Previous Selection commands perform a search for the current selected text. If nothing is selected, by default the current word is used instead. This can be customized by the find_selection_type preference - see Various preferences.

Find usage

Find Usage searches all open files. It is similar to the Find All In Session option in the Find dialog.

If there is a selection, then it is used as the search text; otherwise the current word is used. The current word is either taken from the word nearest the edit cursor, or the word underneath the popup menu click position when the popup menu is used. The search results are shown in the Messages tab of the Message Window.

Find in files

Find in Files is a more powerful version of Find Usage that searches all files in a certain directory using the Grep tool. The Grep tool must be correctly set in Preferences to the path of the system's Grep utility. GNU Grep is recommended (see note below).

The Search field is initially set to the current word in the editor (depending on Search preferences).

The Files setting allows to choose which files are included in the search, depending on the mode:

All

Search in all files;

Project

Use the current project's patterns, see Project properties;

Custom

Use custom patterns.

Both project and custom patterns use a glob-style syntax, each pattern separated by a space. To search all .c and .h files, use: *.c *.h. Note that an empty pattern list searches in all files rather than none.

The Directory field is initially set to the current document's directory, unless this field has already been edited and the current document has not changed. Otherwise, the current document's directory is prepended to the drop-down history. This can be disabled - see Search preferences.

The Encoding field can be used to define the encoding of the files to be searched. The entered search text is converted to the chosen encoding and the search results are converted back to UTF-8.

The Extra options field is used to pass any additional arguments to the grep tool.

Replace

The Replace dialog is used for replacing text in one or more open documents.

The Replace dialog has the same options for matching text as the Find dialog. See the section Matching options.

The Use regular expressions option allows regular expressions to be used in the search string and back references in the replacement text -- see the entry for '\n' in Regular expressions.

Go to symbol definition

If the current word or selection is the name of a symbol definition (e.g. a function name) and the file containing the symbol definition is open, this command will switch to that file and go to the corresponding line number. The current word is either the word nearest the edit cursor, or the word underneath the popup menu click position when the popup menu is used.

If there are more symbols with the same name to which the goto can be performed, a pop up is shown with a list of all the occurrences. After selecting a symbol from the list Geany jumps to the corresponding symbol location. Geany tries to suggest the nearest symbol (symbol from the current file, other open documents or current directory) as the best candidate for the goto and places this symbol at the beginning of the list typed in boldface.

Go to symbol declaration

Like Go to symbol definition, but for a forward declaration such as a C function prototype or extern declaration instead of a function body.

Go to line

Go to a particular line number in the current file.

If the given value starts with a plus or minus, the value will be interpreted as an offset from the current line.

Regular expressions

You can use regular expressions in the Find and Replace dialogs by selecting the Use regular expressions check box (see Matching options). The syntax is Perl compatible. Basic syntax is described in the table below. For full details, see https://www.geany.org/manual/gtk/glib/glib-regex-syntax.html.

By default regular expressions are matched on a line-by-line basis. If you are interested in multi-line regular expressions, matched against the whole buffer at once, see the section Multi-line regular expressions below.

In a regular expression, the following characters are interpreted:

[]|-]    matches these 3 chars
[]-|]    matches from ] to | chars
[a-z]    any lowercase alpha
[^]-]    any char except - and ]
[^A-Z]   any char except uppercase alpha
[a-zA-Z] any alpha

Color schemes dialog

The Color Schemes dialog is available under the View->Change Color Scheme menu item. It lists various color schemes for editor highlighting styles, including the default scheme first. Other items are available based on what color scheme files Geany found at startup.

Color scheme files are read from the Configuration file paths under the colorschemes subdirectory. They should have the extension .conf. The default color scheme is read from filetypes.common.

The [named_styles] section and [named_colors] section are the same as for filetypes.common.

The [theme_info] section can contain information about the theme. The name and description keys are read to set the menu item text and tooltip, respectively. These keys can have translations, e.g.:

key=Hello
key[de]=Hallo
key[fr_FR]=Bonjour

Workspace symbols

Each document is parsed for symbols whenever a file is loaded, saved or modified (see Symbol list update frequency preference in the Editor Completions preferences). These are shown in the Symbol list in the Sidebar. These symbols are also used for autocompletion and calltips for all documents open in the current session that have the same filetype.

The Go to Symbol commands can be used with all workspace symbols. See Go to symbol definition.

Global tags files

Global tags files are used to provide symbols for autocompletion and calltips without having to open the source files containing these symbols. This is intended for library APIs, as the tags file only has to be updated when you upgrade the library.

You can load a custom global tags file in two ways:

• Using the Load Tags File command in the Tools menu.
• By moving or symlinking tags files to the tags subdirectory of one of the configuration file paths before starting Geany.

You can either download these files or generate your own. They have the format:

name.lang_ext.tags

lang_ext is one of the extensions set for the filetype associated with the tags parser. See the section called Filetype extensions for more information.

basename|string|(string path [, string suffix])|

ctags -n --fields=EfiklsZSt -R -o my_project.c.tags my_project

geany -g [-P] <Tags File> <File list>

geany -g wxd.d.tags /home/username/wxd/wx/*.d

CFLAGS=`pkg-config --cflags libgnomeui-2.0` geany -g gnomeui.c.tags \
/usr/include/libgnomeui-2.0/gnome.h

"c:\program files\geany\bin\geany" -g c:\mytags.php.tags c:\code\somefile.php

C ignore.tags

You can ignore certain symbols for C-based languages if they would lead to wrong parsing of the code. Use the Tools->Configuration Files->ignore.tags menu item to open the user ignore.tags file. See also Configuration file paths.

List all symbol names you want to ignore in this file, separated by spaces and/or newlines.

Example:

G_GNUC_NULL_TERMINATED
G_GNUC_PRINTF
G_GNUC_WARN_UNUSED_RESULT
BAR

This will ignore the above macros and will correctly detect 'Foo' as a type instead of 'BAR' in the following code:

struct Foo BAR { int i; };

In addition, it is possible to specify macro definition similarly to the gcc '-D' option:

<macro>=<definition> Defines a C preprocessor <macro>. This emulates the behavior of the corresponding gcc option. All types of macros are supported, including the ones with parameters and variable arguments. Stringification, token pasting and recursive macro expansion are also supported.

For even more detailed information please read the manual page of Universal Ctags.

General Startup preferences

General Miscellaneous preferences

Interface preferences

Interface Notebook tab preferences

Interface Toolbar preferences

Affects the main toolbar underneath the menu bar.

Editor Features preferences

Editor Indentation preferences

Editor Completions preferences

Editor Display preferences

This is for visual elements displayed in the editor window.

Change History

The change history feature enables changed text in a document to be shown in the markers margin or by underlining the text. By default, the change history feature is disabled.

Newly added, modified and removed lines or words are highlighted to easily track changes to the opened document. The changes can be shown as vertical bars in the markers margin and/or as underlines in the text directly.

Note

This feature may use a moderate amount of memory, especially if there are many or big changes in the document. Also, modification information is not kept when re-opening a document - all change markers will be lost.

The image shows the default visuals:

• inserted characters appear with coloured underlines
• points where characters were deleted are shown with small triangles
• the margin shows a block indicating the overall state of the line, prioritizing the more consequential modified states
• the states are modified (orange), saved (green), saved then reverted to modified (green-yellow), and saved then reverted to original (cyan).

Show in markers margin

Changes are shown in the markers margin as vertical bars

Show as underline indicators

Changes are shown as underlines in the text directly

Files preferences

Tools preferences

Template preferences

See Templates.

This data is used as meta data for various template text to insert into a document, such as the file header. You only need to set fields that you want to use in your template files.

Keybinding preferences

There are some commands listed in the keybinding dialog that are not, by default, bound to a key combination, and may not be available as a menu item.

Printing preferences

Use external command for printing

Use a system command to print your file out.

Use native GTK printing

Let the GTK GUI toolkit handle your print request.

Print line numbers

Print the line numbers on the left of your paper.

Print page number

Print the page number on the bottom right of your paper.

Print page header

Print a header on every page that is sent to the printer.

Use base name of the printed file

Don't use the entire path for the header, only the filename.

Date format

How the date should be printed. For a list of available conversion specifiers see https://docs.gtk.org/glib/method.DateTime.format.html.

Various preferences

Rarely used preferences, explained in the table below. A few of them require restart to take effect, and a few other will only affect newly opened or created documents before restart.

Terminal (VTE) preferences

See also: Virtual terminal emulator widget (VTE).

New project

There are two ways of creating new projects, either by using Project->New menu item or by using Project->New from Folder menu item.

New

This method is more suitable for creating new, empty projects from scratch at the default location without having any existing sources.

To create a new project, fill in the Name field. By default this will setup a new project file ~/projects/name/name.geany.

The Base path text field is setup to use ~/projects/name. This can safely be set to any existing path -- it will not touch the file structure contained in it.

New from Folder

This method is more suitable when there is already some folder containing source files for which you want to create a new project.

When using this method, Geany first opens a directory selection dialog to select the folder containing the sources, and the Base path field is set to that value.

Afterwards, Geany shows the same dialog as the Project->New method but already pre-filled with the values based on the Base path selection. The Name field is filled with the folder name, the Filename field is filled with base_path/name.geany and the Base path field is filled with the path specified in the previous dialog.

Project properties

You can set an optional description for the project. Currently it's only used for the {description}} template wildcard - see Dynamic wildcards.

The Base path field is used as the directory to run the Build menu commands. The specified path can be an absolute path or it is considered to be relative to the project's file name.

The File patterns field allows to specify a list of file patterns for the project, which can be used in the Find in files dialog.

The Indentation tab allows you to override the default Indentation settings.

Open project

The Open command displays a standard file chooser, starting in ~/projects. Choose a project file named with the .geany extension.

When project session support is enabled, Geany will close the currently open files and open the session files associated with the project.

Close project

Project file settings are saved when the project is closed.

When project session support is enabled, Geany will close the project session files and open any previously closed default session files.

Indicators

Indicators are red squiggly underlines which are used to highlight errors which occurred while compiling the current file. So you can easily see where your code failed to compile. You can remove them by selecting Remove Error Indicators in the Document menu.

If you do not like this feature, you can disable it - see Editor Features preferences.

Default build menu items

Depending on the current file's filetype, the default Build menu will contain the following items:

• Compile
• Build
• Lint
• Make All
• Make Custom Target
• Make Object
• Next Error
• Previous Error
• Execute
• Set Build Menu Commands

xterm -e "/bin/sh %c"

Build menu configuration

The build menu has considerable flexibility and configurability, allowing menu labels, the commands they execute and the directory they execute in to be configured. For example, if you change one of the default make commands to run say 'waf' you can also change the label to match. These settings are saved automatically when Geany is shut down.

The build menu is divided into four groups of items each with different behaviors:

• Filetype build commands - are configurable and depend on the filetype of the current document; they capture output in the compiler tab and parse it for errors.
• Independent build commands - are configurable and mostly don't depend on the filetype of the current document; they also capture output in the compiler tab and parse it for errors.
• Execute commands - are configurable and intended for executing your program or other long running programs. The output is not parsed for errors and is directed to the terminal command selected in Tools preferences.
• Fixed commands - these perform built-in actions:
  • Go to the next error.
  • Go to the previous error.
  • Show the build menu commands dialog.

The maximum numbers of items in each of the configurable groups can be configured in Various preferences. Even though the maximum number of items may have been increased, only those menu items that have commands configured are shown in the menu.

The groups of menu items obtain their configuration from four potential sources. The highest priority source that has the menu item defined will be used. The sources in decreasing priority are:

• A project file if open
• The user preferences
• The system filetype definitions
• The defaults

The detailed relationships between sources and the configurable menu item groups is shown in the following table:

The following notes on the table may reference cells by coordinate as (group, source):

• Filetype filenames - for filetypes.xxx substitute the appropriate extension for the filetype of the current document for xxx - see filenames.
• System Filetypes - Labels loaded from these sources are locale sensitive and can contain translations.
• (Filetype build, Project and Preferences) - preferences use a full filetype file so that users can configure all other filetype preferences as well. Projects can only configure menu items per filetype. Saving in the project file means that there is only one file per project not a whole directory.
• (Filetype-Independent build, System Filetype) - although conceptually strange, defining filetype-independent commands in a filetype file, this provides the ability to define filetype dependent default menu items.
• (Execute, Project and Preferences) - the project independent execute and preferences independent execute commands can only be set by hand editing the appropriate file, see Preferences file format and Project file format.

Set Build Commands dialog

Most of the configuration of the build menu is done through the Set Build Commands dialog. When no project is open, you can edit the configuration sourced from user preferences using the Build->Set Build Commands menu item. You can edit the configuration sourced from a project in the Build tab of the Project Properties dialog. The former menu item also shows the project dialog when a project is open. Both use the same form shown below.

The dialog is divided into three sections:

• Filetype build commands (selected based on the current document's filetype).
• Independent build commands (available regardless of filetype).
• Filetype execute commands.

The filetype and independent build sections also each contain a field for the regular expression used for parsing command output for error and warning messages.

The columns in the first three sections allow setting of the label, command, and working directory to run the command in. An item with an empty label will not be shown in the menu. An empty working directory will default to the directory of the current document.

If there is no current document then the command will not run.

The dialog will always show the command selected by priority, not just the commands configured in this configuration source. This ensures that you always see what the menu item is going to do if activated.

If the current source of the menu item is higher priority than the configuration source you are editing then the command will be shown in the dialog but will be insensitive (greyed out). This can't happen with the project source but can with the preferences source dialog.

The clear buttons remove the definition from the configuration source you are editing. When you do this the command from the next lower priority source will be shown. To hide lower priority menu items without having anything show in the menu, configure with nothing in the label but at least one character in the command.

Plugin manager

The Plugin Manager dialog lets you choose which plugins should be loaded at startup. You can also load and unload plugins on the fly using this dialog. Once you click the checkbox for a specific plugin in the dialog, it is loaded or unloaded according to its previous state. By default, no plugins are loaded at startup until you select some. You can also configure some plugin specific options if the plugin provides any.

Switching documents

There are some non-configurable bindings to switch between documents, listed below. These can also be overridden by custom keybindings.

See also Notebook tab keybindings.

Configurable keybindings

For all actions listed below you can define your own keybindings. Open the Preferences dialog, select the desired action and click on change. In the resulting dialog you can press the key combination you want to assign to the action and it will be saved when you press OK. You can define only one key combination for each action and each key combination can only be defined for one action.

The following tables list all customizable keyboard shortcuts, those which are common to many applications are marked with (C) after the shortcut.

Paths on Unix-like systems

The system path is $prefix/share/geany, where $prefix is the path where Geany is installed (see Installation prefix).

The user configuration directory is normally: /home/username/.config/geany

Paths on Windows

The system path is the data subfolder of the installation path on Windows.

The user configuration directory might vary, but on Windows XP it's: C:\Documents and Settings\UserName\Application Data\geany On Windows 7 and above you most likely will find it at: C:\users\UserName\Roaming\geany

Customizing Geany's appearance using GTK+ CSS

To override GTK+ CSS styles, you can use traditional mechanisms or you can use the Tools->Configuration files menu to open a file named geany.css which will be loaded after other CSS styles are applied to allow overriding the default styles.

Geany offers a number of CSS IDs which can be used to taylor its appearance. Among the more interesting include:

• geany-compiler-context - the style used for build command output surrounding errors
• geany-compiler-error - the style used for build command errors
• geany-compiler-message - the style other output encountered while running build command
• geany-document-status-changed - the style for document tab labels when the document is changed
• geany-document-status-disk-changed - the style for document tab labels when the file on disk has changed
• geany-document-status-readyonly` - the style for document tab labels when the document is read-only
• geany-search-entry-no-match - the style of find/replace dialog entries when no match is found
• geany-terminal-dirty - the style for the message window Terminal tab label when the terminal output has changed.

Filenames

Each filetype has a corresponding filetype definition file. The format for built-in filetype Foo is:

filetypes.foo

The extension is normally just the filetype name in lower case.

However there are some exceptions:

There is also the special file filetypes.common.

For custom filetypes, the filename for Foo is different:

filetypes.Foo.conf

See the link for details.

System files

The system-wide filetype configuration files can be found in the system configuration path and are called filetypes.$ext, where $ext is the name of the filetype. For every filetype there is a corresponding definition file. There is one exception: filetypes.common -- this file is for general settings, which are not specific to a certain filetype.

User files

To change the settings, copy a file from the system configuration path to the subdirectory filedefs in your user configuration directory. Then you can edit the file and the changes will still be available after an update of Geany.

Alternatively, you can create the file yourself and add only the settings you want to change. All missing settings will be read from the corresponding system configuration file.

Custom filetypes

At startup Geany looks for filetypes.*.conf files in the system and user filetype paths, adding any filetypes found with the name matching the '*' wildcard - e.g. filetypes.Bar.conf.

Custom filetypes are not as powerful as built-in filetypes, but support for the following has been implemented:

• Recognizing and setting the filetype (after the user has manually updated the filetype extensions file).

• Reading filetype settings in the [settings] section, including:

  • Using an existing syntax highlighting lexer (lexer_filetype key).
  • Using an existing tags parser (tag_parser key).

• Build commands ([build-menu] section).
• Loading global tags files (sharing the tag_parser filetype's namespace).

See Filetype configuration for details on each setting.

cp filetypes.foo filetypes.Bar.conf

Filetype configuration

As well as the sections listed below, each filetype file can contain a [build-menu] section as described in [build-menu] section.

[styling=Foo]

[styling=C]

egrep -o 'GetProperty\w*\("([^"]+)"[^)]+\)' scintilla/Lex*.cxx

FT_00_LB=_Compile
FT_00_CM=gcc -c "%f"
FT_00_WD=
FT_01_LB=_Build
FT_01_CM=gcc -o "%e" "%f"
FT_01_WD=
EX_00_LB=_Execute
EX_00_CM="./%e"
EX_00_WD=
error_regex=^([^:]+):([0-9]+):

Special file filetypes.common

There is a special filetype definition file called filetypes.common. This file defines some general non-filetype-specific settings.

You can open the user filetypes.common with the Tools->Configuration Files->filetypes.common menu item. This adds the default settings to the user file if the file doesn't exist. Alternatively the file can be created manually, adding only the settings you want to change. All missing settings will be read from the system file.

[named_styles]
foo=0xc00000;0xffffff;false;true
bar=foo

[styling]
comment=foo

[named_colors]
my_red_color=#FF0000
my_blue_color=#0000FF

[named_styles]
foo=my_red_color;my_blue_color;false;true

[build-menu] section

The [build-menu] section contains the configuration of the build menu. This section can occur in filetype, preferences and project files and always has the format described here. Different menu items are loaded from different files, see the table in the Build Menu Configuration section for details. All the settings can be configured from the dialogs except the execute command in filetype files and filetype definitions in the project file, so these are the only ones which need hand editing.

[build-menu] additions

The project file also can have extra fields in the [build-menu] section in addition to those listed in [build-menu] section above.

When filetype menu items are configured for the project they are stored in the project file.

The filetypes entry is a list of the filetypes which exist in the project file.

For each filetype the entries for that filetype have the format defined in [build-menu] section but the key is prefixed by the name of the filetype as it appears in the filetypes entry, eg the entry for the label of filetype menu item 0 for the C filetype would be

CFT_00_LB=Label

Template meta data

Meta data can be used with all templates, but by default user set meta data is only used for the ChangeLog and File header templates.

In the configuration dialog you can find a tab "Templates" (see Template preferences). You can define the default values which will be inserted in the templates.

File templates

File templates are templates used as the basis of a new file. To use them, choose the New (with Template) menu item from the File menu. If there is more than one template for a filetype then they will be grouped in a submenu.

By default, file templates are installed for some filetypes. Custom file templates can be added by creating the appropriate template file. You can also edit the default file templates.

The file's contents are just the text to place in the document, with optional template wildcards like {fileheader}. The fileheader wildcard can be placed anywhere, but it's usually put on the first line of the file, followed by a blank line.

Customizing templates

Each template can be customized to your needs. The templates are stored in the ~/.config/geany/templates/ directory (see the section called Command line options for further information about the configuration directory). Just open the desired template with an editor (ideally, Geany ;-) ) and edit the template to your needs. There are some wildcards which will be automatically replaced by Geany at startup.

{command:uname -a}

Linux localhost 2.6.9-023stab046.2-smp #1 SMP Mon Dec 10 15:04:55 MSK 2007 x86_64 GNU/Linux

$GEANY_FILENAME

Manually editing the toolbar layout

To override the system-wide configuration file, copy it to your user configuration directory (see Configuration file paths).

For example:

% cp /usr/local/share/geany/ui_toolbar.xml /home/username/.config/geany/

Then edit it and add any of the available elements listed in the file or remove any of the existing elements. Of course, you can also reorder the elements as you wish and add or remove additional separators. This file must be valid XML, otherwise the global toolbar UI definition will be used instead.

Your changes are applied once you save the file.

Available toolbar elements

Insert entity dialog

When the plugin is enabled, you can insert special character entities using Tools->Insert Special HTML Characters.

This opens up a dialog where you can find a huge amount of special characters sorted by category that you might like to use inside your document. You can expand and collapse the categories by clicking on the little arrow on the left hand side. Once you have found the desired character click on it and choose "Insert". This will insert the entity for the character at the current cursor position. You might also like to double click the chosen entity instead.

Replace special chars by its entity

To help make a XML/HTML document valid the plugin supports replacement of special chars known by the plugin. Both bulk replacement and immediate replacement during typing are supported.

A few characters will not be replaced. These are

• "
• &
• <
• >
• (&nbsp;)

Auto Save

This plugin provides an option to automatically save documents. You can choose to save the current document, or all of your documents, at a given delay.

Backup Copy

This plugin creates a backup copy of the current file in Geany when it is saved. You can specify the directory where the backup copy is saved and you can configure the automatically added extension in the configure dialog in Geany's plugin manager.

After the plugin was loaded in Geany's plugin manager, every file is copied into the configured backup directory after the file has been saved in Geany.

The created backup copy file permissions are set to read-write only for the user. This should help to not create world-readable files on possibly unsecure destination directories like /tmp (especially useful on multi-user systems). This applies only to non-Windows systems. On Windows, no explicit file permissions are set.

Additionally, you can define how many levels of the original file's directory structure should be replicated in the backup copy path. For example, setting the option Directory levels to include in the backup destination to 2 cause the plugin to create the last two components of the original file's path in the backup copy path and place the new file there.

Untitled Document Save

This configuration allows to automatically create an underlying file for newly-opened editor tabs (or when using File->New or File->New (with template)). File type is set appropriately to the used template. When no template is used - filetype will be determined by the configurable default value. Such functionality is useful when user often creates new files just for quick editing, taking notes, testing code etc.