You are on page 1of 22


A fast, light, GTK+ IDE

Enrico Trger
Nick Treleaven
Authors: Frank Lanitz
Colomban Wendling
Matthew Brush

Date: 2016-03-13

Version: 1.27

Copyright 2005-2016

This document is distributed under the terms of the GNU General Public License as published
by the Free Software Foundation; either version 2 of the License, or (at your option) any later
version. A copy of this license can be found in the file COPYING included with the source code
of this program, and also in the chapter GNU General Public License.



o About Geany

o Where to get it

o License

o About this document


o Requirements

o Binary packages

o Source compilation

Autotools based build system

Custom installation

Dynamic linking loader support and VTE

Build problems

o Installation prefix


o Getting started

o The Geany workspace

o Command line options

o General


Opening files from the command-line in a running instance

Virtual terminal emulator widget (VTE)

Defining own widget styles using .gtkrc-2.0

o Documents

Switching between documents

Cloning documents

o Character sets and Unicode Byte-Order-Mark (BOM)

Using character sets

In-file encoding specification

Special encoding "None"

Unicode Byte-Order-Mark (BOM)

o Editing


Column mode editing (rectangular selections)

Drag and drop of text


Applying new indentation settings

Detecting indent type



Code navigation history

Sending text through custom commands

Context actions


Word part completion

Scope autocompletion

User-definable snippets

Snippet keybindings

Inserting Unicode characters

o Search, replace and go to

Toolbar entries

Search bar


Matching options

Find all

Change font in search dialog text fields

Find selection

Find usage

Find in files

Filtering out version control files


Replace all

Go to symbol definition

Go to symbol declaration

Go to line

Regular expressions

Multi-line regular expressions

o View menu

Color schemes dialog

o Symbols and tags files

Workspace symbols

Global tags files

Default global tags files

Global tags file format

Pipe-separated format

CTags format

Generating a global tags file

Generating C/C++ tags files

Generating tags files on Windows

C ignore.tags
o Preferences

General Startup preferences




General Miscellaneous preferences




Interface preferences


Message window



Interface Notebook tab preferences

Editor tabs

Tab positions

Interface Toolbar preferences



Editor Features preferences


Editor Indentation preferences

Indentation group

Editor Completions preferences


Auto-close quotes and brackets

Editor Display preferences


Long line marker

Virtual spaces
Files preferences

New files

Saving files


Tools preferences

Tool paths


Template preferences

Template data

Keybinding preferences

Printing preferences

Various preferences

Statusbar Templates

Terminal (VTE) preferences

Terminal widget

o Project management

New project

Project properties

Open project

Close project

o Build menu


Default build menu items





Make custom target

Make object

Next error

Previous error

Stopping running processes

Terminal emulators

Set build commands

Build menu configuration

Build menu commands dialog

Substitutions in commands and working directories

Build menu keyboard shortcuts

Old settings

o Printing support

o Plugins

Plugin manager

o Keybindings

Switching documents

Configurable keybindings

File keybindings

Editor keybindings

Clipboard keybindings

Select keybindings

Insert keybindings

Format keybindings

Settings keybindings

Search keybindings

Go to keybindings

View keybindings

Focus keybindings

Notebook tab keybindings

Document keybindings

Project keybindings

Build keybindings

Tools keybindings
Help keybindings

Configuration files

o Configuration file paths

Paths on Unix-like systems

Paths on Windows

o Tools menu items

o Global configuration file

o Filetype definition files


System files

User files

Custom filetypes

Creating a custom filetype from an existing filetype

Filetype configuration

[styling] section

Using a named style

Reading styles from another filetype

[keywords] section

[lexer_properties] section

[settings] section

[indentation] section

[build_settings] section

Special file filetypes.common

[named_styles] section

[named_colors] section

[styling] section

[settings] section

o Filetype extensions

Filetype group membership

o Preferences file format

[build-menu] section
o Project file format

[build-menu] additions

o Templates

Template meta data

File templates

Adding file templates

Customizing templates

Template wildcards

Special {command:} wildcard

o Customizing the toolbar

Manually editing the toolbar layout

Available toolbar elements

Plugin documentation

o HTML Characters

Insert entity dialog

Replace special chars by its entity

At typing time

Bulk replacement

o Save Actions

Auto Save

Save on focus out

Instant Save

Backup Copy

Contributing to this document

Scintilla keyboard commands

o Keyboard commands

Tips and tricks

o Document notebook

o Editor

o Interface

