Load and Safely Test X Resources with xrdb

Change one X resource carelessly and xrdb will happily wipe out every other setting an app was relying on, which is why previewing first matters. You will preview a resource file, load it into the current X display, query what the server is storing, and make a small change without replacing unrelated settings. The examples use the installed xrdb 1.2.2 from the Debian x11-xserver-utils package.

Allow about fifteen minutes. You need an active X display, a shell, and a resource file you are willing to test. The examples do not need sudo. If DISPLAY is empty, stop at the first checkpoint: there is no X server for xrdb to contact.

Safety boundary: Loading resources changes properties on the X server. It does not edit your file, but it can replace settings used by running X clients. Keep a copy of the file and query the current database before using the replacing default.

1. Check the binary and display

Confirm which command will run, its version, and the display selected by the environment:

$ command -v xrdb
/usr/bin/xrdb
$ xrdb -version
xrdb 1.2.2
$ printf 'DISPLAY=%s\n' "$DISPLAY"
DISPLAY=:0

Your display value and path may differ. -version exits without performing another operation. If the last line is empty, set DISPLAY to the display used by your session only when you know that value:

$ export DISPLAY=':0'

Do not guess a remote display name or copy one from an unrelated session. An incorrect display can produce a connection error or send settings to the wrong X server.

2. Make a small resource file

Use a new file in a temporary directory for the first test. X resources use names such as xterm*background and values such as black. Lines beginning with ! are comments. This sample changes an xterm background if an xterm reads the resource, and also gives you a harmless value to query:

$ work_dir="$(mktemp -d)"
$ resource_file="$work_dir/test.Xresources"
$ cp /dev/null "$resource_file"
$ printf '%s\n' \
    '! temporary xrdb test' \
    'XTerm*background: grey20' \
    'XrdbTest.value: loaded' > "$resource_file"
$ sed -n '1,10p' "$resource_file"
! temporary xrdb test
XTerm*background: grey20
XrdbTest.value: loaded

The file is input to xrdb; it is not itself a database. The server stores resources in the RESOURCE_MANAGER property and, when relevant, in screen-specific properties. A resource line can be accepted by the database even when no current client uses that resource.

3. Preview preprocessing without changing the display

Before loading, use -n to show the change without performing it. -E shows the preprocessor command and processed input. The combination is a dry run:

$ xrdb -n -E "$resource_file"
/usr/bin/cpp -traditional -D... "$resource_file"
XTerm*background: grey20
XrdbTest.value: loaded

The command and server-derived symbols vary with the host, so treat the output above as representative. The useful check is that the input resource lines appear and the command exits successfully. The installed manual says that -n prints the proposed changes but does not perform them.

If you do not want preprocessing, add -nocpp. That is useful for a plain resource file, but it also means that preprocessor directives and macros are not expanded:

$ xrdb -n -nocpp "$resource_file"
XTerm*background: grey20
XrdbTest.value: loaded

Do not treat -E as a dry run by itself. The manual explicitly says changes are still performed unless -n is also present.

4. Load the file, knowing what gets replaced

Once the preview is correct, load it with the explicit -load action:

$ xrdb -load "$resource_file"
$ printf 'load exit status: %s\n' "$?"
load exit status: 0

-load replaces the old contents of the selected properties. It is also the default action, which is why spelling it out in a script makes the state change easier to review. Do not run a bare xrdb "$resource_file" against a valuable database unless replacing the existing resources is exactly what you intend.

If a load damages a client configuration, the undo is another load from a known-good resource file. If you did not save one, query the old database before making further changes and reconstruct a file from that output where possible. A query cannot restore comments or preprocessor directives.

5. Verify the server-side value

Query the stored resources rather than assuming a successful exit status proves that a client will use them:

$ xrdb -query | grep -F 'XrdbTest.value'
XrdbTest.value: loaded

-query prints the current contents of the selected properties. To ask for one named property, use -get:

$ xrdb -get XrdbTest.value
loaded

The distinction matters. -query is a database dump, while -get returns the value for the property matching the name. If either command cannot connect, recheck DISPLAY, the X session, and access control. Do not reach for sudo: root normally does not have the same X authorisation as your desktop user.

6. Add a change with merge or override

Use -override when you want new entries added and duplicate entries to win over previous ones:

$ printf '%s\n' 'XrdbTest.value: override' > "$work_dir/override.Xresources"
$ xrdb -override "$work_dir/override.Xresources"
$ xrdb -get XrdbTest.value
override

Use -merge when you want the input merged and sorted lexicographically instead of replacing the property. The two actions are different: neither is a general backup mechanism, and neither preserves a preprocessor directive inside the server property.

For a repeatable configuration, keep the source file under your home directory and load it during your X session startup. The usual file is ~/.Xresources; xrdb does not load it automatically. Desktop startup tools may do that for you, but check the session configuration rather than assuming it.

7. Avoid the options that change more than you need

The default -all mode operates on the screen-independent RESOURCE_MANAGER property and screen-specific properties as appropriate. Use -global for only the screen-independent property, -screen for the default screen's screen-specific property, or -screens for the screen-specific property on every screen. These distinctions matter on multi-screen displays; leave the default in place unless you have a reason to target one class of property.

-remove removes the selected properties. That is a destructive configuration change, so query or save the current contents first:

$ backup_file="$work_dir/resources-before-remove.txt"
$ xrdb -query > "$backup_file"
$ wc -l "$backup_file"
12 /tmp/example/resources-before-remove.txt

Do not use -remove in a cleanup script just because a query is empty. An empty result may mean the wrong display or property scope, not that removal is needed. To recover, reload the saved file with xrdb -load "$backup_file", after checking its contents.

Done means