A robust Go library for parsing, formatting, and filtering .Xresources files.
.Xresources has historically been the standard way to configure core X11 applications. By supporting a robust parsing method, configuration tools can interact deeply with user setups without requiring destructive overhauls of their files. Preserving comments, spacing, and application-specific blocks keeps user settings intact while enabling programmatic configuration updates.
The xresources library is perfect for you when:
- You need to build a configuration tool that manipulates
.Xresourcesfiles programmatically. This is extremely useful for a class of applications like terminal emulators (e.g.,XTerm,URxvt) or window managers (e.g.,i3,dwm, orxmonad) that rely on system-wide or user-level resource settings. - You want to extract all settings related to a specific application and modify them, without dropping the user's surrounding comments or breaking other applications.
- (Note: On Wayland, there is no direct equivalent to a central
.Xresourcesfile, as configurations are mostly decentralized or managed via standard configuration files per application, often using formats like TOML, YAML, or INI located in~/.config/).
- Full support for comments (
!), preprocessor macros (#), and blank lines. - AST-based parsing that allows programmatic manipulation of
Key: Valueconfigurations. - Handles multi-line values continuing with a backslash
\. - Application-specific prefix filtering (
Filter("AppPrefix")) which preserves comments tightly coupled to an application's resource section.
Download binaries from: https://github.com/your-org/xresources/releases
brew tap arran4/homebrew-tap
brew install xresourcesdocker pull ghcr.io/your-org/xresources:latest
docker run --rm ghcr.io/your-org/xresources:latest --helpgo install github.com/your-org/xresources@latest- Debian/Ubuntu (
.deb): see Releases assets - RPM (
.rpm): see Releases assets - Alpine (
.apk): see Releases assets - Arch (
.pkg.tar.zstor repo): see Releases assets
go get github.com/your-org/xresourcesYou can read an .Xresources file and write it back symmetrically:
package main
import (
"fmt"
"log"
"github.com/your-org/xresources"
)
func main() {
doc, err := xresources.ParseString(`
! XTerm settings
XTerm*faceName: Monospace
XTerm*faceSize: 10
`)
if err != nil {
log.Fatal(err)
}
// Print it out exactly as it was read
fmt.Print(doc.String())
}Often you just want to grab the settings for a single app:
package main
import (
"fmt"
"log"
"github.com/your-org/xresources"
)
func main() {
config := `
! General
*color0: black
! XTerm settings
XTerm*faceName: Monospace
XTerm*faceSize: 10
! URxvt settings
URxvt.font: xft:Monospace:size=10
`
doc, err := xresources.ParseString(config)
if err != nil {
log.Fatal(err)
}
// Extract just the XTerm lines and associated comments
xtermDoc := doc.Filter("XTerm")
fmt.Print(xtermDoc.String())
// Output will contain the XTerm settings with its leading comments.
}You can load and merge settings dynamically from different sources like XDG config paths and home directories using our flexible variadic loader:
package main
import (
"fmt"
"log"
"github.com/your-org/xresources"
)
func main() {
doc, err := xresources.Load(
xresources.UseXDG(true),
xresources.UseHomeDir(true),
xresources.MergeSystem(true),
)
if err != nil {
log.Fatal(err)
}
fmt.Print(doc.String())
}While applications can define any resource, some are widely standardized across X11 systems:
Xft.dpi: Sets the DPI (Dots Per Inch) scaling (e.g.,96,192).Xft.antialias: Enables font anti-aliasing (1ortrue,0orfalse).Xft.hinting: Enables font hinting (1ortrue,0orfalse).Xft.hintstyle: Sets hinting level (hintnone,hintslight,hintmedium,hintfull).Xft.rgba: Subpixel rendering type (rgb,bgr,vrgb,vbgr, ornone).Xft.lcdfilter: LCD filter type (e.g.,lcddefault).Xft.autohint: Enables autohinter (1ortrue,0orfalse).
Xcursor.theme: The cursor theme name (e.g.,Adwaita,Vanilla-DMZ).Xcursor.size: The size of the cursor in pixels (e.g.,16,32,48).
XTerm*faceName: The TrueType font used (e.g.,xft:Monospace:size=10).XTerm*faceSize: Size of the font.XTerm*background: Background color (e.g.,#282C34).XTerm*foreground: Foreground text color.
URxvt.font: Main font string (e.g.,xft:Monospace:size=10).URxvt.scrollBar: Toggles the scrollbar (true,false).URxvt.geometry: Sets initial window size (80x24).URxvt.transparent: Enables pseudo-transparency.URxvt.depth: Used for true transparency (e.g.,32).
Most terminal emulators share a common color palette scheme:
*color0to*color7: Standard ANSI colors (Black, Red, Green, Yellow, Blue, Magenta, Cyan, White).*color8to*color15: Bright ANSI colors.*background: Default background.*foreground: Default foreground.
Many other X11 applications can be configured via .Xresources. For application-specific configuration details, refer to their official documentation:
- XScreenSaver: XScreenSaver Documentation
- xpdf: xpdf Manual
- rxvt-unicode (URxvt): urxvt(1) Manual Page
- XTerm: xterm(1) Manual Page
- rofi: rofi(1) Manual Page (Legacy Xresources)
The .Xresources document syntax uses the following elements:
- Comments: Lines starting with
!are ignored or treated as comments. - Preprocessor Directives: Lines starting with
#are used for#define,#include, etc. - Resources: Key-value pairs defined as
Key: Value, whereKeyidentifies an application or resource path (often separated by*or.), andValueis the content. - Line Continuations: Multi-line strings can be formed using a trailing
\at the end of a line. - Empty Lines: Ignored functionally, but preserved by this parser to ensure identical rewrites.