o GTK-related
Compile-time options

o src/geany.h

o project.h

o filetypes.c

o editor.h

o keyfile.c

o build.c

GNU General Public License

License for Scintilla and SciTE


About Geany

Geany is a small and lightweight Integrated Development Environment. It was developed to

provide a small and fast IDE, which has only a few dependencies on other packages. Another
goal was to be as independent as possible from a particular Desktop Environment like KDE or
GNOME - Geany only requires the GTK+ runtime libraries.

Some basic features of Geany:

Syntax highlighting

Code folding

Autocompletion of symbols/words

Construct completion/snippets

Auto-closing of XML and HTML tags


Many supported filetypes including C, Java, PHP, HTML, Python, Perl, Pascal, and

Symbol lists

Code navigation

Build system to compile and execute your code

Simple project management

Plugin interface

Where to get it

You can obtain Geany from or perhaps also from your distribution. For
a list of available packages, please see

Geany is distributed under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your option) any later version.
A copy of this license can be found in the file COPYING included with the source code of this
program and in the chapter, GNU General Public License.

The included Scintilla library (found in the subdirectory scintilla/) has its own license, which can
be found in the chapter, License for Scintilla and SciTE.

About this document

This documentation is available in HTML and text formats. The latest version can always be
found at

If you want to contribute to it, see Contributing to this document.



You will need the GTK (>= 2.24) libraries and their dependencies (Pango, GLib and ATK). Your
distro should provide packages for these, usually installed by default. For Windows, you can
download an installer from the website which bundles these libraries.

Binary packages

There are many binary packages available. For an up-to-date but maybe incomplete list

Source compilation

Compiling Geany is quite easy. To do so, you need the GTK (>= 2.24) libraries and header files.
You also need the Pango, GLib and ATK libraries and header files. All these files are available
at, but very often your distro will provide development packages to save
the trouble of building these yourself.

Furthermore you need, of course, a C and C++ compiler. The GNU versions of these tools are

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 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.

Installation prefix

If you want to find Geany's system files after installation you may want to know the installation

Pass the --print-prefix option to Geany to check this - see Command line options. The first path
is the prefix.

On Unix-like systems this is commonly /usr if you installed from a binary package,
or /usr/local if you build from source.


Editing system files is not necessary as you should use the per-user configuration files instead,
which don't need root permissions. See Configuration files.


Getting started

You can start Geany in the following ways:

From the Desktop Environment menu:

Choose in your application menu of your used Desktop Environment: Development --> Geany.

At Windows-systems you will find Geany after installation inside the application menu within
its special folder.

From the command line:

To start Geany from a command line, type the following and press Return:

% geany

The Geany workspace

The Geany window is shown in the following figure:

The workspace has the following parts:

The menu.

An optional toolbar.

An optional sidebar that can show the following tabs:

o Documents - A document list, and

o Symbols - A list of symbols in your code.

The main editor window.

An optional message window which can show the following tabs:

o Status - A list of status messages.

o Compiler - The output of compiling or building programs.

o Messages - Results of 'Find Usage', 'Find in Files' and other actions

o Scribble - A text scratchpad for any use.

o Terminal - An optional terminal window.

A status bar

Most of these can be configured in the Interface preferences, the View menu, or the popup
menu for the relevant area.

Additional tabs may be added to the sidebar and message window by plugins.

The position of the tabs can be selected in the interface preferences.

The sizes of the sidebar and message window can be adjusted by dragging the dividers.

Command line options

Long option Function

Set initial line number for the first opened file (same as --
line, do not put a space between the + sign and the
none +number
number). E.g. "geany +7" will open the file
and place the cursor in line 7.

none --column Set initial column number for the first opened file.

Use an alternate configuration directory. The default

-c --
configuration directory is ~/.config/geany/ and that is
dir_name config=directory_name
where geany.conf and other configuration files reside.

Print a list of Geany's internal filetype names (useful for

none --ft-names
snippets configuration).

