{"id":13423542,"url":"https://github.com/baskerville/bspwm","last_synced_at":"2025-05-14T01:07:53.233Z","repository":{"id":4103957,"uuid":"5213091","full_name":"baskerville/bspwm","owner":"baskerville","description":"A tiling window manager based on binary space partitioning","archived":false,"fork":false,"pushed_at":"2024-07-19T17:23:15.000Z","size":3235,"stargazers_count":7930,"open_issues_count":344,"forks_count":419,"subscribers_count":133,"default_branch":"master","last_synced_at":"2025-04-02T01:09:58.424Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/baskerville.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-07-28T08:24:18.000Z","updated_at":"2025-04-01T21:08:18.000Z","dependencies_parsed_at":"2024-05-05T06:32:41.969Z","dependency_job_id":"3b6db12a-705e-4400-b724-0455a983236a","html_url":"https://github.com/baskerville/bspwm","commit_stats":{"total_commits":1438,"total_committers":60,"mean_commits":"23.966666666666665","dds":0.1008344923504868,"last_synced_commit":"8fc2269fe0f29a785885bcd9122812eae7226d7b"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baskerville%2Fbspwm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baskerville%2Fbspwm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baskerville%2Fbspwm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baskerville%2Fbspwm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/baskerville","download_url":"https://codeload.github.com/baskerville/bspwm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247962508,"owners_count":21024867,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T00:00:37.036Z","updated_at":"2025-04-09T02:11:31.858Z","avatar_url":"https://github.com/baskerville.png","language":"C","readme":"## Description\n\n*bspwm* is a tiling window manager that represents windows as the leaves of a full binary tree.\n\nIt only responds to X events, and the messages it receives on a dedicated socket.\n\n*bspc* is a program that writes messages on *bspwm*'s socket.\n\n*bspwm* doesn't handle any keyboard or pointer inputs: a third party program (e.g. *sxhkd*) is needed in order to translate keyboard and pointer events to *bspc* invocations.\n\nThe outlined architecture is the following:\n\n```\n        PROCESS          SOCKET\nsxhkd  --------\u003e  bspc  \u003c------\u003e  bspwm\n```\n\n## Configuration\n\nThe default configuration file is `$XDG_CONFIG_HOME/bspwm/bspwmrc`: this is simply a shell script that calls *bspc*.\n\nAn argument is passed to that script to indicate whether is was executed after a restart (`$1 -gt 0`) or not (`$1 -eq 0`).\n\nKeyboard and pointer bindings are defined with [sxhkd](https://github.com/baskerville/sxhkd).\n\nExample configuration files can be found in the [examples](examples) directory.\n\n## Monitors, desktops and windows\n\n*bspwm* holds a list of monitors.\n\nA monitor is just a rectangle that contains desktops.\n\nA desktop is just a pointer to a tree.\n\nMonitors only show the tree of one desktop at a time (their focused desktop).\n\nThe tree is a partition of a monitor's rectangle into smaller rectangular regions.\n\nEach node in a tree either has zero or two children.\n\nEach internal node is responsible for splitting a rectangle in half.\n\nA split is defined by two parameters: the type (horizontal or vertical) and the ratio (a real number *r* such that *0 \u003c r \u003c 1*).\n\nEach leaf node holds exactly one window.\n\n## Insertion modes\n\nWhen *bspwm* receives a new window, it inserts it into a window tree at the specified insertion point (a leaf) using the insertion mode specified for that insertion point.\n\nThe insertion mode tells *bspwm* how it should alter the tree in order to insert new windows on a given insertion point.\n\nBy default the insertion point is the focused window and its insertion mode is *automatic*.\n\n### Manual mode\n\nThe user can specify a region in the insertion point where the next new window should appear by sending a *node -p|--presel-dir DIR* message to *bspwm*.\n\nThe *DIR* argument allows to specify how the insertion point should be split (horizontally or vertically) and if the new window should be the first or the second child of the new internal node (the insertion point will become its *brother*).\n\nAfter doing so the insertion point goes into *manual* mode.\n\nLet's consider the following scenario:\n\n```\n            a                          a                          a\n           / \\                        / \\                        / \\\n          1   b         ---\u003e         c   b         ---\u003e         c   b\n          ^  / \\                    / \\ / \\                    / \\ / \\\n            2   3                  4  1 2  3                  d  1 2  3\n                                   ^                         / \\\n                                                            5   4\n                                                            ^\n\n+-----------------------+  +-----------------------+  +-----------------------+\n|           |           |  |           |           |  |     |     |           |\n|           |     2     |  |     4     |     2     |  |  5  |  4  |     2     |\n|           |           |  |     ^     |           |  |  ^  |     |           |\n|     1     |-----------|  |-----------|-----------|  |-----------|-----------|\n|     ^     |           |  |           |           |  |           |           |\n|           |     3     |  |     1     |     3     |  |     1     |     3     |\n|           |           |  |           |           |  |           |           |\n+-----------------------+  +-----------------------+  +-----------------------+\n\n            X                          Y                          Z \n```\n\nIn state *X*, the insertion point is *1*.\n\nWe send the following message to *bspwm*: *node -p north*.\n\nThen add a new window: *4*, this leads to state *Y*: the new internal node, *c* becomes *a*'s first child.\n\nFinally we send another message: *node -p west* and add window *5*.\n\nThe ratio of the preselection (that ends up being the ratio of the split of the new internal node) can be changed with the *node -o|--presel-ratio* message.\n\n### Automatic mode\n\nThe *automatic* mode, as opposed to the *manual* mode, doesn't require any user choice. The way the new window is inserted is determined by the value of the automatic scheme and the initial polarity settings.\n\n#### Longest side scheme\n\nWhen the value of the automatic scheme is `longest_side`, the window will be attached as if the insertion point was in manual mode and the split direction was chosen based on the dimensions of the tiling rectangle and the initial polarity.\n\nLet's consider the following scenario, where the initial polarity is set to `second_child`:\n\n```\n             1                          a                          a\n             ^                         / \\                        / \\\n                         ---\u003e         1   2         ---\u003e         1   b\n                                          ^                         / \\\n                                                                   2   3\n                                                                       ^\n\n +-----------------------+  +-----------------------+  +-----------------------+\n |                       |  |           |           |  |           |           |\n |                       |  |           |           |  |           |     2     |\n |                       |  |           |           |  |           |           |\n |           1           |  |     1     |     2     |  |     1     |-----------|\n |           ^           |  |           |     ^     |  |           |           |\n |                       |  |           |           |  |           |     3     |\n |                       |  |           |           |  |           |     ^     |\n +-----------------------+  +-----------------------+  +-----------------------+\n\n             X                          Y                          Z\n```\n\nIn state *X*, a new window is added.\n\nSince *1* is wide, it gets split vertically and *2* is added as *a*'s second child given the initial polarity.\n\nThis leads to *Y* where we insert window *3*. *2* is tall and is therefore split horizontally. *3* is once again added as *b*'s second child.\n\n#### Alternate scheme\n\nWhen the value of the automatic scheme is `alternate`, the window will be attached as if the insertion point was in manual mode and the split direction was chosen based on the split type of the insertion point's parent and the initial polarity. If the parent is split horizontally, the insertion point will be split vertically and vice versa.\n\n#### Spiral scheme\n\nWhen the value of the automatic scheme is `spiral`, the window will *take the space* of the insertion point.\n\nLet's dive into the details with the following scenario:\n\n```\n             a                          a                          a\n            / \\                        / \\                        / \\\n           1   b         ---\u003e         1   c         ---\u003e         1   d\n              / \\                        / \\                        / \\\n             2   3                      4   b                      5   c\n             ^                          ^  / \\                     ^  / \\\n                                          3   2                      b   4\n                                                                    / \\\n                                                                   3   2\n\n +-----------------------+  +-----------------------+  +-----------------------+\n |           |           |  |           |           |  |           |           |\n |           |     2     |  |           |     4     |  |           |     5     |\n |           |     ^     |  |           |     ^     |  |           |     ^     |\n |     1     |-----------|  |     1     |-----------|  |     1     |-----------|\n |           |           |  |           |     |     |  |           |  3  |     |\n |           |     3     |  |           |  3  |  2  |  |           |-----|  4  |\n |           |           |  |           |     |     |  |           |  2  |     |\n +-----------------------+  +-----------------------+  +-----------------------+\n\n             X                          Y                          Z\n```\n\nIn state *X*, the insertion point, *2* is in automatic mode.\n\nWhen we add a new window, *4*, the whole tree rooted at *b* is reattached, as the second child of a new internal node, *c*.\n\nThe splitting parameters of *b* (type: *horizontal*, ratio: *½*) are copied to *c* and *b* is rotated by 90° clockwise.\n\nThe tiling rectangle of *4* in state *Y* is equal to the tiling rectangle of *2* in state *X*.\n\nThen the insertion of *5*, with *4* as insertion point, leads to *Z*.\n\nThe *spiral* automatic scheme generates window spirals that rotate clockwise (resp. anti-clockwise) if the insertion point is the first (resp. second) child of its parent.\n\n\n## Supported protocols and standards\n\n- The RandR and Xinerama protocols.\n- A subset of the EWMH and ICCCM standards.\n\n## Community\n\nWant to get in touch with other *bspwm* users or you need help? Join us on our:\n\n- Subreddit at [r/bspwm](https://www.reddit.com/r/bspwm/).\n- IRC channel at `#bspwm` on `irc.libera.chat` (maintained by [Emanuele Torre](https://github.com/emanuele6) / emanuele6 on IRC).\n- Matrix room at https://matrix.to/#/#bspwm:matrix.org\n","funding_links":[],"categories":["GUI","C","Window Managers","Packages","Window Manager","Windows mangers","X Windows Managers"],"sub_categories":["Windows Manager","Tiling Window Managers","window-managers","Tiling","Tiling window managers","Mesh networks","Bash Learning Resources","Courses"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaskerville%2Fbspwm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbaskerville%2Fbspwm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaskerville%2Fbspwm/lists"}