bspc(1)
NAME
bspwm - Binary space partitioning window manager
SYNOPSIS
bspwm [-h|-v|-c CONFIG_PATH] bspc DOMAIN [SELECTOR] COMMANDS bspc COMMAND [OPTIONS] [ARGUMENTS]
DESCRIPTION
bspwm is a tiling window manager that represents windows as the leaves of a full binary tree. It is controlled and configured via bspc.
OPTIONS
-h
Print the synopsis and exit.
-v
Print the version and exit.
-c CONFIG_PATH
Use the given configuration file.
COMMON DEFINITIONS
DIR := north | west | south | east
CYCLE_DIR := next | prev
SELECTORS
Selectors are used to select a target node, desktop, or monitor. A
selector can either describe the target relatively or name it globally.
Selectors consist of an optional reference, a descriptor and any number
of non-conflicting modifiers as follows:
[REFERENCE#]DESCRIPTOR(.MODIFIER)*
The relative targets are computed in relation to the given reference
(the default reference value is focused).
An exclamation mark can be prepended to any modifier in order to
reverse its meaning.
Node
Select a node.
NODE_SEL := [NODE_SEL#](DIR|CYCLE_DIR|PATH|last|older|newer|focused|pointed|biggest|<node_id>)[.[!]focused][.[!]automatic][.[!]local][.[!]active][.[!]leaf][.[!]window][.[!]STATE][.[!]FLAG][.[!]LAYER][.[!]same_class][.[!]descendant_of][.[!]ancestor_of]
STATE := tiled|pseudo_tiled|floating|fullscreen
FLAG := hidden|sticky|private|locked|urgent
LAYER := below|normal|above
PATH := @[DESKTOP_SEL:][[/]JUMP](/JUMP)*
JUMP := first|1|second|2|brother|parent|DIR
Descriptors
DIR
Selects the window in the given (spacial) direction relative to
the reference node.
CYCLE_DIR
Selects the window in the given (cyclic) direction relative to
the reference node.
PATH
Selects the node at the given path.
last
Selects the previously focused node relative to the reference
node.
older
Selects the node older than the reference node in the history.
newer
Selects the node newer than the reference node in the history.
focused
Selects the currently focused node.
pointed
Selects the window under the pointer.
biggest
Selects the biggest window.
<node_id>
Selects the node with the given ID.
Path Jumps
The initial node is the focused node (or the root if the path
starts with /) of the reference desktop (or the selected desktop if
the path has a DESKTOP_SEL prefix).
1|first
Jumps to the first child.
2|second
Jumps to the second child.
brother
Jumps to the brother node.
parent
Jumps to the parent node.
DIR
Jumps to the node holding the edge in the given direction.
Modifiers
[!]focused
Only consider focused or unfocused nodes.
[!]automatic
Only consider nodes in automatic or manual insertion mode.
[!]local
Only consider nodes in or not in the reference desktop.
[!]active
Only consider nodes in or not in the active desktop of their
monitor.
[!]leaf
Only consider leaves or internal nodes.
[!]window
Only consider nodes that hold or don't hold a window.
[!](tiled|pseudo_tiled|floating|fullscreen)
Only consider windows in or not in the given state.
[!]same_class
Only consider windows that have or don't have the same class as
the reference window.
[!]descendant_of
Only consider nodes that are or aren't descendants of the
reference node.
[!]ancestor_of
Only consider nodes that are or aren't ancestors of the
reference node.
[!](hidden|sticky|private|locked|urgent)
Only consider windows that have or don't have the given flag
set.
[!](below|normal|above)
Only consider windows in or not in the given layer.
Desktop
Select a desktop.
DESKTOP_SEL := [DESKTOP_SEL#](CYCLE_DIR|last|older|newer|[MONITOR_SEL:](focused|^<n>)|<desktop_id>|<desktop_name>)[.[!]occupied][.[!]focused][.[!]urgent][.[!]local]
Descriptors
CYCLE_DIR
Selects the desktop in the given direction relative to the
reference desktop.
last
Selects the previously focused desktop relative to the
reference desktop.
older
Selects the desktop older than the reference desktop in the
history.
newer
Selects the desktop newer than the reference desktop in the
history.
focused
Selects the currently focused desktop.
^<n>
Selects the nth desktop.
<desktop_id>
Selects the desktop with the given ID.
<desktop_name>
Selects the desktop with the given name.
Modifiers
[!]occupied
Only consider occupied or free desktops.
[!]focused
Only consider focused or unfocused desktops.
[!]urgent
Only consider urgent or non urgent desktops.
[!]local
Only consider inside or outside of the reference monitor.
Monitor
Select a monitor.
MONITOR_SEL := [MONITOR_SEL#](DIR|CYCLE_DIR|last|older|newer|focused|primary|^<n>|<monitor_id>|<monitor_name>)[.[!]occupied][.[!]focused]
Descriptors
DIR
Selects the monitor in the given (spacial) direction relative
to the reference monitor.
CYCLE_DIR
Selects the monitor in the given (cyclic) direction relative to
the reference monitor.
last
Selects the previously focused monitor relative to the
reference monitor.
older
Selects the monitor older than the reference monitor in the
history.
newer
Selects the monitor newer than the reference monitor in the
history.
focused
Selects the currently focused monitor.
primary
Selects the primary monitor.
^<n>
Selects the nth monitor.
<monitor_id>
Selects the monitor with the given ID.
<monitor_name>
Selects the monitor with the given name.
Modifiers
[!]occupied
Only consider monitors where the focused desktop is occupied or
free.
[!]focused
Only consider focused or unfocused monitors.
WINDOW STATES
tiled
Its size and position are determined by the splitting type and
ratio of each node of its path in the window tree.
pseudo_tiled
Has an unrestricted size while being centered in its tiling space.
floating
Can be moved/resized freely. Although it doesn't occupy any tiling
space, it is still part of the window tree.
fullscreen
Fills its monitor rectangle and has no borders. It is send in the
ABOVE layer by default.
NODE FLAGS
hidden
Is hidden and doesn't occupy any tiling space.
sticky
Stays in the focused desktop of its monitor.
private
Tries to keep the same tiling position/size.
locked
Ignores the node --close message.
urgent
Has its urgency hint set. This flag is set externally.
STACKING LAYERS
There's three stacking layers: BELOW, NORMAL and ABOVE. In each layer, the window are orderered as follow: tiled & pseudo-tiled < fullscreen < floating.
DOMAINS
Node
General Syntax
node [NODE_SEL] COMMANDS
If NODE_SEL is omitted, focused is assumed.
Commands
-f, --focus [NODE_SEL]
Focus the selected or given node.
-a, --activate [NODE_SEL]
Activate the selected or given node.
-d, --to-desktop DESKTOP_SEL
Send the selected node to the given desktop.
-m, --to-monitor MONITOR_SEL
Send the selected node to the given monitor.
-n, --to-node NODE_SEL
Transplant the selected node to the given node.
-s, --swap NODE_SEL
Swap the selected node with the given node.
-p, --presel-dir [~]DIR|cancel
Preselect the splitting area of the selected node (or cancel
the preselection). If ~ is prepended to DIR and the current
preselection direction matches DIR, then the argument is
interpreted as cancel.
-o, --presel-ratio RATIO
Set the splitting ratio of the preselection area.
-v, --move dx dy
Move the selected window by dx pixels horizontally and dy
pixels vertically.
-z, --resize
top|left|bottom|right|top_left|top_right|bottom_right|bottom_left
dx dy
Resize the selected window by moving the given handle by dx
pixels horizontally and dy pixels vertically.
-r, --ratio RATIO|(+|-)PIXELS
Set the splitting ratio of the selected node (0 < RATIO < 1).
-R, --rotate 90|270|180
Rotate the tree rooted at the selected node.
-F, --flip horizontal|vertical
Flip the the tree rooted at selected node.
-E, --equalize
Reset the split ratios of the tree rooted at the selected node
to their default value.
-B, --balance
Adjust the split ratios of the tree rooted at the selected node
so that all windows occupy the same area.
-C, --circulate forward|backward
Circulate the windows of the tree rooted at the selected node.
-t, --state [~](tiled|pseudo_tiled|floating|fullscreen)
Set the state of the selected window. If ~ is present and the
current state matches the given state, then the argument is
interpreted as the last state.
-g, --flag hidden|sticky|private|locked[=on|off]
Set or toggle the given flag for the selected node.
-l, --layer below|normal|above
Set the stacking layer of the selected window.
-i, --insert-receptacle
Insert a receptacle node at the selected node.
-c, --close
Close the windows rooted at the selected node.
-k, --kill
Kill the windows rooted at the selected node.
Desktop
General Syntax
desktop [DESKTOP_SEL] COMMANDS
If DESKTOP_SEL is omitted, focused is assumed.
COMMANDS
-f, --focus [DESKTOP_SEL]
Focus the selected or given desktop.
-a, --activate [DESKTOP_SEL]
Activate 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.
-b, --bubble CYCLE_DIR
Bubble the selected desktop in the given direction.
-r, --remove
Remove the selected desktop.
Monitor
General Syntax
monitor [MONITOR_SEL] COMMANDS
If MONITOR_SEL is omitted, focused is assumed.
Commands
-f, --focus [MONITOR_SEL]
Focus the selected or given monitor.
-s, --swap MONITOR_SEL
Swap the selected monitor with the given monitor.
-a, --add-desktops <name>...
Create desktops with the given names in the selected monitor.
-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.
-g, --rectangle WxH+X+Y
Set the rectangle of the selected monitor.
-n, --rename <new_name>
Rename the selected monitor.
-r, --remove
Remove the selected monitor.
Query
General Syntax
query COMMANDS [OPTIONS]
Commands
The optional selectors are references.
-N, --nodes [NODE_SEL]
List the IDs of the matching nodes.
-D, --desktops [DESKTOP_SEL]
List the IDs of the matching desktops.
-M, --monitors [MONITOR_SEL]
List the IDs of the matching monitors.
-T, --tree
Print a JSON representation of the matching item.
Options
-m,--monitor [MONITOR_SEL], -d,--desktop [DESKTOP_SEL], -n, --node
[NODE_SEL]
Constrain matches to the selected monitor, desktop or node. The
descriptor can be omitted for -M, -D and -N.
Wm
General Syntax
wm COMMANDS
Commands
-d, --dump-state
Dump the current world state on standard output.
-l, --load-state <file_path>
Load a world state from the given file.
-a, --add-monitor <name> WxH+X+Y
Add a monitor for the given name and rectangle.
-o, --adopt-orphans
Manage all the unmanaged windows remaining from a previous
session.
-h, --record-history on|off
Enable or disable the recording of node focus history.
-g, --get-status
Print the current status information.
Rule
General Syntax
rule COMMANDS
Commands
-a, --add (<class_name>|*)[:(<instance_name>|*)] [-o|--one-shot]
[monitor=MONITOR_SEL|desktop=DESKTOP_SEL|node=NODE_SEL]
[state=STATE] [layer=LAYER] [split_dir=DIR] [split_ratio=RATIO]
[(hidden|sticky|private|locked|center|follow|manage|focus|border)=(on|off)]
Create a new rule.
-r, --remove
^<n>|head|tail|(<class_name>|*)[:(<instance_name>|*)]...
Remove the given rules.
-l, --list
List the rules.
Config
General Syntax
config [-m MONITOR_SEL|-d DESKTOP_SEL|-n NODE_SEL] <key> [<value>]
Get or set the value of <key>.
Subscribe
General Syntax
subscribe (all|report|monitor|desktop|node|...)*
Continuously print status information. See the EVENTS section
for the detailed description of each event.
Quit
General Syntax
quit [<status>]
Quit with an optional exit status.
EXIT CODES
If the server can't handle a message, bspc will return with a non-zero exit code.
SETTINGS
Colors are in the form #RRGGBB, booleans are true, on, false or off.
All the boolean settings are false by default unless stated otherwise.
Global Settings
normal_border_color
Color of the border of an unfocused window.
active_border_color
Color of the border of a focused window of an unfocused monitor.
focused_border_color
Color of the border of a focused window of a focused monitor.
presel_feedback_color
Color of the node --presel-{dir,ratio} message feedback area.
split_ratio
Default split ratio.
status_prefix
Prefix prepended to each of the status lines.
external_rules_command
External command used to retrieve rule consequences. The command
will receive the following arguments: window ID, class and instance
names, monitor, desktop and node selectors. The output of that
command must have the following format: key1=value1 key2=value2 ...
(the valid key/value pairs are given in the description of the rule
command).
initial_polarity
On which child should a new window be attached when adding a window
on a single window tree in automatic mode. Accept the following
values: first_child, second_child.
borderless_monocle
Remove borders of tiled windows for the monocle desktop layout.
gapless_monocle
Remove gaps of tiled windows for the monocle desktop layout.
paddingless_monocle
Remove padding space for the monocle desktop layout.
single_monocle
Set the desktop layout to monocle if there's only one tiled window
in the tree.
pointer_motion_interval
The minimum interval, in milliseconds, between two motion notify
events.
pointer_modifier
Keyboard modifier used for moving or resizing windows. Accept the
following values: shift, control, lock, mod1, mod2, mod3, mod4,
mod5.
pointer_action1, pointer_action2, pointer_action3
Action performed when pressing pointer_modifier + button<n>. Accept
the following values: move, resize_side, resize_corner, focus,
none.
click_to_focus
Focus a window (or a monitor) by clicking it.
focus_follows_pointer
Focus the window under the pointer.
pointer_follows_focus
When focusing a window, put the pointer at its center.
pointer_follows_monitor
When focusing a monitor, put the pointer at its center.
ignore_ewmh_focus
Ignore EWMH focus requests coming from applications.
center_pseudo_tiled
Center pseudo tiled windows into their tiling rectangles. Defaults
to true.
honor_size_hints
Apply ICCCM window size hints.
remove_disabled_monitors
Consider disabled monitors as disconnected.
remove_unplugged_monitors
Remove unplugged monitors.
merge_overlapping_monitors
Merge overlapping monitors (the bigger remains).
Monitor and Desktop Settings
top_padding, right_padding, bottom_padding, left_padding
Padding space added at the sides of the monitor or desktop.
Desktop Settings
window_gap
Size of the gap that separates windows.
Node Settings
border_width
Window border width.
POINTER BINDINGS
button1
Focus the window under the pointer if click_to_focus is set.
pointer_modifier + button1
Move the window under the pointer.
pointer_modifier + button2
Resize the window under the pointer by dragging the nearest side.
pointer_modifier + button3
Resize the window under the pointer by dragging the nearest corner.
The behavior of pointer_modifier + button<n> can be modified through
the pointer_action<n> setting.
EVENTS
report
See the next section for the description of the format.
monitor_add <monitor_id> <monitor_name> <monitor_geometry>
A monitor is added.
monitor_rename <monitor_id> <old_name> <new_name>
A monitor is renamed.
monitor_remove <monitor_id>
A monitor is removed.
monitor_swap <src_monitor_id> <dst_monitor_id>
A monitor is swapped.
monitor_focus <monitor_id>
A monitor is focused.
monitor_geometry <monitor_id> <monitor_geometry>
The geometry of a monitor changed.
desktop_add <monitor_id> <desktop_id> <desktop_name>
A desktop is added.
desktop_rename <monitor_id> <desktop_id> <old_name> <new_name>
A desktop is renamed.
desktop_remove <monitor_id> <desktop_id>
A desktop is removed.
desktop_swap <src_monitor_id> <src_desktop_id> <dst_monitor_id>
<dst_desktop_id>
A desktop is swapped.
desktop_transfer <src_monitor_id> <src_desktop_id> <dst_monitor_id>
A desktop is transferred.
desktop_focus <monitor_id> <desktop_id>
A desktop is focused.
desktop_activate <monitor_id> <desktop_id>
A desktop is activated.
desktop_layout <monitor_id> <desktop_id> tiled|monocle
The layout of a desktop changed.
node_manage <monitor_id> <desktop_id> <node_id> <ip_id>
A window is managed.
node_unmanage <monitor_id> <desktop_id> <node_id>
A window is unmanaged.
node_swap <src_monitor_id> <src_desktop_id> <src_node_id>
<dst_monitor_id> <dst_desktop_id> <dst_node_id>
A node is swapped.
node_transfer <src_monitor_id> <src_desktop_id> <src_node_id>
<dst_monitor_id> <dst_desktop_id> <dst_node_id>
A node is transferred.
node_focus <monitor_id> <desktop_id> <node_id>
A node is focused.
node_activate <monitor_id> <desktop_id> <node_id>
A node is activated.
node_presel <monitor_id> <desktop_id> <node_id> (dir DIR|ratio
RATIO|cancel)
A node is preselected.
node_stack <node_id_1> below|above <node_id_2>
A node is stacked below or above another node.
node_geometry <monitor_id> <desktop_id> <node_id> <node_geometry>
The geometry of a window changed.
node_state <monitor_id> <desktop_id> <node_id>
tiled|pseudo_tiled|floating|fullscreen on|off
The state of a window changed.
node_flag <monitor_id> <desktop_id> <node_id>
hidden|sticky|private|locked|urgent on|off
One of the flags of a node changed.
node_layer <monitor_id> <desktop_id> <node_id> below|normal|above
The layer of a window changed.
pointer_action <monitor_id> <desktop_id> <node_id>
move|resize_corner|resize_side begin|end
A pointer action occured.
Please note that bspwm initializes monitors before it reads messages on
its socket, therefore the initial monitor events can't be received.
REPORT FORMAT
Each report event message is 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(T|M)
Layout of the focused desktop of a monitor.
T(T|P|F|=|@)
State of the focused node of a focused desktop.
G(S?P?L?)
Active flags of the focused node of a focused desktop.
ENVIRONMENT VARIABLES
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<host_name>_<display_number>_<screen_number>-socket.
CONTRIBUTORS
* Steven Allen <steven at stebalien.com> * Thomas Adam <thomas at xteddy.org> * Ivan Kanakarakis <ivan.kanak at gmail.com>
AUTHOR
Bastien Dejean <nihilhill at gmail.com>
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
