i3

https://i3wm.org/docs
Admin
i3 is an improved tiling window manager for X11 designed for advanced users and developers,...
Tokens:79,983
Snippets:1,036
Trust Score:9.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Configure Autostart Applications

Source: https://i3wm.org/docs/user-contributed/lzap-config.html

Executes commands or scripts when i3 starts. Includes examples for audio sample playback, launching a scratchpad terminal, and running a custom autostart script.

```i3config
# before autostart
exec --no-startup-id pactl upload-sample ~/.i3/that_was_easy.wav that_was_easy
exec urxvt -name scratchpad -e bash
exec ~/.i3/autostart

```

--------------------------------

### Universal Module Options Example

Source: https://i3wm.org/docs/i3status.html

Example configuration demonstrating universal module options like alignment, minimum width, and separator settings for a disk module.

```i3config
disk "/" {
    format = "%avail"
    align = "left"
    min_width = 100
    separator = false
    separator_block_width = 1
}
```

--------------------------------

### Full i3bar Block Configuration Example

Source: https://i3wm.org/docs/i3bar-protocol.html

An example showcasing all possible keys for a block, including text content, colors, borders, alignment, identification, and separator settings.

```json
{
 "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
 "short_text": "10.0.0.1",
 "color": "#00ff00",
 "background": "#1c1c1c",
 "border": "#ee0000",
 "border_top": 1,
 "border_right": 0,
 "border_bottom": 3,
 "border_left": 1,
 "min_width": 300,
 "align": "right",
 "urgent": false,
 "name": "ethernet",
 "instance": "eth0",
 "separator": true,
 "separator_block_width": 9,
 "markup": "none"
}
```

--------------------------------

### i3status Configuration Example

Source: https://i3wm.org/docs/i3status.html

A comprehensive example of an i3status configuration file, demonstrating general settings and various module configurations.

```ini
general {
        output_format = "dzen2"
        colors = true
        interval = 5
}

order += "ipv6"
order += "disk /"
order += "run_watch DHCP"
order += "run_watch VPNC"
order += "path_exists VPN"
order += "wireless wlan0"
order += "ethernet eth0"
order += "battery 0"
order += "cpu_temperature 0"
order += "memory"
order += "load"
order += "tztime local"
order += "tztime berlin"

wireless wlan0 {
        format_up = "W: (%quality at %essid, %bitrate) %ip"
        format_down = "W: down"
}

ethernet eth0 {
        format_up = "E: %ip (%speed)"
        format_down = "E: down"
}

battery 0 {
        format = "%status %percentage %remaining %emptytime"
        format_down = "No battery"
        status_chr = "⚡ CHR"
        status_bat = "🔋 BAT"
        status_unk = "? UNK"
        status_full = "☻ FULL"
        status_idle = "☻ IDLE"
        path = "/sys/class/power_supply/BAT%d/uevent"
        low_threshold = 10
}

run_watch DHCP {
        pidfile = "/var/run/dhclient*.pid"
}

run_watch VPNC {
        # file containing the PID of a vpnc process
        pidfile = "/var/run/vpnc/pid"
}

path_exists VPN {
        # path exists when a VPN tunnel launched by nmcli/nm-applet is active
        path = "/proc/sys/net/ipv4/conf/tun0"
}

tztime local {
        format = "%Y-%m-%d %H:%M:%S"
        hide_if_equals_localtime = true
}

tztime berlin {
        format = "%Y-%m-%d %H:%M:%S %Z"
        timezone = "Europe/Berlin"
}

load {
        format = "%5min"
}

cpu_temperature 0 {
        format = "T: %degrees °C"
        path = "/sys/devices/platform/coretemp.0/temp1_input"
}

memory {
        format = "%used"
        threshold_degraded = "10%"
        format_degraded = "MEMORY: %free"
}

disk "/" {
        format = "%free"
}

read_file uptime {
        path = "/proc/uptime"
}
```

--------------------------------

### i3 .xsession File Example

Source: https://i3wm.org/docs/i3.html

This .xsession file is used to configure system locales and start the i3 window manager upon login. It disables screen blanking and audible bells.

```bash
# Disable DPMS turning off the screen
xset -dpms
xset s off

# Disable bell
xset -b

```

--------------------------------

### Start i3 with Force Xinerama

Source: https://i3wm.org/docs/manpage.html

Use this flag when starting i3 if you are using the nVidia binary graphics driver to ensure proper multi-monitor setup.

```bash
`exec i3 --force-xinerama -V >>~/.i3/i3log 2>&1`
```

--------------------------------

### Build and Install i3wm Tree Branch

Source: https://i3wm.org/docs/tree-migrating.html

After cloning, navigate to the directory, build the project using 'make', and then install the 'i3-tree' executable. Ensure you have the same dependencies as the latest stable i3 version.

```bash
cd i3
make
sudo cp i3 /usr/bin/i3-tree
```

--------------------------------

### i3-msg Examples

Source: https://i3wm.org/docs/i3-msg.html

Practical examples demonstrating how to use i3-msg for common tasks.

```APIDOC
## EXAMPLES
```
`# Use 1-px border for current client
i3-msg "border 1pixel"

# You can leave out the quotes
i3-msg border normal

# Dump the layout tree
i3-msg -t get_tree

# Monitor window changes
i3-msg -t subscribe -m '[ "window" ]'
```
```

--------------------------------

### Start Applications Automatically on i3 Startup

Source: https://i3wm.org/docs/userguide.html

Use 'exec' to run commands when i3 starts, and 'exec_always' to run them on startup and restarts. Commands are executed in order. Use '--no-startup-id' for applications that do not support startup notifications.

```i3config
exec chromium
exec_always ~/my_script.sh