Generate a global tags file (see Generating a global tags

-g --generate-tags

-P --no-preprocessing Don't preprocess C/C++ files when generating tags file.

Do not open files in a running instance, force opening a

-i --new-instance new instance. Only available if Geany was compiled with
support for Sockets.

-l --line Set initial line number for the first opened file.

Return a list of open documents in a running Geany

none --list-documents instance. This can be used to read the currently opened
documents in Geany from an external script or tool. The
Long option Function

returned list is separated by newlines (LF) and consists of

the full, UTF-8 encoded filenames of the documents. Only
available if Geany was compiled with support for Sockets.

Do not show the message window. Use this option if you

-m --no-msgwin
do not need compiler messages or VTE support.

Do not load symbol completion and call tip data. Use this
-n --no-ctags
option if you do not want to use them.

-p --no-plugins Do not load plugins or plugin support.

Print installation prefix, the data directory, the lib

directory and the locale directory (in that order) to
none --print-prefix
stdout, one line each. This is mainly intended for plugin
authors to detect installation paths.

Open all files given on the command line in read-only

mode. This only applies to files opened explicitly from the
-r --read-only
command line, so files from previous sessions or project
files are unaffected.

-s --no-session Do not load the previous session's files.

Do not load terminal support. Use this option if you do

not want to load the virtual terminal emulator widget at
-t --no-terminal startup. If you do not have installed, then
terminal-support is automatically disabled. Only available
if Geany was compiled with support for VTE.

Use this socket filename for communication with a

running Geany instance. This can be used with the
following command to execute Geany on the current
none --socket-file workspace:

geany --socket-file=/tmp/geany-sock-$(xprop -root

_NET_CURRENT_DESKTOP | awk '{print $3}')

Specify explicitly the path including filename or only the

filename to the VTE library,
none --vte-lib e.g./usr/lib/ or This option is only
needed when the auto-detection does not work. Only
available if Geany was compiled with support for VTE.

-v --verbose Be verbose (print useful status messages).

Long option Function

-V --version Show version information and exit.

-? --help Show help information and exit.

Open all given files at startup. This option causes Geany

to ignore loading stored files from the last session (if
enabled). Geany also recognizes line and column
information when appended to the filename with colons,
none [files ...] e.g. "geany" will open the file and
place the cursor in line 10 at column 5.

Projects can also be opened but a project file (*.geany)

must be the first non-option argument. All additionally
given files are ignored.

You can also pass line number and column number information, e.g.:


Geany supports all generic GTK options, a list is available on the help screen.



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 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 appropriate command line option.

Opening files from the command-line in a running instance

Geany detects if there is an instance of itself already running and opens files from the
command-line in that instance. So, Geany can be used to view and edit files by opening them
from other programs such as a file manager.

You can also pass line number and column number information, e.g.:


This would open the file with the cursor on line 55, column 4.

If you do not like this for some reason, you can disable using the first instance by using the
appropriate command line option -- see the section called Command line options.

Virtual terminal emulator widget (VTE)

If you have installed 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 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.


Geany tries to load If this fails, it tries to load some other filenames. If this fails too,
you should check whether you installed libvte correctly. Again note, Geany will run without
this library.

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

# ln -s /usr/lib/ /usr/lib/

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

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.

Defining own widget styles using .gtkrc-2.0

You can define your widget style for many of Geany's GUI parts. To do this, just edit
your .gtkrc-2.0 (usually found in your home directory on UNIX-like systems and in the etc
subdirectory of your Geany installation on Windows).

To have a defined style used by Geany you must assign it to at least one of Geany's widgets.
For example use the following line:

widget "Geany*" style "geanyStyle"

This would assign your style "geany_style" to all Geany widgets. You can also assign styles only
to specific widgets. At the moment you can use the following widgets:









An example of a simple .gtkrc-2.0:

style "geanyStyle"

font_name="Sans 12"

widget "GeanyMainWindow" style "geanyStyle"

style "geanyStyle"

font_name="Sans 10"

widget "GeanyPrefsDialog" style "geanyStyle"


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.

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.

Character sets and Unicode Byte-Order-Mark (BOM)

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 */


# 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 ]*


These specifications must be in the first 512 bytes of the file. Anything after the first 512 bytes
will not be recognized.

Some examples are:

# encoding = ISO-8859-15


# 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 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.


If you are unsure what a BOM is or if you do not understand where to use it, then it is probably
not important for you and you can safely ignore it.


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.


You can customize the folding icon and line styles - see the filetypes.common Folding Settings.

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

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.


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

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:


Indent with Tab characters.


Indent with spaces.


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

Applying new indentation settings

After changing the default settings you may wish to apply the new settings to every document
in the current session. To do this use the Project->Apply Default Indentation menu item.

Detecting indent type

The Detect from file indentation preference can be used to scan each file as it's opened and set
the indent type based on how many lines start with a tab vs. 2 or more spaces.


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

Geany has four types of auto-indentation:


Disables auto-indentation completely.


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.


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

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.