gimp/docs/gimprc.5.in

.\" This man-page is auto-generated by gimp --dump-gimprc-manpage.

.TH GIMPRC 5 "Version @GIMP_VERSION@" "GIMP Manual Pages"
.SH NAME
gimprc \- gimp configuration file
.SH DESCRIPTION
The
.B gimprc
file is a configuration file read by the GIMP when it starts up.  There
are two of these: one system-wide one stored in
@gimpsysconfdir@/gimprc and a per-user \fB$HOME\fP/@gimpdir@/gimprc
which may override system settings.

Comments are introduced by a hash sign (#), and continue until the end
of the line.  Blank lines are ignored.

The
.B gimprc
file associates values with properties.  These properties may be set
by lisp-like assignments of the form:
.IP
\f3(\f2property\-name\ value\f3)\f1
.TP
where:
.TP 10
.I property\-name
is one of the property names described below.
.TP
.I value
is the value the property is to be set to.
.PP

Either spaces or tabs may be used to separate the name from the value.
.PP
.SH PROPERTIES
Valid properties and their default values are:

.TP
(temp-path "${gimp_dir}/tmp")

Sets the folder for temporary storage. Files will appear here during the
course of running the GIMP.  Most files will disappear when the GIMP exits,
but some files are likely to remain, so it is best if this folder not be one
that is shared by other users.  This is a single folder.

.TP
(swap-path "${gimp_dir}")

Sets the swap file location. GIMP uses a tile based memory allocation scheme.
The swap file is used to quickly and easily swap tiles out to disk and back
in. Be aware that the swap file can easily get very large if GIMP is used with
large images. Also, things can get horribly slow if the swap file is created
on a folder that is mounted over NFS.  For these reasons, it may be desirable
to put your swap file in "/tmp".  This is a single folder.

.TP
(num-processors 2)

On multiprocessor machines, if GIMP has been compiled with --enable-mp this
sets how many processors GIMP should use simultaneously.  This is an integer
value.

.TP
(tile-cache-size 256M)

The tile cache is used to make sure the GIMP doesn't thrash tiles between
memory and disk. Setting this value higher will cause the GIMP to use less
swap space, but will also cause the GIMP to use more memory. Conversely, a
smaller cache size causes the GIMP to use more swap space and less memory. 
The integer size can contain a suffix of 'B', 'K', 'M' or 'G' which makes GIMP
interpret the size as being specified in bytes, kilobytes, megabytes or
gigabytes. If no suffix is specified the size defaults to being specified in
kilobytes.

.TP
(interpolation-type linear)

Sets the level of interpolation used for scaling and other transformations. 
Possible values are none, linear, cubic and lanczos.

.TP
(plug-in-path "${gimp_dir}/plug-ins:${gimp_plug_in_dir}/plug-ins")

Sets the plug-in search path.  This is a colon-separated list of folders to
search.

.TP
(module-path "${gimp_dir}/modules:${gimp_plug_in_dir}/modules")

Sets the module search path.  This is a colon-separated list of folders to
search.

.TP
(interpreter-path "${gimp_dir}/interpreters:${gimp_plug_in_dir}/interpreters")

Sets the interpreter search path.  This is a colon-separated list of folders
to search.

.TP
(environ-path "${gimp_dir}/environ:${gimp_plug_in_dir}/environ")

Sets the environ search path.  This is a colon-separated list of folders to
search.

.TP
(brush-path "${gimp_dir}/brushes:${gimp_data_dir}/brushes")

Sets the brush search path.  This is a colon-separated list of folders to
search.

.TP
(brush-path-writable "${gimp_dir}/brushes")

  This is a colon-separated list of folders to search.

.TP
(pattern-path "${gimp_dir}/patterns:${gimp_data_dir}/patterns")

Sets the pattern search path.  This is a colon-separated list of folders to
search.

.TP
(pattern-path-writable "${gimp_dir}/patterns")

  This is a colon-separated list of folders to search.

.TP
(palette-path "${gimp_dir}/palettes:${gimp_data_dir}/palettes")

Sets the palette search path.  This is a colon-separated list of folders to
search.

.TP
(palette-path-writable "${gimp_dir}/palettes")

  This is a colon-separated list of folders to search.

.TP
(gradient-path "${gimp_dir}/gradients:${gimp_data_dir}/gradients")

Sets the gradient search path.  This is a colon-separated list of folders to
search.

.TP
(gradient-path-writable "${gimp_dir}/gradients")

  This is a colon-separated list of folders to search.

.TP
(font-path "${gimp_dir}/fonts:${gimp_data_dir}/fonts")

Where to look for fonts in addition to the system-wide installed fonts.  This
is a colon-separated list of folders to search.

.TP
(default-brush "Circle (11)")

Specify a default brush.  The brush is searched for in the specified brush
path.  This is a string value.

.TP
(default-pattern "Pine")

Specify a default pattern.  This is a string value.

.TP
(default-palette "Default")

Specify a default palette.  This is a string value.

.TP
(default-gradient "FG to BG (RGB)")

Specify a default gradient.  This is a string value.

.TP
(default-font "Sans")

Specify a default font.  This is a string value.

.TP
(global-brush yes)

When enabled, the selected brush will be used for all tools.  Possible values
are yes and no.

.TP
(global-pattern yes)

When enabled, the selected pattern will be used for all tools.  Possible
values are yes and no.

.TP
(global-palette yes)

When enabled, the selected palette will be used for all tools.  Possible
values are yes and no.

.TP
(global-gradient yes)

When enabled, the selected gradient will be used for all tools.  Possible
values are yes and no.

.TP
(global-font yes)

When enabled, the selected font will be used for all tools.  Possible values
are yes and no.

.TP
(default-image
    (width 377)
    (height 233)
    (unit pixels)
    (xresolution 72.000000)
    (yresolution 72.000000)
    (resolution-unit inches)
    (image-type rgb)
    (fill-type background-fill)
    (comment "Created with GIMP"))

Sets the default image in the "File/New" dialog.  This is a parameter list.

.TP
(default-grid
    (style intersections)
    (fgcolor (color-rgba 0.000000 0.000000 0.000000 1.000000))
    (bgcolor (color-rgba 1.000000 1.000000 1.000000 1.000000))
    (xspacing 32.000000)
    (yspacing 32.000000)
    (spacing-unit inches)
    (xoffset 0.000000)
    (yoffset 0.000000)
    (offset-unit inches))

Specify a default image grid.  This is a parameter list.

.TP
(undo-levels 5)

Sets the minimal number of operations that can be undone. More undo levels are
kept available until the undo-size limit is reached.  This is an integer
value.

.TP
(undo-size 16M)

Sets an upper limit to the memory that is used per image to keep operations on
the undo stack. Regardless of this setting, at least as many undo-levels as
configured can be undone.  The integer size can contain a suffix of 'B', 'K',
\&'M' or 'G' which makes GIMP interpret the size as being specified in bytes,
kilobytes, megabytes or gigabytes. If no suffix is specified the size defaults
to being specified in kilobytes.

.TP
(undo-preview-size large)

Sets the size of the previews in the Undo History.  Possible values are tiny,
extra-small, small, medium, large, extra-large, huge, enormous and gigantic.

.TP
(plug-in-history-size 10)

How many recently used plug-ins to keep on the Filters menu.  This is an
integer value.

.TP
(pluginrc-path "${gimp_dir}/pluginrc")

Sets the pluginrc search path.  This is a single filename.

.TP
(layer-previews yes)

Sets whether GIMP should create previews of layers and channels. Previews in
the layers and channels dialog are nice to have but they can slow things down
when working with large images.  Possible values are yes and no.

.TP
(layer-preview-size medium)

Sets the preview size used for layers and channel previews in newly created
dialogs.  Possible values are tiny, extra-small, small, medium, large,
extra-large, huge, enormous and gigantic.

.TP
(thumbnail-size normal)

Sets the size of the thumbnail shown in the Open dialog. Note that GIMP can
not create thumbnails if layer previews are disabled.  Possible values are
none, normal and large.

.TP
(thumbnail-filesize-limit 4M)

The thumbnail in the Open dialog will be automatically updated if the file
being previewed is smaller than the size set here.  The integer size can
contain a suffix of 'B', 'K', 'M' or 'G' which makes GIMP interpret the size
as being specified in bytes, kilobytes, megabytes or gigabytes. If no suffix
is specified the size defaults to being specified in kilobytes.

.TP
(install-colormap no)

Install a private colormap; might be useful on 8-bit (256 colors) displays. 
Possible values are yes and no.

.TP
(min-colors 144)

Generally only a concern for 8-bit displays, this sets the minimum number of
system colors allocated for the GIMP.  This is an integer value.

.TP
(color-management
    (mode display)
    (display-profile-from-gdk yes)
    (display-rendering-intent perceptual)
    (simulation-rendering-intent perceptual)
    (display-module "CdisplayLcms"))

Defines the color management behavior.  This is a parameter list.

.TP
(save-document-history yes)

Add all opened and saved files to the document history on disk.  Possible
values are yes and no.

.TP
(transparency-size medium-checks)

Sets the size of the checkerboard used to display transparency.  Possible
values are small-checks, medium-checks and large-checks.

.TP
(transparency-type gray-checks)

Sets the manner in which transparency is displayed in images.  Possible values
are light-checks, gray-checks, dark-checks, white-only, gray-only and
black-only.

.TP
(snap-distance 8)

This is the distance in pixels where Guide and Grid snapping activates.  This
is an integer value.

.TP
(marching-ants-speed 300)

Speed of marching ants in the selection outline.  This value is in
milliseconds (less time indicates faster marching).  This is an integer value.

.TP
(resize-windows-on-zoom no)

When enabled, the image window will automatically resize itself when zooming
into and out of images.  Possible values are yes and no.

.TP
(resize-windows-on-resize no)

When enabled, the image window will automatically resize itself whenever the
physical image size changes.  Possible values are yes and no.

.TP
(default-dot-for-dot yes)

When enabled, this will ensure that each pixel of an image gets mapped to a
pixel on the screen.  Possible values are yes and no.

.TP
(initial-zoom-to-fit yes)

When enabled, this will ensure that the full image is visible after a file is
opened, otherwise it will be displayed with a scale of 1:1.  Possible values
are yes and no.

.TP
(perfect-mouse yes)

When enabled, the X server is queried for the mouse's current position on each
motion event, rather than relying on the position hint.  This means painting
with large brushes should be more accurate, but it may be slower.  Perversely,
on some X servers enabling this option results in faster painting.  Possible
values are yes and no.

.TP
(cursor-mode tool-icon)

Sets the type of mouse pointers to use.  Possible values are tool-icon,
tool-crosshair and crosshair.

.TP
(cursor-updating yes)

Context-dependent mouse pointers are helpful.  They are enabled by default. 
However, they require overhead that you may want to do without.  Possible
values are yes and no.

.TP
(show-brush-outline yes)

When enabled, all paint tools will show a preview of the current brush's
outline.  Possible values are yes and no.

.TP
(show-paint-tool-cursor yes)

When enabled, the mouse pointer will be shown over the image while using a
paint tool.  Possible values are yes and no.

.TP
(image-title-format "%D*%f-%p.%i (%t, %L) %wx%h")

Sets the text to appear in image window titles.  This is a format string;
certain % character sequences are recognised and expanded as follows:
.br

.br
%%  literal percent sign
.br
%f  bare filename, or "Untitled"
.br
%F  full path to file, or "Untitled"
.br
%p  PDB image id
.br
%i  view instance number
.br
%t  image type (RGB, grayscale, indexed)
.br
%z  zoom factor as a percentage
.br
%s  source scale factor
.br
%d  destination scale factor
.br
%Dx expands to x if the image is dirty, the empty string otherwise
.br
%Cx expands to x if the image is clean, the empty string otherwise
.br
%B  expands to (modified) if the image is dirty, the empty string otherwise
.br
%A  expands to (clean) if the image is clean, the empty string otherwise
.br
%l  the number of layers
.br
%L  the number of layers (long form)
.br
%m  memory used by the image
.br
%n  the name of the active layer/channel
.br
%P  the PDB id of the active layer/channel
.br
%w  image width in pixels
.br
%W  image width in real-world units
.br
%h  image height in pixels
.br
%H  image height in real-world units
.br
%u  unit symbol
.br
%U  unit abbreviation
.br

.br

.TP
(image-status-format "%n (%m)")

Sets the text to appear in image window status bars.  This is a format string;
certain % character sequences are recognised and expanded as follows:
.br

.br
%%  literal percent sign
.br
%f  bare filename, or "Untitled"
.br
%F  full path to file, or "Untitled"
.br
%p  PDB image id
.br
%i  view instance number
.br
%t  image type (RGB, grayscale, indexed)
.br
%z  zoom factor as a percentage
.br
%s  source scale factor
.br
%d  destination scale factor
.br
%Dx expands to x if the image is dirty, the empty string otherwise
.br
%Cx expands to x if the image is clean, the empty string otherwise
.br
%B  expands to (modified) if the image is dirty, the empty string otherwise
.br
%A  expands to (clean) if the image is clean, the empty string otherwise
.br
%l  the number of layers
.br
%L  the number of layers (long form)
.br
%m  memory used by the image
.br
%n  the name of the active layer/channel
.br
%P  the PDB id of the active layer/channel
.br
%w  image width in pixels
.br
%W  image width in real-world units
.br
%h  image height in pixels
.br
%H  image height in real-world units
.br
%u  unit symbol
.br
%U  unit abbreviation
.br

.br

.TP
(confirm-on-close yes)

Ask for confirmation before closing an image without saving.  Possible values
are yes and no.

.TP
(monitor-xresolution 72.000000)

Sets the monitor's horizontal resolution, in dots per inch.  If set to 0,
forces the X server to be queried for both horizontal and vertical resolution
information.  This is a float value.

.TP
(monitor-yresolution 72.000000)

Sets the monitor's vertical resolution, in dots per inch.  If set to 0, forces
the X server to be queried for both horizontal and vertical resolution
information.  This is a float value.

.TP
(monitor-resolution-from-windowing-system yes)

When enabled, the GIMP will use the monitor resolution from the windowing
system.  Possible values are yes and no.

.TP
(navigation-preview-size medium)

Sets the size of the navigation preview available in the lower right corner of
the image window.  Possible values are tiny, extra-small, small, medium,
large, extra-large, huge, enormous and gigantic.

.TP
(default-view
    (show-menubar yes)
    (show-rulers yes)
    (show-scrollbars yes)
    (show-statusbar yes)
    (show-selection yes)
    (show-layer-boundary yes)
    (show-guides yes)
    (show-grid no)
    (show-sample-points yes)
    (padding-mode default)
    (padding-color (color-rgb 1.000000 1.000000 1.000000)))

Sets the default settings for the image view.  This is a parameter list.

.TP
(default-fullscreen-view
    (show-menubar yes)
    (show-rulers yes)
    (show-scrollbars yes)
    (show-statusbar yes)
    (show-selection yes)
    (show-layer-boundary yes)
    (show-guides yes)
    (show-grid no)
    (show-sample-points yes)
    (padding-mode default)
    (padding-color (color-rgb 1.000000 1.000000 1.000000)))

Sets the default settings used when an image is viewed in fullscreen mode. 
This is a parameter list.

.TP
(activate-on-focus yes)

When enabled, an image will become the active image when its image window
receives the focus. This is useful for window managers using "click to focus".
 Possible values are yes and no.

.TP
(default-threshold 15)

Tools such as fuzzy-select and bucket fill find regions based on a seed-fill
algorithm.  The seed fill starts at the initially selected pixel and
progresses in all directions until the difference of pixel intensity from the
original is greater than a specified threshold. This value represents the
default threshold.  This is an integer value.

.TP
(move-tool-changes-active no)

If enabled, the move tool changes the active layer or path when a layer or
path is being picked. This used to be the default behaviour in older versions.
 Possible values are yes and no.

.TP
(trust-dirty-flag no)

When enabled, the GIMP will not save an image if it has not been changed since
it was opened.  Possible values are yes and no.

.TP
(save-device-status no)

Remember the current tool, pattern, color, and brush across GIMP sessions. 
Possible values are yes and no.

.TP
(save-session-info yes)

Save the positions and sizes of the main dialogs when the GIMP exits. 
Possible values are yes and no.

.TP
(restore-session yes)

Let GIMP try to restore your last saved session on each startup.  Possible
values are yes and no.

.TP
(save-tool-options no)

Save the tool options when the GIMP exits.  Possible values are yes and no.

.TP
(show-tips yes)

Enable displaying a handy GIMP tip on startup.  Possible values are yes and
no.

.TP
(show-tooltips yes)

Show a tooltip when the pointer hovers over an item.  Possible values are yes
and no.

.TP
(tearoff-menus yes)

When enabled, menus can be torn off.  Possible values are yes and no.

.TP
(can-change-accels no)

When enabled, you can change keyboard shortcuts for menu items by hitting a
key combination while the menu item is highlighted.  Possible values are yes
and no.

.TP
(save-accels yes)

Save changed keyboard shortcuts when the GIMP exits.  Possible values are yes
and no.

.TP
(restore-accels yes)

Restore saved keyboard shortcuts on each GIMP startup.  Possible values are
yes and no.

.TP
(menu-mnemonics yes)

When enabled, GIMP will show mnemonics in menus.  Possible values are yes and
no.

.TP
(last-opened-size 10)

How many recently opened image filenames to keep on the File menu.  This is an
integer value.

.TP
(max-new-image-size 64M)

GIMP will warn the user if an attempt is made to create an image that would
take more memory than the size specified here.  The integer size can contain a
suffix of 'B', 'K', 'M' or 'G' which makes GIMP interpret the size as being
specified in bytes, kilobytes, megabytes or gigabytes. If no suffix is
specified the size defaults to being specified in kilobytes.

.TP
(toolbox-color-area no)

The toolbox-color-area property has no description.  Possible values are yes
and no.

.TP
(toolbox-foo-area no)

The toolbox-foo-area property has no description.  Possible values are yes and
no.

.TP
(toolbox-image-area no)

The toolbox-image-area property has no description.  Possible values are yes
and no.

.TP
(theme-path "${gimp_dir}/themes:${gimp_data_dir}/themes")

Sets the theme search path.  This is a colon-separated list of folders to
search.

.TP
(theme "Default")

The name of the theme to use.  This is a string value.

.TP
(use-help yes)

When enabled, pressing F1 will open the help browser.  Possible values are yes
and no.

.TP
(show-help-button yes)

When enabled, dialogs will show a help button that gives access to the related
help page.  Without this button, the help page can still be reached by
pressing F1.  Possible values are yes and no.

.TP
(help-locales "")

Specifies the language preferences used by the help system. This is a
colon-separated list of language identifiers with decreasing priority. If
empty, the language is taken from the user's locale setting.  This is a string
value.

.TP
(help-browser gimp)

Sets the browser used by the help system.  Possible values are gimp and
web-browser.

.TP
(web-browser "mozilla-firefox %s")

Sets the external web browser to be used.  This can be an absolute path or the
name of an executable to search for in the user's PATH. If the command
contains '%s' it will be replaced with the URL, else the URL will be appended
to the command with a space separating the two.  This is a single filename.

.TP
(toolbox-window-hint utility)

The window type hint that is set on the toolbox. This may affect how your
window manager decorates and handles the toolbox window.  Possible values are
normal, utility and keep-above.

.TP
(dock-window-hint utility)

The window type hint that is set on dock windows. This may affect the way your
window manager decorates and handles dock windows.  Possible values are
normal, utility and keep-above.

.TP
(transient-docks no)

When enabled, dock windows (the toolbox and palettes) are set to be transient
to the active image window. Most window managers will keep the dock windows
above the image window then, but it may also have other effects.  Possible
values are yes and no.

.TP
(cursor-format pixbuf)

Sets the pixel format to use for mouse pointers.  Possible values are bitmap
and pixbuf.

.TP
(fractalexplorer-path "${gimp_dir}/fractalexplorer:${gimp_data_dir}/fractalexplorer")

Where to search for fractals used by the Fractal Explorer plug-in.  This is a
colon-separated list of folders to search.

.TP
(gfig-path "${gimp_dir}/gfig:${gimp_data_dir}/gfig")

Where to search for Gfig figures used by the Gfig plug-in.  This is a
colon-separated list of folders to search.

.TP
(gflare-path "${gimp_dir}/gflare:${gimp_data_dir}/gflare")

Where to search for gflares used by the GFlare plug-in.  This is a
colon-separated list of folders to search.

.TP
(gimpressionist-path "${gimp_dir}/gimpressionist:${gimp_data_dir}/gimpressionist")

Where to search for data used by the Gimpressionist plug-in.  This is a
colon-separated list of folders to search.

.TP
(script-fu-path "${gimp_dir}/scripts:${gimp_data_dir}/scripts")

This path will be searched for scripts when the Script-Fu plug-in is run. 
This is a colon-separated list of folders to search.

.PP
.SH PATH EXPANSION
Strings of type PATH are expanded in a manner similar to
.BR bash (1).
Specifically: tilde (~) is expanded to the user's home directory. Note that
the bash feature of being able to refer to other user's home directories
by writing ~userid/ is not valid in this file.

${variable} is expanded to the current value of an environment variable.
There are a few variables that are pre-defined:
.TP
.I gimp_dir
The personal gimp directory which is set to the value of the environment
variable GIMP2_DIRECTORY or to ~/@gimpdir@.
.TP
.I gimp_data_dir
Base for paths to shareable data, which is set to the value of the
environment variable GIMP2_DATADIR or to the compiled-in default value
@gimpdatadir@.
.TP
.I gimp_plug_in_dir
Base to paths for architecture-specific plugins and modules, which is set
to the value of the environment variable GIMP2_PLUGINDIR or to the
compiled-in default value @gimpplugindir@.
.TP
.I gimp_sysconf_dir
Path to configuration files, which is set to the value of the environment
variable GIMP2_SYSCONFDIR or to the compiled-in default value 
@gimpsysconfdir@.

.SH FILES
.TP
.I @gimpsysconfdir@/gimprc
System-wide configuration file
.TP
.I \fB$HOME\fP/@gimpdir@/gimprc
Per-user configuration file

.SH "SEE ALSO"
.BR gimp (1),
.BR gimptool (1),
.BR gimp\-remote (1)