# Execute the terminal emulator urxvt, which is not yet startup-notification aware.
exec --no-startup-id urxvt
```

--------------------------------

### Example: Open file manager with disk module click

Source: https://i3wm.org/docs/user-contributed/py3status.html

Configure the 'disk' module to open the 'thunar' file manager when clicked.

```config
disk {
    on_click 1 = "exec thunar"
}
```

--------------------------------

### Install i3 and Recommended Apps

Source: https://i3wm.org/docs/user-contributed/lzap-config.html

Installs the i3 window manager along with i3lock, dmenu, and dunst using yum. Ensure dunst is available or handled separately if not in default repositories.

```bash
# yum -y install i3 i3lock dmenu dunst
```

--------------------------------

### Copy luastatus example widgets

Source: https://i3wm.org/docs/user-contributed/luastatus-i3bar.html

Copy example widget configuration files from the luastatus repository to a local configuration directory. These files define the content and behavior of status bar modules.

```bash
# we assume we are in the luastatus repo directory
mkdir ~/.config/luastatus  # if this directory has not been already created
cp examples/i3/time-battery-combined.lua examples/i3/alsa.lua ~/.config/luastatus

```

--------------------------------

### Example: Open URL with weather module click

Source: https://i3wm.org/docs/user-contributed/py3status.html

Set the 'weather_yahoo' module to open a specific weather website in Firefox when clicked.

```config
weather_yahoo paris {
    on_click 1 = "exec firefox http://www.my-favorite-weather-site.com/
}

```

--------------------------------

### Generate documentation with BuildFactory

Source: https://i3wm.org/docs/buildbot.html

Initializes a BuildFactory for generating project documentation. This snippet shows the setup and the addition of the git source step.

```python
`f = factories['docs'] = BuildFactory()
f.addStep(s_git)
`
```

--------------------------------

### Example Workspace Data Structure (JSON)

Source: https://i3wm.org/docs/i3bar-workspace-protocol.html

This is an example of the JSON output from `i3-msg -t get_workspaces`, representing the state of workspaces. i3bar uses this format to create workspace buttons.

```json
[
  {
    "id": 94131549984064,
    "num": 1,
    "name": "1",
    "visible": false,
    "focused": false,
    "output": "HDMI-A-0",
    "urgent": false
  },
  {
    "id": 94131550477584,
    "num": 2,
    "name": "2",
    "visible": true,
    "focused": true,
    "output": "HDMI-A-0",
    "urgent": false
  },
  {
    "id": 94131550452704,
    "num": 3,
    "name": "3:some workspace",
    "visible": false,
    "focused": false,
    "output": "HDMI-A-0",
    "urgent": false
  }
]
```

--------------------------------

### Assignment with arrow syntax

Source: https://i3wm.org/docs/userguide.html

This example demonstrates the use of an arrow (→) for assignment, which is purely cosmetic but can improve readability. It achieves the same result as the previous example.

```i3 config
# Same thing, but with a beautiful arrow :)
assign [class="^URxvt$"] → 2
```

--------------------------------

### Example: Control wicd-gtk with ethernet module clicks

Source: https://i3wm.org/docs/user-contributed/py3status.html

Use the 'ethernet' module to launch 'wicd-gtk' on a left-click and kill it on a right-click.

```config
ethernet eth0 {
    on_click 1 = "exec wicd-gtk"
    on_click 3 = "exec killall wicd-gtk"
}
```

--------------------------------

### i3 Testcase Workspace Setup

Source: https://i3wm.org/docs/testsuite.html

Initializes a fresh workspace and sets the window split orientation using i3test functions and IPC commands.

```perl
my $tmp = fresh_workspace;

cmd 'split h';
```

--------------------------------

### Example: Add IMAP module to py3status

Source: https://i3wm.org/docs/user-contributed/py3status.html

This example demonstrates adding the 'imap' module to the status line and configuring its connection details.

```config
order += "imap"
imap {
    user = "alex"
    password = "ilovebugs"
    port = "993"
    server = "imap.mybugprovider.com"

    on_click 1 = "exec xterm -e mutt"
}
```

--------------------------------

### Sample ~/.xsession for i3 Configuration

Source: https://i3wm.org/docs/manpage.html

Configures system settings like locales, disables screen blanking and bell, enables key combinations for killing X, sets environment variables, and starts the i3 window manager.

```bash
# Disable DPMS turning off the screen
xset dpms force on
xset s off

# Disable bell
xset -b

# Enable zapping (C-A-<Bksp> kills X)
setxkbmap -option terminate:ctrl_alt_bksp

# Enforce correct locales from the beginning
unset LC_COLLATE
export LC_CTYPE=de_DE.UTF-8
export LC_TIME=de_DE.UTF-8
export LC_NUMERIC=de_DE.UTF-8
export LC_MONETARY=de_DE.UTF-8
export LC_MESSAGES=C
export LC_PAPER=de_DE.UTF-8
export LC_NAME=de_DE.UTF-8
export LC_ADDRESS=de_DE.UTF-8
export LC_TELEPHONE=de_DE.UTF-8
export LC_MEASUREMENT=de_DE.UTF-8
export LC_IDENTIFICATION=de_DE.UTF-8

# Use XToolkit in java applications
export AWT_TOOLKIT=XToolkit

# Set background color
xsetroot -solid "#333333"

# Enable core dumps in case something goes wrong
ulimit -c unlimited

