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.
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|private[=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.
- -t, --toggle floating[=on|off]
-
Set or toggle the given state for 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.
- -o, --reorder-desktops <name>…
-
Reorder the desktops of the selected monitor to match the given order.
- -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.
- -n, --rename <new_name>
-
Rename the selected monitor.
- -s, --swap MONITOR_SEL
-
Swap the selected monitor with the given monitor.
- -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.
- --adopt-orphans
-
Manage all the unmanaged windows remaining from a previous session.
- --toggle-visibility
-
Toggle the visibility of all the windows.
- --record-history on|off
-
Enable or disable the recording of window focus history.
- --subscribe
-
Continuously print status informations on standard output.
Colors are either X color names or #RRGGBB, booleans are true or false.
All the boolean settings are false by default.
- rule_command
-
External command used to retrieve rule consequences. The command will receive the the ID of the window being processed as its first argument. The output of that command must have the following format: key1=value1 key2=value2 …, where keyN is one of floating, fullscreen, locked, sticky, private, frame, center, lower, follow, manage, focus, desktop or monitor.
- status_prefix
-
Prefix prepended to each of the status lines.
- 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.
- focused_private_border_color
-
Color of the border of a focused private window of a focused monitor.
- active_private_border_color
-
Color of the border of a focused private window of an unfocused monitor.
- normal_private_border_color
-
Color of the border of an unfocused private window.
- urgent_border_color
-
Color of the border of an urgent window.
- focused_frame_opacity
-
Opacity of a focused frame of a focused monitor.
- active_frame_opacity
-
Opacity of a focused frame of an unfocused monitor.
- normal_frame_opacity
-
Opacity of an unfocused frame.
- 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.
- ignore_ewmh_focus
-
Ignore EWMH requests to focus a window.
- remove_disabled_monitor
-
Consider disabled monitors as disconnected.
- top_padding
- right_padding
- bottom_padding
- left_padding
-
Padding space added at the sides of the monitor.
Status informations are composed of items separated by colons.
Each item has the form <type><value> where <type> is the first character of the item.
- M<monitor_name>
-
Focused monitor.
- m<monitor_name>
-
Unfocused monitor.
- O<desktop_name>
-
Occupied focused desktop.
- o<desktop_name>
-
Occupied unfocused desktop.
- F<desktop_name>
-
Free focused desktop.
- f<desktop_name>
-
Free unfocused desktop.
- U<desktop_name>
-
Urgent focused desktop.
- u<desktop_name>
-
Urgent unfocused desktop.
- L(tiled|monocle)
-
Layout of the focused desktop of the focused 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>