Skip to content

Commit 0ea2e94

Browse files
nikitabobkonikitabobko
committed
WIP guide
1 parent fd704c9 commit 0ea2e94

File tree

3 files changed

+147
-53
lines changed

3 files changed

+147
-53
lines changed

‎README.md

+45-42
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
AeroSpace is a tiling window manager for macOS.
44

5-
## Status
5+
## Project status
66

77
🚧 **Work in progress.** Not usable yet 🚧
88

@@ -14,14 +14,17 @@ I will publish first release once I believe it's usable, so subscribe to release
1414

1515
- **Manual** tiling window manager
1616
- [i3](https://i3wm.org/) inspired
17-
- AeroSpace employs its **own emulation of virtual workspaces** instead of relying on native macOS Spaces due to
17+
- AeroSpace employs its [own emulation of virtual workspaces](./docs/guide.md#emulation-of-virtual-workspaces) instead of relying
18+
on native macOS Spaces due to
1819
their considerable limitations
1920
- Plain text configuration (dotfiles friendly)
2021
- **[PLANNED]** CLI scriptable
2122
- Doesn't require disabling SIP (System Integrity Protection)
2223
- Proper multi-monitor support (i3-like paradigm)
2324
- Status menu icon displays current workspace name
2425

26+
## [AeroSpace Guide](./docs/guide.md)
27+
2528
## How to build the project
2629

2730
You would need a Mac.
@@ -37,43 +40,43 @@ Firstly, install [xcodegen](https://github.com/yonaskolb/XcodeGen). Then run in
3740
./run-tests.sh
3841
```
3942

40-
## Todo
41-
42-
- is dialog, is resizable, is modal?
43-
- select parent and kill several windows at once
44-
- select parent -> outline several windows?
45-
- OR: outline with "SLSSetWindowOpacity"
46-
- OR: "shake" windows
47-
- CLI interface
48-
- Check all todos in code
49-
- move vs swap
50-
- what is src/Assets.xcassets ?
51-
- license
52-
- unminimize apps automatically
53-
- minimized apps handling
54-
- macOS fullscreen apps handling
55-
- unhide apps automatically
56-
57-
## Challenges
58-
59-
- Window overlapping
60-
- "floating" window layout
61-
- windows' min/max sizes
62-
63-
## Known Special windows to check
64-
65-
- XCode welcome screen
66-
- Finder preview
67-
- Finder tabs
68-
- Chrome create bookmark window
69-
- Toolbox window
70-
- IntelliJ dialog windows (e.g. "Add to git")
71-
- IntelliJ project structure modal window blocks main window resize
72-
- VLC full screen window (eh, I wish every fullscreen window in macOS worked like that)
73-
- iTerm drop down window
74-
- Chrome cmd+f window
75-
76-
## Limitations of macOS API
77-
78-
- It's not possible to find to what monitor window is assigned
79-
- It's not possible to __reliably__ know what monitor is currently active
43+
## Values of the project
44+
45+
**Values**
46+
- AeroSpace is targeted at advanced users and developers
47+
- Keyboard centric
48+
- Never break configuration files or existing workflows (Guaranteed once AeroSpace reaches 1.0 version)
49+
- AeroSpace doesn't use GUI, unless necessarily
50+
- AeroSpace will never provide a GUI for configuration. For advanced users, it's easier to edit a configuration file in text
51+
editor rather than navigating through checkboxes in GUI.
52+
- Status menu icon is ok, because visual feedback is needed
53+
- Provide _practical_ features. Fancy appearance features are not _practical_
54+
- If "dark magic" (aka "private APIs", "code injections", etc) can be avoided, it must be avoided
55+
- Right now, AeroSpace uses only a [single private API](./src/Bridged-Header.h). Everything else is [macOS public accessibility
56+
API](https://developer.apple.com/documentation/applicationservices/axuielement_h).
57+
- AeroSpace will never require you to disable SIP (System Integrity Protection). For example, yabai [requires you to disable
58+
SIP](https://github.com/koekeishiya/yabai/issues/1863) to use some of its features. AeroSpace will either find another way
59+
(e.g. [emulation of workspaces](./docs/guide.md#emulation-of-virtual-workspaces)) or will not implement this feature at all
60+
(window transparency and window shadowing are not _practical_ features)
61+
62+
**Non Values**
63+
- Play nicely with existing macOS features. If limitations are imposed then AeroSpace won't play nicely with existing macOS
64+
features
65+
- E.g. AeroSpace doesn't acknowledge the existence of macOS Spaces, and it uses [emulation of its own
66+
workspaces](./docs/guide.md#emulation-of-virtual-workspaces)
67+
68+
## Tip of the day
69+
70+
```bash
71+
defaults write -g NSWindowShouldDragOnGesture YES
72+
```
73+
74+
Now, you can move windows by holding `ctrl`+`cmd` and dragging any part of the window (not necessarily the window title)
75+
76+
Source: [reddit](https://www.reddit.com/r/MacOS/comments/k6hiwk/keyboard_modifier_to_simplify_click_drag_of/)
77+
78+
## Related projects
79+
80+
If AeroSpace doesn't work for you, take a look at projects by other authors:
81+
- [Amethyst](https://github.com/ianyh/Amethyst)
82+
- [yabai](https://github.com/koekeishiya/yabai)

‎config-examples/default-config.toml

+37-11
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,50 @@
1-
# For all possible keys and modifiers see: https://github.com/nikitabobko/AeroSpace/blob/main/src/config/keysMap.swift
1+
# You can use it to add commands that run after login to macOS user session.
2+
# 'start-at-login' needs to be 'true' for 'after-login-command' to work
3+
# For the list of available commands see: https://github.com/nikitabobko/AeroSpace/blob/main/docs/commands.md
4+
after-login-command = []
25

3-
# todo review defaults
6+
# You can use it to add commands that run after AeroSpace startup.
7+
# 'after-startup-command' is run after 'after-login-command'
8+
# For the list of available commands see: https://github.com/nikitabobko/AeroSpace/blob/main/docs/commands.md
9+
after-startup-command = []
410

5-
after-login-command = [] # You can use it to add command or commands that run after login to macOS user session.
6-
after-startup-command = [] # You can use it to add command or commands that run after startup.
11+
# Visual indent makes it easier to understand that containers of the same orientation are nested.
12+
# If you have 'auto-opposite-orientation-for-nested-containers' enabled then there is no way to observe the indent
713
indent-for-nested-containers-with-the-same-orientation = 30
8-
enable-normalization-flatten-containers = true
9-
enable-normalization-opposite-orientation-for-nested-containers = true
14+
15+
# todo Not tested
1016
start-at-login = false
17+
18+
# todo drop. I don't see any value in providing configuration for this option. Why would anyone may want to set it
19+
# to 'false'?
1120
floating-windows-on-top = true
12-
main-layout = 'h_list' # todo change
13-
DEBUG-all-windows-are-floating = false # todo drop
14-
accordion-padding = 30 # todo dp?
1521

22+
# Normalization. See: https://github.com/nikitabobko/AeroSpace/blob/main/docs/guide.md#normalization
23+
enable-normalization-flatten-containers = true
24+
enable-normalization-opposite-orientation-for-nested-containers = true
25+
26+
# Accordion is a layout where windows are placed on top of each other.
27+
# - Horizontal accordion puts paddings on left and right to make it clear that containers exist in this direction
28+
# - Vertical accordion puts paddings on above and below to make it clear that containers exist in this direction
29+
# The 'accordion-padding' specifies the size of the padding. You can set 0 to disable padding feature
30+
accordion-padding = 30
31+
main-layout = 'h_list' # TODO SUBJECT TO CHANGE
32+
33+
# DEBUG KEY. DON'T USE IT
34+
DEBUG-all-windows-are-floating = false # TODO DROP
35+
36+
# It's a declaration of 'main' binding mode. See: https://github.com/nikitabobko/AeroSpace/blob/main/docs/guide.md#bindings-modes
37+
# 'main' binding mode must be always presented
1638
[mode.main.binding]
39+
40+
# For all possible keys and modifiers see: https://github.com/nikitabobko/AeroSpace/blob/main/src/config/keysMap.swift
41+
# For all possible commands see: https://github.com/nikitabobko/AeroSpace/blob/main/docs/commands.md
42+
1743
alt-enter = 'exec-and-forget open -n /System/Applications/Utilities/Terminal.app'
1844

1945
alt-slash = 'layout h_list v_list' # todo layout vs change-parent-container-kind
2046
alt-comma = 'layout h_accordion v_accordion'
2147

22-
# todo focus floating binding
23-
2448
alt-h = 'focus left'
2549
alt-j = 'focus down'
2650
alt-k = 'focus up'
@@ -106,6 +130,7 @@ alt-shift-z = 'move-container-to-workspace Z'
106130
alt-tab = 'workspace-back-and-forth'
107131
alt-shift-tab = 'move-workspace-to-display next'
108132

133+
# It's a declaration of binding mode. See: https://github.com/nikitabobko/AeroSpace/blob/main/docs/guide.md#bindings-modes
109134
[mode.service.binding]
110135
r = ['flatten-workspace-tree', 'mode main']
111136
o = ['reload-config', 'mode main']
@@ -115,6 +140,7 @@ backslash = ['close-all-windows-but-current', 'mode main']
115140
esc = 'mode main'
116141
enter = 'mode main'
117142

143+
# It's a declaration of binding mode. See: https://github.com/nikitabobko/AeroSpace/blob/main/docs/guide.md#bindings-modes
118144
[mode.move-in.binding]
119145
alt-shift-h = ['move-in left', 'mode main']
120146
alt-shift-j = ['move-in down', 'mode main']

‎docs/guide.md

+65
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# AeroSpace Guide
2+
3+
**Table of contents**
4+
5+
- [Tree](#tree)
6+
- [Normalization](#normalization)
7+
- [Floating windows](#floating-windows)
8+
- [Default keybindings](#default-keybindings)
9+
- [Configuring AeroSpace](#configuring-aerospace)
10+
- [Binding modes](#bindings-modes)
11+
- [Commands](#commands)
12+
- [Emulation of virtual workspaces](#emulation-of-virtual-workspaces)
13+
- [A note on mission control](#a-note-on-mission-control)
14+
- [A note on 'Displays have separate Spaces'](#a-note-on-displays-have-separate-spaces)
15+
- [Multiple displays](#multiple-displays)
16+
17+
## Tree
18+
TODO DOCUMENTATION. This section is yet to be written, for now you can refer to https://i3wm.org/docs/userguide.html#tree
19+
20+
### Normalization
21+
TODO DOCUMENTATION
22+
23+
### Floating windows
24+
TODO DOCUMENTATION
25+
26+
Normally, floating windows are not part of the tiling tree except for the 'focus' command. From 'focus' command perspective,
27+
floating windows are part of the tree.
28+
29+
## Default keybindings
30+
TODO DOCUMENTATION the idea behind default keybindings
31+
32+
## Configuring AeroSpace
33+
34+
AeroSpace will read config file from `~/.aerospace.toml`. Please see the following config samples:
35+
- The default config with comments: [default-config.toml](../config-examples/default-config.toml)
36+
- i3 like config: [i3-like-config-example.toml](../config-examples/i3-like-config-example.toml)
37+
38+
AeroSpace uses TOML format for the config. TOML is a popular format with open specification. TOML is easy to read, and it supports
39+
comments. See [TOML site for more info](https://toml.io/en/)
40+
41+
### Binding modes
42+
TODO DOCUMENTATION
43+
44+
### Commands
45+
46+
AeroSpace is controlled by commands. For more info see [the list of all available commands](./commands.md).
47+
48+
## Emulation of virtual workspaces
49+
50+
The supposed workflow is to only have one macOS Space (or as many as monitors you have) and don't interact with macOS spaces in
51+
any way
52+
53+
When user quits AeroSpace or before crashing, AeroSpace puts windows back to the center of the screen
54+
55+
### A note on mission control
56+
TODO DOCUMENTATION
57+
Enable 'Group windows by application'
58+
59+
### A note on 'Displays have separate Spaces'
60+
TODO DOCUMENTATION
61+
62+
## Multiple displays
63+
TODO DOCUMENTATION
64+
TODO DOCUMENTATION. Add difference with i3
65+

0 commit comments

Comments
 (0)