# Start i3 and log to ~/.i3/logfile
echo "Starting at $(date)" >> ~/.i3/logfile
exec /usr/bin/i3 -V -d all >> ~/.i3/logfile
```

--------------------------------

### Start i3 Window Manager with Logging

Source: https://i3wm.org/docs/i3.html

Initializes the i3 window manager, directing verbose debug output and startup information to a log file. Ensure the log directory exists before execution.

```bash
mkdir -p ~/.local/share/i3
echo "Starting at $(date)" >> ~/.local/share/i3/log
exec /usr/bin/i3 -V -d all >> ~/.local/share/i3/log
```

--------------------------------

### Example: Reload and restart i3 on time module clicks

Source: https://i3wm.org/docs/user-contributed/py3status.html

Configure the 'time' module to reload i3 on a left-click and restart i3 on a middle-click.

```config
time {
    on_click 1 = "reload"
    on_click 2 = "restart"
}
```

--------------------------------

### Start Parcellite Clipboard Manager

Source: https://i3wm.org/docs/user-contributed/lzap-config.html

Starts the Parcellite clipboard manager, ensuring it runs in English.

```shell
## Clipboard manager
LC_ALL=C parcellite &
```

--------------------------------

### Get current screen configuration with xrandr

Source: https://i3wm.org/docs/userguide.html

Run 'xrandr' to get an overview of your current screen configuration, including connected and disconnected displays, and their resolutions.

```bash
$ xrandr
Screen 0: minimum 320 x 200, current 1280 x 800, maximum 8192 x 8192
VGA1 disconnected (normal left inverted right x axis y axis)
LVDS1 connected 1280x800+0+0 (normal left inverted right x axis y axis) 261mm x 163mm
   1280x800       60.0*+   50.0
   1024x768       85.0     75.0     70.1     60.0
   832x624        74.6
   800x600        85.1     72.2     75.0     60.3     56.2
   640x480        85.0     72.8     75.0     59.9
   720x400        85.0
   640x400        85.1
   640x350        85.1
```

--------------------------------

### Configure Audio and Brightness Keys

Source: https://i3wm.org/docs/user-contributed/lzap-config.html

These keybindings control PulseAudio volume and backlight brightness. Ensure pactl and xbacklight are installed and configured.

```i3config
# pulse audio volume control
bindsym XF86AudioLowerVolume exec /usr/bin/pactl set-sink-volume 0 -- '-5%'
bindsym XF86AudioRaiseVolume exec /usr/bin/pactl set-sink-volume 0 -- '+5%'
bindsym XF86AudioMute exec /usr/bin/pactl set-sink-volume 0 0
bindsym XF86AudioMute exec /usr/bin/pactl play-sample that_was_easy
bindsym XF86MonBrightnessUp exec /usr/bin/xbacklight -inc 10
bindsym XF86MonBrightnessDown exec /usr/bin/xbacklight -dec 5
```

--------------------------------

### Using Derived Plugin: cpu-usage-linux

Source: https://i3wm.org/docs/user-contributed/luastatus-i3bar.html

Example of how to use the `cpu-usage-linux` derived plugin to display CPU usage in the i3bar. Requires the plugin to be available.

```lua
widget = luastatus.require_plugin('cpu-usage-linux').widget{
    cb = function(usage)
        if usage ~= nil then
            return {full_text = string.format('[%5.1f%%]', usage * 100)}
        end
    end,
}

