i3wsr - i3 workspace renamer

i3wsr is a small program that uses I3's IPC Interface to change the name of a workspace based on its contents.

Table of content

• Details
• Requirements
• Installation
  • Arch linux
• Usage
• i3 configuration
• Configuration / options
  • Icons
  • Aliases
  • Separator
  • Default icon
  • No names
  • Remove duplicates
  • Use instance
• Sway
• Contributors
• Test environment
• Attribution

Details

The chosen name for a workspace is a composite of the WM_CLASS X11 window property for each window in a workspace. In action it would look something like this:

Requirements

i3wsr requires XCB, if you get compilation errors mentioning xcb, you might need to install libxcb. On Ubuntu for example you'd install:

sudo apt-get install libxcb1-dev

Refer to #18 for more.

Installation

Rust, and Cargo is required, and i3wsr can be installed using cargo like so:

cargo install i3wsr

Or alternatively, you can build a release binary,

cargo build --release

Then place the built binary, located at target/release/i3wsr, somewhere on your $path.

Arch linux

If you're running Arch you can install either stable, or latest from AUR thanks to reddit user u/OniTux.

Usage

Just launch the program and it'll listen for events if you are running I3. Another option is to put something like this in your i3 config

# cargo
exec_always --no-startup-id $HOME/.cargo/bin/i3wsr
# AUR
exec_always --no-startup-id /usr/bin/i3wsr

i3 configuration

This program depends on numbered workspaces, since we're constantly changing the workspace name. So your I3 configuration need to reflect this:

bindsym $mod+1 workspace number 1

If you're like me and don't necessarily bind your workspaces to only numbers, or you want to keep a part of the name constant you can do like this:

bindsym $mod+q workspace number 1:[Q]

This way the workspace would look something like this when it gets changed:

1:[Q] Emacs|Firefox

You can take this a bit further by using a bar that trims the workspace number and be left with only

[Q] Emacs|Firefox

Configuration / options

Configuration for i3wsr can be done using cmd flags, or a config file. A config file allows for more nuanced settings, and is required to configure icons and aliases. To use a config file pass to the --config option on invocation:

i3wsr --config ~/my_config.toml

Example config can be found in assets/example_config.toml.

Icons

You can configure icons for the respective classes, a very basic preset for font-awesome is configured, to enable it use the option --icons awesome (requires font-awesome to be installed).

A more in depth icon configuration can be setup by using a configuration file. In there you can define icons for whatever class you'd like.

[icons]
Firefox = "🌍"

# Use quote when matching anything other than [a-zA-Z]
"Org.gnome.Nautilus" = "📘"

A font that provides icons is of course recommended, like font-awesome. Make sure your bar has that font configured.

Aliases

Sometimes class names for windows can be overly verbose, so its possible to match a class name with an alias:

[aliases]
Google-chrome-unstable = "Chrome-dev"

# Use quote when matching anything other than [a-zA-Z]
"Org.gnome.Nautilus" = "Nautilus"

Now i3wsr will display the alias instead of the full class name.

Separator

Normally i3wsr uses the pipe character | between class names in a workspace, but a custom separator can be configured in the config file:

[general]
separator = "  "

Default icon

To use a default icon when no other is defined use:

[general]
default_icon = "💀"

No names

If you have icons and don't want the names to be displayed, you can use the --no-names flag, or enable it in your config file like so:

[options]
no_names = true

Remove duplicates

If you want duplicates removed from workspaces use either the flag --remove-duplicates, or configure it in the options section of the config file:

[options]
remove_duplicates = true

Use instance

Use WM_INSTANCE instead of WM_CLASS when assigning workspace names, instance is usually more specific. i3wsr will try to match icon with instance, and if that fail, will fall back to class.

To enable this, either pass the flag --use-instance, or add it in your config file under options.

[options]
use_instance = true

A use case for this option could be launching chromium --app="https://web.whatsapp.com", and then assign a different icon to whatsapp in your config file:

[icons]
"web.whatsapp.com" = "💧"

Aliases will also match on instance:

[aliases]
"web.whatsapp.com" = "WhatsApp"

Sway

Check Pedro Scaff's port swaywsr.

Contributors

• Daniel Berg (roosta)
• Cauê Baasch de Souza (cauebs)
• Pedro Scaff (pedroscaff)
• Ben Brooks (bbrks)
• luukvbaal

Test environment

To run the tests Xvfb needs to be installed and run:

Xvfb :99.0

This sets up a headless x server running on DISPLAY :99.0, then some apps needs to be run in this new server:

env DISPLAY=:99.0 gpick
env DISPLAY=:99.0 i3 -c /etc/i3/config

refer to .travis.yml for a CI example

Attribution

This program would not be possible without i3ipc-rs, a rust library for controlling i3-wm through its IPC interface and rust-xcb, a set of rust bindings and wrappers for XCB.