gsettings-data-convert

gsettings-data-convert [OPTION…] SCHEMA-DIR…

--help
    Print help information and exit

--version
    Print version information and exit

The gsettings-data-convert command is a utility from the GLib library used to migrate user configuration data from the deprecated GConf system to the modern GSettings/dconf backend. It is primarily invoked during system upgrades or package installations in GNOME-based environments to preserve user preferences seamlessly.

This tool scans specified schema directories for migration definition files located in a migrate subdirectory. These XML files (e.g., path-to-schema.xml or numbered like 10_org.gnome.example.gschema.xml) define mappings between old GConf keys/values and new GSettings schema keys. It supports value transformations via matchers, lists, and maps, allowing complex conversions like type changes or computations.

During execution, it loads GConf data, applies the mappings to create or update dconf database entries, and optionally removes migrated GConf keys if specified in the migration file. The process is non-interactive and designed to be idempotent—running multiple times won't duplicate data.

Common use cases include distro packagers running it post-upgrade (e.g., via postinst scripts) or administrators migrating legacy setups. It requires write access to ~/.config/dconf and reads from GConf's XML databases.

Requires migration XML files in SCHEMA-DIR/migrate/; skips absent mappings. Always backs up data implicitly but test in safe environments. Not for interactive use—intended for scripts.

XML rules in SCHEMA-DIR/migrate/*.xml use <match>, <apply>, <remove> tags for key mapping, value conversion (e.g., string-to-int), and cleanup.

Introduced in GLib 2.28 (2010) alongside GSettings to facilitate GNOME 3's shift from GConf. Actively used in Fedora/Ubuntu upgrades through GNOME 40+; maintained in glib2.0 package.

gsettings(1), dconf(1), glib-compile-schemas(1), gconftool(1)