```

--------------------------------

### i3wm Multiple Swallow Criteria Example

Source: https://i3wm.org/docs/layout-saving.html

This JSON example illustrates how to use multiple 'swallows' criteria within a single layout definition to match different window classes.

```json
"swallows": [
    {"class": "^Emacs$"},
    {"class": "^Gvim$"}
]
```

--------------------------------

### i3bar Status Line Array Example

Source: https://i3wm.org/docs/i3bar-protocol.html

An example demonstrating the structure of a status line array in the i3bar protocol, showing multiple blocks with text and color information. Note that this is pretty-printed for readability; actual output is typically on a single line.

```json
[

 [
  {
   "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
   "color": "#00ff00"
  },
  {
   "full_text": "2012-01-05 20:00:01"
  }
 ],

 [
  {
   "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
   "color": "#00ff00"
  },
  {
   "full_text": "2012-01-05 20:00:02"
  }
 ],
 …
```

--------------------------------

### Bind Key to Start Terminal in i3

Source: https://i3wm.org/docs/user-contributed/lzap-config.html

Assigns a keybinding to launch the default terminal. Uses i3-sensible-terminal to find the best available terminal emulator.

```i3config
bindsym $mod+Return exec i3-sensible-terminal
```

--------------------------------

### Example: Grouping multiple time modules

Source: https://i3wm.org/docs/user-contributed/py3status.html

Use the 'group' module to combine multiple 'tztime' modules, allowing them to be cycled through.

```config
order += "group tz"

```

--------------------------------

### Full i3bar Protocol Header with Options

Source: https://i3wm.org/docs/i3bar-protocol.html

An example of the i3bar protocol header including optional parameters like stop/continue signals and click event handling.

```json
{ "version": 1, "stop_signal": 10, "cont_signal": 12, "click_events": true }
```

--------------------------------

### Custom Block Data Example

Source: https://i3wm.org/docs/i3bar-protocol.html

Demonstrates how to include custom data in a block by prefixing keys with an underscore. i3bar ignores these keys.

```json
{
 "full_text": "E: 10.0.0.1 (1000 Mbit/s)",
 "_ethernet_vendor": "Intel"
}
```

--------------------------------

### Run luastatus-i3-wrapper

Source: https://i3wm.org/docs/user-contributed/luastatus-i3bar.html

Execute the luastatus wrapper for i3bar. This command starts the status bar generator. It requires widgets to be specified for meaningful output.

```bash
$ luastatus-i3-wrapper
luastatus: warning: no widgets specified (see luastatus(1) for usage info)
{"version":1,"click_events":true,"stop_signal":0,"cont_signal":0}
[

```

--------------------------------

### Chain i3 Commands

Source: https://i3wm.org/docs/userguide.html

Commands can be chained using a semicolon. This example binds a key to move a window to workspace 3 and then switch to it.

```i3config
bindsym $mod+x move container to workspace 3; workspace 3
```

--------------------------------

### Enable Core Dumps

Source: https://i3wm.org/docs/debugging-release-version.html

Set the user limit for core dump files to unlimited in your ~/.xsession before starting i3. This allows the system to generate core dumps when i3 crashes.

```bash
ulimit -c unlimited
```

--------------------------------

### Define and Enter a Custom Mode

Source: https://i3wm.org/docs/userguide.html

Use the `mode` directive to create custom keybindings for specific contexts. This example defines a mode for launching applications and binds keys to execute them.

```i3config
# Press $mod+o followed by either f, t, Escape or Return to launch firefox,
# thunderbird or return to the default mode, respectively.
set $mode_launcher Launch: [f]irefox [t]hunderbird
bindsym $mod+o mode "$mode_launcher"

mode "$mode_launcher" {
    bindsym f exec firefox
    bindsym t exec thunderbird

    bindsym Escape mode "default"
    bindsym Return mode "default"
}
```

--------------------------------

### Clone Keyring Repository and Include Changes

Source: https://i3wm.org/docs/buildbot.html

Clones the i3-autobuild-keyring repository and includes prebuilt .changes files. This is part of the initial setup for building packages.

```python
cmd(f,
    name = 'clone keyring repo',
    command = 'git clone git://code.i3wm.org/i3-autobuild-keyring',
)
reprepro_include(f, 'i3-autobuild-keyring/prebuilt/*.changes')
```

--------------------------------

### Apply i3 Command with Criteria

Source: https://i3wm.org/docs/userguide.html

Use criteria in square brackets before a command to specify which containers it should affect. This example kills all windows with the class 'Firefox'.

```i3config
# if you want to kill all windows which have the class Firefox, use:
bindsym $mod+x [class="Firefox"] kill
```

--------------------------------

### Switch to Specific Workspace in i3

Source: https://i3wm.org/docs/user-contributed/lzap-config.html

Configures keybindings to switch to specific workspaces (1-10). Includes commented-out examples for standard number keys.

```i3config
bindsym $mod+ampersand workspace 1
bindsym $mod+eacute workspace 2
bindsym $mod+quotedbl workspace 3
bindsym $mod+apostrophe workspace 4
bindsym $mod+parenleft workspace 5
bindsym $mod+minus workspace 6
bindsym $mod+egrave workspace 7
bindsym $mod+underscore workspace 8
bindsym $mod+ccedilla workspace 9
bindsym $mod+agrave workspace 10
#bindsym $mod+1 workspace 1
#bindsym $mod+2 workspace 2
#bindsym $mod+3 workspace 3
#bindsym $mod+4 workspace 4
#bindsym $mod+5 workspace 5
#bindsym $mod+6 workspace 6
#bindsym $mod+7 workspace 7
#bindsym $mod+8 workspace 8
#bindsym $mod+9 workspace 9
#bindsym $mod+0 workspace 10
```

--------------------------------

### Window Properties using xprop

Source: https://i3wm.org/docs/layout-saving.html

This command-line example shows how to use 'xprop' to inspect window properties like WM_WINDOW_ROLE, WM_CLASS, and _NET_WM_NAME, which are useful for configuring 'swallows' criteria.

```bash
$ xprop
WM_WINDOW_ROLE(STRING) = "gimp-toolbox-color-dialog"
WM_CLASS(STRING) = "gimp-2.8", "Gimp-2.8"
_NET_WM_NAME(UTF8_STRING) = "Change Foreground Color"
```

--------------------------------

### Bind Key to Launch Application Menu in i3

Source: https://i3wm.org/docs/user-contributed/lzap-config.html

Sets a keybinding to open dmenu, a dynamic program launcher. This is the primary way to start applications in i3.

```i3config
bindsym $mod+d exec dmenu_run
```

--------------------------------

### Bind Window Movement Keys in i3wm

Source: https://i3wm.org/docs/tree-migrating.html

Example keybindings for moving windows. Mod1+Shift combined with arrow keys are used to move windows before or after other windows horizontally and vertically.

```i3config
bindsym Mod1+Shift+Left move before h
bindsym Mod1+Shift+Right move after h
bindsym Mod1+Shift+Down move before v
bindsym Mod1+Shift+Up move after v
```

--------------------------------

### i3wm 'swallows' Configuration Example

Source: https://i3wm.org/docs/layout-saving.html

This JSON snippet demonstrates how to configure the 'swallows' property in an i3wm layout file to match specific window classes and instances.

```json
"swallows": [
    {
        "class": "^Emacs$",
        "instance": "^notmuch$"
    }
]
```

--------------------------------

### Minimum Width with Text Example

Source: https://i3wm.org/docs/i3bar-protocol.html

Shows how to set the minimum width of a block using a text string. The width of this string determines the minimum block width, useful for consistent alignment.

```json
{
 "full_text": "CPU 4%",
 "min_width": "CPU 100%",
 "align": "left"
}
```

--------------------------------

### Apply i3 Window Rule with Padding

Source: https://i3wm.org/docs/userguide.html

Use the `for_window` directive to apply rules to specific windows. This example enables window icons and adds horizontal padding for all windows.

```i3config
# enable window icons for all windows with extra horizontal padding of 1px
for_window [all] title_window_icon padding 1px
```

--------------------------------

### Start Dunst Notification Daemon

Source: https://i3wm.org/docs/user-contributed/lzap-config.html

Starts the Dunst notification daemon for displaying system notifications.

```shell
## OSD
dunst &
```

--------------------------------

### Apply i3 Command with Multiple Criteria

Source: https://i3wm.org/docs/userguide.html

Combine multiple criteria within square brackets to target specific windows. This example kills a Firefox 'About' dialog based on class and window role.

```i3config
# kill only the About dialog from Firefox
bindsym $mod+x [class="Firefox" window_role="About"] kill
```

--------------------------------

### Prepare pbuilder Environments

Source: https://i3wm.org/docs/buildbot.html

Sets up pbuilder environments by creating symbolic links to 'pbuilder-dist' and then creating the 'sid-amd64' and 'sid-i386' environments.

```bash
sudo ln -s pbuilder-dist /usr/bin/pbuilder-sid-amd64
sudo ln -s pbuilder-dist /usr/bin/pbuilder-sid-i386
pbuilder-sid-amd64 create
pbuilder-sid-i386 create
```

--------------------------------

### i3 Configuration File Example

Source: https://i3wm.org/docs/i3.html

This is a sample i3 configuration file. It defines fonts, modifier keys, and various keybindings for window management tasks like opening terminals, launching applications, changing focus, moving windows, and managing layouts.

```i3config
# i3 config file (v4)

# Font for window titles. Will also be used by the bar unless a different font
# is used in the bar {} block below.
# This font is widely installed, provides lots of unicode glyphs, right-to-left
# text rendering and scalability on retina/hidpi displays (thanks to pango).
font pango:DejaVu Sans Mono 8
# Before i3 v4.8, we used to recommend this one as the default:
# font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1
# The font above is very space-efficient, that is, it looks good, sharp and
# clear in small sizes. However, its unicode glyph coverage is limited, the old
# X core fonts rendering does not support right-to-left and this being a bitmap
# font, it doesn’t scale on retina/hidpi displays.

# use Mouse+Mod1 to drag floating windows to their wanted position
floating_modifier Mod1

# start a terminal
bindsym Mod1+Return exec /usr/bin/urxvt

# kill focused window
bindsym Mod1+Shift+q kill

# start dmenu (a program launcher)
bindsym Mod1+d exec /usr/bin/dmenu_run

# change focus
bindsym Mod1+j focus left
bindsym Mod1+k focus down
bindsym Mod1+l focus up
bindsym Mod1+semicolon focus right

# alternatively, you can use the cursor keys:
bindsym Mod1+Left focus left
bindsym Mod1+Down focus down
bindsym Mod1+Up focus up
bindsym Mod1+Right focus right

# move focused window
bindsym Mod1+Shift+j move left
bindsym Mod1+Shift+k move down
bindsym Mod1+Shift+l move up
bindsym Mod1+Shift+semicolon move right

# alternatively, you can use the cursor keys:
bindsym Mod1+Shift+Left move left
bindsym Mod1+Shift+Down move down
bindsym Mod1+Shift+Up move up
bindsym Mod1+Shift+Right move right

# split in horizontal orientation
bindsym Mod1+h split h

# split in vertical orientation
bindsym Mod1+v split v

# enter fullscreen mode for the focused container
bindsym Mod1+f fullscreen toggle

# change container layout (stacked, tabbed, default)
bindsym Mod1+s layout stacking
bindsym Mod1+w layout tabbed
bindsym Mod1+e layout default

# toggle tiling / floating
bindsym Mod1+Shift+space floating toggle

# change focus between tiling / floating windows
bindsym Mod1+space focus mode_toggle

# focus the parent container
bindsym Mod1+a focus parent

# focus the child container
#bindsym Mod1+d focus child

# switch to workspace
bindsym Mod1+1 workspace 1
bindsym Mod1+2 workspace 2
# ..

# move focused container to workspace
bindsym Mod1+Shift+1 move workspace 1
bindsym Mod1+Shift+2 move workspace 2
# ...

# reload the configuration file
bindsym Mod1+Shift+c reload
# restart i3 inplace (preserves your layout/session, can be used to upgrade i3)
bindsym Mod1+Shift+r restart
# exit i3 (logs you out of your X session)
bindsym Mod1+Shift+e exit

# display workspace buttons plus a statusline generated by i3status
bar {
    status_command i3status
}
```

--------------------------------

### Enable Docs and Manpages Build

Source: https://i3wm.org/docs/hacking-howto.html

Meson options to enable the building of documentation and manpages. Additional dependencies may be required.

```bash
meson -Ddocs=true -Dmans=true
```

--------------------------------

### Install Testsuite Dependencies with cpanminus

Source: https://i3wm.org/docs/testsuite.html

Installs system-level dependencies and Perl modules for the i3 testsuite using cpanminus. Ensure local::lib and App::cpanminus are activated before running.

```bash
# Install testsuite system-level dependencies. Xvfb is optional but recommended.
$ sudo apt-get install xcb-proto cpanminus xvfb xserver-xephyr
# Install dependencies in ~/perl5 local library
$ cpanm --local-lib=~/perl5 local::lib App::cpanminus Module::Install
# Activate the local library
$ eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)
$ cd ~/i3/testcases/
$ cpanm .
$ cd ~/i3/AnyEvent-I3
$ cpanm .
```

--------------------------------

### Build Documentation with Make

Source: https://i3wm.org/docs/buildbot.html

Executes the 'make' command to build documentation, specifying the ASCIIDOC command with custom options.

```python
cmd(f, name = 'build docs', command = [ 'make', '-C', 'docs', "ASCIIDOC=asciidoc -a linkcss -a stylesdir=http://i3wm.org/css -a scriptsdir=http://i3wm.org/js --backend=xhtml11 -f docs/asciidoc-git.conf" ])
```

--------------------------------

### Run i3-wsbar with dzen2

Source: https://i3wm.org/docs/wsbar.html

This is the most basic usage of i3-wsbar, launching dzen2 in dock mode. The %x placeholder is replaced by i3 with the correct X position for the output.

```bash
`i3-wsbar -c "dzen2 -x %x -dock"`
```

--------------------------------

### Build i3 using Meson

Source: https://i3wm.org/docs/hacking-howto.html

Standard commands to set up and compile i3 using the Meson build system. Ensure you are in the i3 source directory.

```bash
mkdir -p build
meson setup build
meson compile -C build
```

--------------------------------

### Disable Workspace Buttons

Source: https://i3wm.org/docs/userguide.html

Hides the workspace buttons from the i3bar. Useful for statusline-only bars or minimalist setups.

```i3config
bar {
    workspace_buttons no
}
```

--------------------------------

### Display Loaded i3 Configuration Files

Source: https://i3wm.org/docs/userguide.html

Run `i3 --moreversion` to list all configuration files that i3 has loaded, including the main config and any included files, along with their modification times.

```bash
% i3 --moreversion
Binary i3 version:  4.19.2-87-gfcae64f7+ © 2009 Michael Stapelberg and contributors
Running i3 version: 4.19.2-87-gfcae64f7+ (pid 963940)
Loaded i3 config:
  /tmp/i3.cfg (main) (last modified: 2021-05-13T16:42:31 CEST, 463 seconds ago)
  /tmp/included.cfg (included) (last modified: 2021-05-13T16:42:43 CEST, 451 seconds ago)
  /tmp/another.cfg (included) (last modified: 2021-05-13T16:42:46 CEST, 448 seconds ago)
```

--------------------------------

### Tick Event - With Payload

Source: https://i3wm.org/docs/ipc.html

This example shows the structure of a tick event received upon a SEND_TICK message with a payload.

```json
{
 "first": false,
 "payload": "arbitrary string"
}
```

--------------------------------

### Get PulseAudio Sink Name

Source: https://i3wm.org/docs/i3status.html

Command to list PulseAudio sinks and identify the name of the desired sink for configuration.

```bash
$ pacmd list-sinks | grep name:
           name: <alsa_output.pci-0000_00_14.2.analog-stereo>
```

--------------------------------

### Tick Event - Upon Subscription

Source: https://i3wm.org/docs/ipc.html

This example shows the structure of a tick event received upon subscribing to tick events.

```json
{
 "first": true,
 "payload": ""
}
```

--------------------------------

### Create Documentation Directory

Source: https://i3wm.org/docs/buildbot.html

Adds a build step to create a directory named 'build/COPY-DOCS' on the slave.

```python
f.addStep(slave.MakeDirectory(dir='build/COPY-DOCS'))
```

--------------------------------

### Output Event Payload Example

Source: https://i3wm.org/docs/ipc.html

The output event payload is simpler, currently containing only a 'change' property which is typically 'unspecified'.

```json
{ "change": "unspecified" }
```

--------------------------------

### Build Documentation

Source: https://i3wm.org/docs/buildbot.html

Builds the project documentation using make and a custom asciidoc configuration. It also copies documentation and manpages to a build directory for upload.

```python
f.addStep(shell.SetProperty(command = 'git describe --tags', property = 'gitversion'))
```

```python
cmd(f, name = 'build docs', command = [ 'make', '-C', 'docs', "ASCIIDOC=asciidoc -a linkcss -a stylesdir=http://i3wm.org/css -a scriptsdir=http://i3wm.org/js --backend=xhtml11 -f docs/asciidoc-git.conf" ])
```

```python
cmd(f, name = 'build manpages', command = "for file in $(sed 's/\.1$/.man/g' debian/i3-wm.manpages); do asciidoc -a linkcss -a stylesdir=http://i3wm.org/css -a scriptsdir=http://i3wm.org/js --backend=xhtml11 -f docs/asciidoc-git.conf \"$file\"; done")
```

```python
f.addStep(slave.MakeDirectory(dir='build/COPY-DOCS'))
```

```python
cmd(f, name = 'copy docs', command = "cp $(tr '\n' ' ' < debian/i3-wm.docs) COPY-DOCS")
```

```python
cmd(f, name = 'copy manpages', command = "cp $(sed 's/\.1$/.html/g' debian/i3-wm.manpages | tr '\n' ' ') COPY-DOCS")
```

```python
f.addStep(transfer.DirectoryUpload(
    slavesrc = 'COPY-DOCS',
    masterdest = 'htdocs/docs-git',
    compress = 'bz2',
    name = 'upload docs'))
```

```python
f.addStep(DocsToIRC())
```

--------------------------------

### Copy Debian Packaging Files

Source: https://i3wm.org/docs/buildbot.html

Copies the 'debian' directory into the 'build/DIST' directory. This is part of the setup for building Ubuntu packages.

```python
cmd(f, name='copy packaging', command = "cp -r debian DIST/")
```

--------------------------------

### Autostart Applications with i3

Source: https://i3wm.org/docs/user-contributed/lzap-config.html

Executes applications on i3 startup. This can include graphical applications, terminals, or background services.

```shell
exec google-chrome
exec urxvt -name mail -e bash -c "mutt"
exec xchat
exec rednotebook
exec decibel-audio-player
exec lexicon
```

--------------------------------

### Prepare Result Directories for Debian Builds

Source: https://i3wm.org/docs/buildbot.html

Creates result directories for each specified distribution (e.g., 'build/RESULT-sid-amd64').

```python
for dist in distributions:
    f.addStep(slave.MakeDirectory(dir = 'build/RESULT-' + dist))
```

--------------------------------

### Show Marks on Window Decorations

Source: https://i3wm.org/docs/userguide.html

Enables or disables the drawing of marks (from vim_like_marks) on window decorations. Marks starting with an underscore are not drawn.

```i3config
show_marks yes
```

--------------------------------

### Run i3-wsbar with i3status and dzen2

Source: https://i3wm.org/docs/wsbar.html

Integrates i3status output into the workspace bar by piping its output to i3-wsbar, which then formats and displays it using dzen2.

```bash
`i3status | i3-wsbar -c "dzen2 -x %x -dock"`
```

--------------------------------

### Create Debian Sid Repository Configuration

Source: https://i3wm.org/docs/buildbot.html

Sets up the configuration for a Debian 'sid' repository. This includes creating necessary directories and defining repository properties like codename, suite, and architectures.

```python
f.addStep(slave.MakeDirectory(dir='build/REPO-sid/conf'))
```

```python
f.addStep(transfer.StringDownload(
    """Codename: sid
Suite: unstable
Architectures: i386 amd64 source
Components: main
DebIndices: Packages Release . .gz .bz2
DscIndices: Sources Release . .gz .bz2
SignWith: %(gpg_key)s
""" % { "gpg_key": gpg_key },
    slavedest = 'REPO-sid/conf/distributions',
))
```

--------------------------------

### i3status Command-line Options

Source: https://i3wm.org/docs/i3status.html

Provides basic command-line options for i3status, including configuration file path, help, and version information.

```bash
i3status [-c configfile] [-h] [-v] [--run-once]
```

--------------------------------

### Start application on a specific workspace once

Source: https://i3wm.org/docs/userguide.html

This configuration uses `exec --no-startup-id` to launch an application on a specific workspace and then immediately switch back to the original workspace. It's crucial for i3 to correctly match the window to the workspace it was launched on.

```i3 config
# Start iceweasel on workspace 3, then switch back to workspace 1
# (Being a command-line utility, i3-msg does not support startup notifications,
#  hence the exec --no-startup-id.)
# (Starting iceweasel with i3’s exec command is important in order to make i3
#  create a startup notification context, without which the iceweasel window(s)
#  cannot be matched onto the workspace on which the command was started.)
exec --no-startup-id i3-msg 'workspace 3; exec iceweasel; workspace 1'
```

--------------------------------

### Run All i3wm Testcases

Source: https://i3wm.org/docs/testsuite.html

Execute all testcases using `complete-run.pl`. This script manages i3 instances, configurations, and log files, typically running tests under Xephyr or Xvfb.

```bash
$ cd ~/
i3

$ mkdir -p build

$ meson setup build
$ cd build

$ meson compile
# output omitted because it is very long

$ ./complete-run.pl
# output omitted because it is very long
All tests successful.
Files=78, Tests=734, 27 wallclock secs ( 0.38 usr  0.48 sys + 17.65 cusr  3.21 csys = 21.72 CPU)
Result: PASS
```

--------------------------------

### File Contents Module Configuration

Source: https://i3wm.org/docs/i3status.html

Example configuration for the file contents module, specifying the format for displaying file content and error states.

```i3config
read_file UPTIME
    format = "%title: %content"
    format_bad = "%title - %errno: %error"
    path = "/proc/uptime"
    Max_characters = 255
```

--------------------------------

### Run i3wm Testsuite with Ninja

Source: https://i3wm.org/docs/testsuite.html

Execute the i3 testsuite using the `ninja test` command after setting up the build with Meson. This provides a summary of test results.

```bash
$ cd ~/
i3

$ mkdir -p build

$ meson setup build
$ cd build

$ ninja test
[1/102] Generating config.h with a custom command
[1/2] Running all tests.
1/1 complete-run OK              34.39s

Ok:                 1
Expected Fail:      0
Fail:               0
Unexpected Pass:    0
Skipped:            0
Timeout:            0

Full log written to i3/build/meson-logs/testlog.txt

$ less latest/complete-run.log
```

--------------------------------

### GET_BAR_CONFIG / BAR_CONFIG

Source: https://i3wm.org/docs/ipc.html

Retrieves the configuration for a specified bar or all bar configurations if no ID is provided. This is useful for third-party bars to get their configuration from i3.

```APIDOC
## GET_BAR_CONFIG / BAR_CONFIG

### Description
Gets the specified bar configuration or the names of all bar configurations if payload is empty.

### Method
GET

### Endpoint
/bar_config

### Parameters
#### Query Parameters
- **bar_id** (string) - Optional - The ID of the bar whose configuration to retrieve.

### Response
#### Success Response (200)
- **If bar_id is provided**: A JSON map containing the configuration for the specified bar. Properties include: `id` (string), `mode` (string: 'dock' or 'hide'), `position` (string: 'bottom' or 'top'), `status_command` (string), `font` (string), `workspace_buttons` (boolean), `binding_mode_indicator` (boolean), `verbose` (boolean), `colors` (map).
- **If bar_id is not provided**: An array of configured bar IDs (strings).

### Request Example
```json
{
  "bar_id": "bar-bxuqzf"
}
```

### Response Example (All bar IDs)
```json
["bar-bxuqzf"]
```

### Response Example (Specific bar configuration)
```json
{
  "id": "bar-bxuqzf",
  "mode": "dock",
  "position": "bottom",
  "status_command": "i3status",
  "font": "-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1",
  "workspace_buttons": true,
  "binding_mode_indicator": true,
  "verbose": false,
  "colors": {
    "background": "#c0c0c0",
    "statusline": "#00ff00",
    "focused_workspace_text": "#ffffff",
    "focused_workspace_bg": "#000000"
  }
}
```
```

--------------------------------

### Execute Application with Keybinding

Source: https://i3wm.org/docs/userguide.html

Assigns a key combination to execute a specified application. The command is passed to a shell, allowing for shell globbing and PATH searches.

```i3config
# Start the GIMP
bindsym $mod+g exec gimp
```

--------------------------------

### Get All Bar Configuration IDs

Source: https://i3wm.org/docs/ipc.html

Use this command with an empty payload to retrieve a list of all configured bar IDs. The response is an array of strings.

```json
["bar-bxuqzf"]
```

--------------------------------

### Setup Socket and Environment for i3 Socket Activation

Source: https://i3wm.org/docs/testsuite.html

This Perl code prepares a listening UNIX socket, forks a child process, sets environment variables for socket activation (LISTEN_PID, LISTEN_FDS), and configures file descriptors for the child process before executing i3. Ensure the socket path is correctly provided.

```perl
my $socket = IO::Socket::UNIX->new(
    Listen => 1,
    Local => $args{unix_socket_path},
);

my $pid = fork;
if ($pid == 0) {
    $ENV{LISTEN_PID} = $$;
    $ENV{LISTEN_FDS} = 1;

    # Only pass file descriptors 0 (stdin), 1 (stdout),
    # 2 (stderr) and 3 (socket) to the child.
    $^F = 3;

    # If the socket does not use file descriptor 3 by chance
    # already, we close fd 3 and dup2() the socket to 3.
    if (fileno($socket) != 3) {
        POSIX::close(3);
        POSIX::dup2(fileno($socket), 3);
    }

    exec "/usr/bin/i3";
}
```

--------------------------------

### Focus specific window by class and title

Source: https://i3wm.org/docs/userguide.html

Use the 'focus' command with criteria to jump to a specific window. This is particularly useful in multi-monitor setups.

```i3config
bindsym $mod+a [class="urxvt" title="VIM"] focus
```

--------------------------------

### Set Startup Volume

Source: https://i3wm.org/docs/user-contributed/lzap-config.html

Sets the initial audio sink volume to 20% on startup to prevent sudden loud noises.

```shell
## Set startup volume
pactl set-sink-volume 0 '20%' &
```

--------------------------------

### Configure i3status General Settings and Modules

Source: https://i3wm.org/docs/i3status.html

Sets the output format to xmobar, customizes the separator between modules, and defines the order and format for 'load' and 'disk' modules.

```config
general {
    output_format = "xmobar"
    separator = "  "
}

order += "load"
order += "disk /"

load {
    format = "[ load: %1min, %5min, %15min ]"
}
disk "/" {
    format = "%avail" 
}
```

--------------------------------

### Get i3 IPC Socket Path

Source: https://i3wm.org/docs/wsbar.html

Use this command to retrieve the path to the i3 IPC socket, which is necessary for external programs to communicate with i3.

```bash
i3 --get-socketpath
```

--------------------------------

### Configure Debian Sid Repository

Source: https://i3wm.org/docs/buildbot.html

Sets up the configuration for a Debian 'sid' repository, including codename, suite, architectures, indices, and signing key.

```python
f.addStep(slave.MakeDirectory(dir = 'build/REPO-sid/conf'))
f.addStep(transfer.StringDownload(
    """Codename: sid
Suite: unstable
Architectures: i386 amd64 source
Components: main
DebIndices: Packages Release . .gz .bz2
DscIndices: Sources Release . .gz .bz2
SignWith: %(gpg_key)s
""" % { "gpg_key": gpg_key },
    slavedest = 'REPO-sid/conf/distributions',
))
```

--------------------------------

### Configure Window Title Font in i3

Source: https://i3wm.org/docs/user-contributed/lzap-config.html

Sets the font used for window titles. The example uses a fixed-width font suitable for ISO 10646 (Unicode).

```i3config
font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1
```

--------------------------------

### Upload Documentation

Source: https://i3wm.org/docs/buildbot.html

Adds a build step to upload the 'COPY-DOCS' directory to 'htdocs/docs-git' on the master, using bz2 compression.

```python
f.addStep(transfer.DirectoryUpload(
    slavesrc = 'COPY-DOCS',
    masterdest = 'htdocs/docs-git',
    compress = 'bz2',
    name = 'upload docs'))
```

--------------------------------

### Create Ubuntu Package Repository Configuration

Source: https://i3wm.org/docs/buildbot.html

Creates the configuration directory for the Ubuntu repository and downloads the 'distributions' file content. This file defines the repository's properties like codename, suite, and architectures.

```python
f.addStep(slave.MakeDirectory(dir='build/REPO-sid/conf'))
f.addStep(transfer.StringDownload(
    """Codename: precise
Suite: unstable
Architectures: i386 amd64 source
Components: main
DebIndices: Packages Release . .gz .bz2
DscIndices: Sources Release . .gz .bz2
SignWith: %(gpg_key)s
""" % { "gpg_key": gpg_key },
    slavedest = 'REPO-sid/conf/distributions',
))
```
Tokens:
Raw