rgrc

Development Guide

Add new commands

  1. Create a new config file in share/ (e.g., conf.mycommand)
  2. Add rules in the format: 
    regexp=REGEX
colours=COLOR1,COLOR2,...
  3. Test with: 
    echo "ERROR: Something went wrong" | RGRC_DEV_SHARE=1 cargo run -- --color on -c conf.mycommand

    RGRC_DEV_SHARE=1 makes rgrc search share/ next to the repo; without it only user ($XDG_CONFIG_HOME/rgrc) and system paths are searched. -c also runs a command when one is given:

    RGRC_DEV_SHARE=1 cargo run -- --color on -c conf.mycommand mycommand --arg
  4. Enable the command in etc/rgrc.conf; colorization picks it up from there. Optionally add the name to SUPPORTED_COMMANDS in src/utils.rs so --aliases covers it; whitelist_entries_are_mapped keeps the two in sync.

Config resolution

Conf files are searched in this order (first match wins, embedded configs last):

  1. $XDG_CONFIG_HOME/rgrc (default ~/.config/rgrc)
  2. $XDG_DATA_HOME/rgrc (default ~/.local/share/rgrc)
  3. $XDG_CONFIG_DIRS/rgrc, $XDG_DATA_DIRS/rgrc (system defaults apply)
  4. grc compat paths (~/.config/grc, /usr/share/grc, …)
  5. configs embedded at build time

Mapper files (rgrc.conf) are searched the same way. Patterns match the full command line first, then the bare command name, so ^df$ also matches df -h.

bypass

A mapper entry pointing at bypass (a sentinel, not a conf file) runs the command untouched: inherited stdio (the tty stays intact) and no colorization. Use it for commands that only need colorization when invoked bare, like env:

# env wrapping another command: run it untouched (#40)
^([/\w\.]+\/)?env\s
bypass

# env listing the environment
^([/\w\.]+\/)?env\b
conf.env

Order matters: the first matching pattern wins, so the bypass pattern must come first. The same trick works for wrappers you want to exempt yourself (sudo, watch, ssh, …) via your own rgrc.conf.

Testing

# Run tests
make test
# Run tests with coverage
make cov

Code Formatting and Linting

make check

Local Installation

make install

# Uninstall
make uninstall

Advanced Features

Count/Replace

# Match only once per line
regexp=^\s*#
colours=cyan
count=once

# Replace matched text (with backreferences)
regexp=(ERROR|WARN|INFO)
colours=red,yellow,green
replace=[\1]

# Stop processing after match
regexp=^FATAL
colours=red,bold
count=stop

Count options: once, more (default), stop Replace: Supports \1, \2, etc.

256-color and truecolor

Beyond the 8 base colors and their bright_* variants:

# 256-color (0-255), grc-compatible
colours=colour_140
colours=on_colour_140

# truecolor hex
colours=rgb:ff8800
colours=on_rgb:ff8800

Both colour_ and color_ (American spelling) are accepted.

This site is open source. Improve this page.