bspwm is a tiling window manager that represents windows as the leaves of a full binary tree.
It is controlled and configured via bspc.
- -h
-
Print the synopsis and exit.
- -v
-
Print the version and exit.
- -c CONFIG_PATH
-
Use the given configuration file.
- -s PANEL_FIFO
-
Write the internal state to the given FIFO.
- -p PANEL_PREFIX
-
Start every line written to the PANEL_FIFO with the given prefix.
bspwm has only two sources of informations: the X events it receives and the messages it reads on a dedicated socket.
The default configuration file is $XDG_CONFIG_HOME/bspwm/bspwmrc.
Keyboard and pointer bindings are defined with sxhkd.
Example configuration files can be found in the examples directory.
New windows are inserted in the tree as close as possible to the focused window.
There is only two splitting modes: automatic and manual.
The default mode is automatic. The manual mode is entered by sending a preselection message.
Example: insertion of a new node (number 4) into the given tree in automatic mode:
b c
/ \ / \
3 a --> 4 b
^ / \ ^ / \
2 1 3 a
/ \
2 1
+-------------------------+ +-------------------------+
| | | | | |
| | 2 | | | 3 |
| | | | | |
| 3 |------------| --> | 4 |------------|
| ^ | | | ^ | | |
| | 1 | | | 1 | 2 |
| | | | | | |
+-------------------------+ +-------------------------+
Same departure, but the mode is manual, and a window --presel up message was sent beforehand:
b b
/ \ / \
3 a --> c a
^ / \ / \ / \
2 1 4 3 2 1
^
+-------------------------+ +-------------------------+
| | | | | |
| | 2 | | 4 | 2 |
| | | | ^ | |
| 3 |------------| --> |------------|------------|
| ^ | | | | |
| | 1 | | 3 | 1 |
| | | | | |
+-------------------------+ +-------------------------+
Selectors are used to select a target window, desktop, or monitor. A selector can either describe the target relatively or name it globally.
Descriptive (relative) selectors consist of a primary selector and any number of non-conflicting modifiers as follows:
PRIMARY_SELECTOR[.MODIFIER]*
For obvious reasons, neither desktops nor monitors names may be valid descriptive selectors.
Select a window.
WINDOW_SEL := <window_id>
| (DIR|CYCLE_DIR|biggest|last|focused|older|newer)[.floating|.tiled][.like|.unlike][.manual][.urgent][.local]
- DIR
-
Selects the window in the given (spacial) direction relative to the active window.
- CYCLE_DIR
-
Selects the window in the given (cyclic) direction.
- biggest
-
Selects the biggest window on the current desktop.
- last
-
Selects the previously focused window.
- focused
-
Selects the currently focused window.
- older
-
Selects the window older than the focused window in the history.
- newer
-
Selects the window newer than the focused window in the history.
- floating
-
Only consider floating windows.
- tiled
-
Only consider tiled windows.
- like
-
Only consider windows that have the same class as the current window.
- unlike
-
Only consider windows that have a different class than the current window.
- manual
-
Only consider windows in manual splitting mode (see --presel).
- local
-
Only consider windows of the current desktop.
- urgent
-
Only consider urgent windows.
Select a desktop.
DESKTOP_SEL := <desktop_name>
| ^<n>
| (CYCLE_DIR|last|focused|older|newer)[.occupied|.free][.urgent][.local]
- <desktop_name>
-
Selects the desktop with the given name.
- ^<n>
-
Selects the nth desktop.
- CYCLE_DIR
-
Selects the desktop in the given direction relative to the active desktop.
- last
-
Selects the previously focused desktop.
- focused
-
Selects the currently focused desktop.
- older
-
Selects the desktop older than the focused desktop in the history.
- newer
-
Selects the desktop newer than the focused desktop in the history.
Select a monitor.
MONITOR_SEL := <monitor_name>
| ^<n>
| (DIR|CYCLE_DIR|last|primary|focused|older|newer)[.occupied|.free]
- <monitor_name>
-
Selects the monitor with the given name.
- ^<n>
-
Selects the nth monitor.
- DIR
-
Selects the monitor in the given (spacial) direction relative to the active monitor.
- CYCLE_DIR
-
Selects the monitor in the given (cyclic) direction relative to the active monitor.
- primary
-
Selects the primary monitor.
- last
-
Selects the previously focused monitor.
- focused
-
Selects the currently focused monitor.
- older
-
Selects the monitor older than the focused monitor in the history.
- newer
-
Selects the monitor newer than the focused monitor in the history.
- -f, --focus [WINDOW_SEL]
-
Focus the selected or given window.
- -d, --to-desktop DESKTOP_SEL
-
Send the selected window to the given desktop.
- -m, --to-monitor MONITOR_SEL
-
Send the selected window to the given monitor.
- -w, --to-window WINDOW_SEL
-
Transplant the selected window to the given window.
- -s, --swap WINDOW_SEL
-
Swap the selected window with the given window.
- -p, --presel DIR|cancel
-
Preselect the splitting area of the selected window (or cancel the preselection).
- -r, --ratio RATIO
-
Set the splitting ratio of the selected window (0 < RATIO < 1).
- -e, --edge DIR RATIO|pull|push
-
Set the splitting ratio (or pull, or push) the edge located in the given direction in relation to the selected window.
- -R, --rotate DIR 90|270|180
-
Rotate the tree holding the edge located in the given direction in relation to the selected window.
- -t, --toggle floating|fullscreen|locked|sticky|visible[=on|off]
-
Set or toggle the given state for the selected window.
- -c, --close
-
Close the selected window.
- -k, --kill
-
Kill the selected window.
- -f, --focus [DESKTOP_SEL]
-
Focus the selected or given desktop.
- -m, --to-monitor MONITOR_SEL
-
Send the selected desktop to the given monitor.
- -l, --layout CYCLE_DIR|monocle|tiled
-
Set or cycle the layout of the selected desktop.
- -n, --rename <new_name>
-
Rename the selected desktop.
- -s, --swap DESKTOP_SEL
-
Swap the selected desktop with the given desktop.
- -r, --remove
-
Remove the selected desktop.
- -c, --cancel-presel
-
Cancel the preselection of all the windows of the selected desktop.
- -F, --flip horizontal|vertical
-
Flip the tree of the selected desktop.
- -R, --rotate 90|270|180
-
Rotate the tree of the selected desktop.
- -B, --balance
-
Adjust the split ratios of the tree of the selected desktop so that all windows occupy the same area.
- -C, --circulate forward|backward
-
Circulate the leaves of the tree of the selected desktop.
- -f, --focus [MONITOR_SEL]
-
Focus the selected or given monitor.
- -a, --add-desktops <name>…
-
Create desktops with the given names in the selected monitor.
- -r, --remove-desktops <name>…
-
Remove desktops with the given names.
- -n, --rename <new_name>
-
Rename the selected monitor.
- -d, --reset-desktops <name>…
-
Rename, add or remove desktops depending on whether the number of given names is equal, superior or inferior to the number of existing desktops.
- -s, --swap MONITOR_SEL
-
Swap the selected monitor with the given monitor.
- -l, --list
-
List the tags.
- -a, --add <name>…
-
Create tags with the given names.
- -r, --remove <name>|^<n>…
-
Remove tags with the given names or indexes.
- -e, --enumerate-tags <name>…
-
Rename, add or remove tags depending on whether the number of given names is equal, superior or inferior to the number of existing tags.
- -d, --desktop DESKTOP_SEL
-
Select the given desktop as target for the -s and -t options.
- -w, --window WINDOW_SEL
-
Select the given window as target for the -s and -t options.
- -s, --set-tags (<name>|^<n>…)|all
-
Set the tags of the selected object.
- -t, --toggle-tags (<name>|^<n>)[=on|off]…
-
Toggle the tags of the selected object.
- -W, --windows
-
List matching windows.
- -D, --desktops
-
List matching desktops.
- -M, --monitors
-
List matching monitors.
- -T, --tree
-
Print tree rooted at query.
- -H, --history
-
Print the history as it relates to the query.
- -S, --stack
-
Print the window stacking order.
- [-m,--monitor [MONITOR_SEL]] | [-d,--desktop [DESKTOP_SEL]] | [-w, --window [WINDOW_SEL]]
-
Constrain matches to the selected monitor, desktop or window.
- -a, --add <class_name>|<instance_name> [-d DESKTOP_SEL [--follow]] [--tags <name>|^<n>[,…]][--floating] [--fullscreen] [--locked] [--sticky] [--focus] [--unmanage] [--one-shot]
-
Create a new rule.
- -r, --remove <name>|^<n>|tail|head…
-
Remove the rules with the given names or indexes.
- -l, --list [<name>]
-
List the rules.
Colors are either X color names or #RRGGBB, booleans are true or false.
All the boolean settings are false by default.
- focused_border_color
-
Color of the border of a focused window of a focused monitor.
- active_border_color
-
Color of the border of a focused window of an unfocused monitor.
- normal_border_color
-
Color of the border of an unfocused window.
- presel_border_color
-
Color of the presel message feedback.
- focused_locked_border_color
-
Color of the border of a focused locked window of a focused monitor.
- active_locked_border_color
-
Color of the border of a focused locked window of an unfocused monitor.
- normal_locked_border_color
-
Color of the border of an unfocused locked window.
- focused_sticky_border_color
-
Color of the border of a focused sticky window of a focused monitor.
- active_sticky_border_color
-
Color of the border of a focused sticky window of an unfocused monitor.
- normal_sticky_border_color
-
Color of the border of an unfocused sticky window.
- urgent_border_color
-
Color of the border of an urgent window.
- split_ratio
-
Default split ratio.
- growth_factor
-
Intensity of the growth involved in pulling or pushing an edge.
- history_aware_focus
-
Give priority to the focus history when focusing nodes.
- borderless_monocle
-
Remove borders for tiled windows in monocle mode.
- gapless_monocle
-
Remove gaps for tiled windows in monocle mode.
- focus_follows_pointer
-
Focus the window under the pointer.
- pointer_follows_monitor
-
When focusing a monitor, put the pointer at its center.
- auto_alternate
-
Interpret two consecutive identical use messages as an alternate message.
- auto_cancel
-
Interpret two consecutive identical presel messages as a cancel message.
- apply_floating_atom
-
Set the value of the _BSPWM_FLOATING_WINDOW atom of each window according to its floating state.
- honor_ewmh_focus
-
Honor EWMH requests to focus a window.
- top_padding
- right_padding
- bottom_padding
- left_padding
-
Padding space added at the sides of the monitor.
- BSPWM_SOCKET
-
The path of the socket used for the communication between bspc and bspwm. If it isn’t defined, then the following path is used: /tmp/bspwm-socket.
-
Any EWMH compliant panel (e.g.: tint2, bmpanel2, etc.).
-
A custom panel if the -s flag is used (have a look at the files in examples/panel).
-
Configured and controlled through messages.
-
Multiple monitors support (via RandR).
-
EWMH support (tint2 works).
-
Hybrid tiling.
-
Steven Allen <steven at stebalien.com>
-
Thomas Adam <thomas at xteddy.org>
-
Ivan Kanakarakis <ivan.kanak at gmail.com>