Skip to content

Commit

Permalink
EMPTY MESSAGE
Browse files Browse the repository at this point in the history
  • Loading branch information
@nikitabobko
nikitabobko committed Oct 13, 2024
1 parent 91bab1e commit 817287e
Show file tree
Hide file tree
Showing 10 changed files with 501 additions and 152 deletions.
Binary file modified assets/icon.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
533 changes: 430 additions & 103 deletions commands.html
View file

Large diffs are not rendered by default.

14 changes: 10 additions & 4 deletions config-examples/default-config.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,17 +31,23 @@ default-root-container-layout = 'tiles'
# tall monitor (anything higher than wide) gets vertical orientation
default-root-container-orientation = 'auto'

# Possible values: (qwerty|dvorak)
# See https://nikitabobko.github.io/AeroSpace/guide#key-mapping
key-mapping.preset = 'qwerty'

# Mouse follows focus when focused monitor changes
# Drop it from your config, if you don't like this behavior
# See https://nikitabobko.github.io/AeroSpace/guide#on-focus-changed-callbacks
# See https://nikitabobko.github.io/AeroSpace/commands#move-mouse
# Fallback value (if you omit the key): on-focused-monitor-changed = []
on-focused-monitor-changed = ['move-mouse monitor-lazy-center']

# You can effectively turn off macOS "Hide application" (cmd-h) feature by toggling this flag
# Useful if you don't use this macOS feature, but accidentally hit cmd-h or cmd-alt-h key
# Also see: https://nikitabobko.github.io/AeroSpace/goodness#disable-hide-app
automatically-unhide-macos-hidden-apps = false

# Possible values: (qwerty|dvorak)
# See https://nikitabobko.github.io/AeroSpace/guide#key-mapping
[key-mapping]
preset = 'qwerty'

# Gaps between windows (inner-*) and between monitor edges (outer-*).
# Possible values:
# - Constant: gaps.outer.top = 8
Expand Down
9 changes: 5 additions & 4 deletions config-examples/i3-like-config-example.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,11 @@ tell application "Terminal"
end tell'
'''

alt-j = 'focus left'
alt-k = 'focus down'
alt-l = 'focus up'
alt-semicolon = 'focus right'
# i3 wraps focus by default
alt-j = 'focus --boundaries-action wrap-around-the-workspace left'
alt-k = 'focus --boundaries-action wrap-around-the-workspace down'
alt-l = 'focus --boundaries-action wrap-around-the-workspace up'
alt-semicolon = 'focus --boundaries-action wrap-around-the-workspace right'

alt-shift-j = 'move left'
alt-shift-k = 'move down'
Expand Down
16 changes: 10 additions & 6 deletions goodness.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -559,7 +559,7 @@ <h1>AeroSpace Goodness</h1>
<div class="paragraph">
<p>Do you have a cool automatization, AeroSpace integration, or workflow?
Feel free to open an issue or pull request to add it to this list!
The source code of the page can be found in <code>./docs</code> directory.</p>
The source code of the page can be found in the <code>./docs</code> directory.</p>
</div>
</div>
</div>
Expand Down Expand Up @@ -743,6 +743,9 @@ <h2 id="open-a-new-window-with-applescript"><a class="anchor" href="#open-a-new-
<div class="sect1">
<h2 id="disable-hide-app"><a class="anchor" href="#disable-hide-app"></a><a class="link" href="#disable-hide-app">8. Disable annoying and useless "hide application" shortcut</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>If <code>automatically-unhide-macos-hidden-apps</code> isn&#8217;t enough, you can disable <code>cmd-h</code> altogether (which will make this hotkey unavailable for apps that might use it for other purposes)</p>
</div>
<div class="listingblock">
<div class="title">~/.aerospace.toml</div>
<div class="content">
Expand Down Expand Up @@ -829,10 +832,11 @@ <h2 id="i3-like-config"><a class="anchor" href="#i3-like-config"></a><a class="l
<span class="tok-s1">end tell&#39;</span>
<span class="tok-s1">&#39;&#39;&#39;</span>

<span class="tok-n">alt-j</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;focus left&#39;</span>
<span class="tok-n">alt-k</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;focus down&#39;</span>
<span class="tok-n">alt-l</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;focus up&#39;</span>
<span class="tok-n">alt-semicolon</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;focus right&#39;</span>
<span class="tok-c1"># i3 wraps focus by default</span>
<span class="tok-n">alt-j</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;focus --boundaries-action wrap-around-the-workspace left&#39;</span>
<span class="tok-n">alt-k</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;focus --boundaries-action wrap-around-the-workspace down&#39;</span>
<span class="tok-n">alt-l</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;focus --boundaries-action wrap-around-the-workspace up&#39;</span>
<span class="tok-n">alt-semicolon</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;focus --boundaries-action wrap-around-the-workspace right&#39;</span>

<span class="tok-n">alt-shift-j</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;move left&#39;</span>
<span class="tok-n">alt-shift-k</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;move down&#39;</span>
Expand Down Expand Up @@ -1261,7 +1265,7 @@ <h2 id="popular-apps-ids"><a class="anchor" href="#popular-apps-ids"></a><a clas
</div>
<div id="footer">
<div id="footer-text">
Last updated 2024-08-16 10:05:58 +0200
Last updated 2024-10-13 14:21:16 +0200
</div>
</div>
</body>
Expand Down
74 changes: 41 additions & 33 deletions guide.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -556,11 +556,8 @@ <h1>AeroSpace Guide</h1>
<li><a href="#assign-workspaces-to-monitors">6.1. Assign workspaces to monitors</a></li>
</ul>
</li>
<li><a href="#caveats">7. Caveats</a>
<ul class="sectlevel2">
<li><a href="#dialog-heuristics">7.1. Dialog heuristics</a></li>
</ul>
</li>
<li><a href="#dialog-heuristics">7. Dialog heuristics</a></li>
<li><a href="#common-pitfall-keyboard-keys-handling">8. Common pitfall: keyboard keys handling</a></li>
</ul>
</div>
</div>
Expand Down Expand Up @@ -593,6 +590,10 @@ <h1>AeroSpace Guide</h1>
</div>
</div>
</div>
<div class="paragraph">
<p>This Guide is designed to be read from top to bottom as a whole.
You can skip parts that are obvious.</p>
</div>
</div>
</div>
<div class="sect1">
Expand All @@ -613,16 +614,13 @@ <h3 id="homebrew-installation"><a class="anchor" href="#homebrew-installation"><
AeroSpace provides bash, fish and zsh completions.</p>
</div>
<div class="paragraph">
<p>You can also install specific previous versions:</p>
<p>You can also install specific previous <a href="https://github.com/nikitabobko/homebrew-tap/tree/main/Casks">pinned homebrew Casks versions</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight nowrap"><code data-lang="bash"><span></span>brew<span class="tok-w"> </span>install<span class="tok-w"> </span>--cask<span class="tok-w"> </span>nikitabobko/tap/[email protected]</code></pre>
</div>
</div>
<div class="paragraph">
<p>For the list of all the versions available for installation via brew see: <a href="https://github.com/nikitabobko/homebrew-tap/tree/main/Casks" class="bare">https://github.com/nikitabobko/homebrew-tap/tree/main/Casks</a></p>
</div>
</div>
<div class="sect2">
<h3 id="manual-installation"><a class="anchor" href="#manual-installation"></a><a class="link" href="#manual-installation">1.2. Manual installation</a></h3>
Expand Down Expand Up @@ -799,17 +797,23 @@ <h3 id="default-config"><a class="anchor" href="#default-config"></a><a class="l
<span class="tok-c1"># tall monitor (anything higher than wide) gets vertical orientation</span>
<span class="tok-n">default-root-container-orientation</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;auto&#39;</span>

<span class="tok-c1"># Possible values: (qwerty|dvorak)</span>
<span class="tok-c1"># See <a href="https://nikitabobko.github.io/AeroSpace/guide#key-mapping" class="bare">https://nikitabobko.github.io/AeroSpace/guide#key-mapping</a></span>
<span class="tok-n">key-mapping</span><span class="tok-p">.</span><span class="tok-n">preset</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;qwerty&#39;</span>

<span class="tok-c1"># Mouse follows focus when focused monitor changes</span>
<span class="tok-c1"># Drop it from your config, if you don&#39;t like this behavior</span>
<span class="tok-c1"># See <a href="https://nikitabobko.github.io/AeroSpace/guide#on-focus-changed-callbacks" class="bare">https://nikitabobko.github.io/AeroSpace/guide#on-focus-changed-callbacks</a></span>
<span class="tok-c1"># See <a href="https://nikitabobko.github.io/AeroSpace/commands#move-mouse" class="bare">https://nikitabobko.github.io/AeroSpace/commands#move-mouse</a></span>
<span class="tok-c1"># Fallback value (if you omit the key): on-focused-monitor-changed = []</span>
<span class="tok-n">on-focused-monitor-changed</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-p">[</span><span class="tok-s1">&#39;move-mouse monitor-lazy-center&#39;</span><span class="tok-p">]</span>

<span class="tok-c1"># You can effectively turn off macOS &quot;Hide application&quot; (cmd-h) feature by toggling this flag</span>
<span class="tok-c1"># Useful if you don&#39;t use this macOS feature, but accidentally hit cmd-h or cmd-alt-h key</span>
<span class="tok-c1"># Also see: <a href="https://nikitabobko.github.io/AeroSpace/goodness#disable-hide-app" class="bare">https://nikitabobko.github.io/AeroSpace/goodness#disable-hide-app</a></span>
<span class="tok-n">automatically-unhide-macos-hidden-apps</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-kc">false</span>

<span class="tok-c1"># Possible values: (qwerty|dvorak)</span>
<span class="tok-c1"># See <a href="https://nikitabobko.github.io/AeroSpace/guide#key-mapping" class="bare">https://nikitabobko.github.io/AeroSpace/guide#key-mapping</a></span>
<span class="tok-k">[key-mapping]</span>
<span class="tok-n">preset</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;qwerty&#39;</span>

<span class="tok-c1"># Gaps between windows (inner-*) and between monitor edges (outer-*).</span>
<span class="tok-c1"># Possible values:</span>
<span class="tok-c1"># - Constant: gaps.outer.top = 8</span>
Expand Down Expand Up @@ -1044,7 +1048,7 @@ <h3 id="key-mapping"><a class="anchor" href="#key-mapping"></a><a class="link" h
<span class="tok-n">unicorn</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;u&#39;</span>

<span class="tok-k">[mode.main.binding]</span>
<span class="tok-n">alt-unicorn</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;workspace unicorn&#39;</span><span class="tok-w"> </span><span class="tok-c1"># (⁀ᗢ⁀)</span></code></pre>
<span class="tok-n">alt-unicorn</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;workspace wonderland&#39;</span><span class="tok-w"> </span><span class="tok-c1"># (⁀ᗢ⁀)</span></code></pre>
</div>
</div>
<div class="ulist">
Expand All @@ -1053,7 +1057,8 @@ <h3 id="key-mapping"><a class="anchor" href="#key-mapping"></a><a class="link" h
<p>For <code>dvorak</code> users, AeroSpace offers a preconfigured preset.</p>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight nowrap"><code data-lang="toml"><span></span><span class="tok-n">key-mapping</span><span class="tok-p">.</span><span class="tok-n">preset</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;dvorak&#39;</span></code></pre>
<pre class="pygments highlight nowrap"><code data-lang="toml"><span></span><span class="tok-k">[key-mapping]</span>
<span class="tok-n">preset</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;dvorak&#39;</span></code></pre>
</div>
</div>
</li>
Expand Down Expand Up @@ -1192,7 +1197,7 @@ <h2 id="tree"><a class="anchor" href="#tree"></a><a class="link" href="#tree">3.
<p><a href="commands#join-with">join-with</a></p>
</li>
<li>
<p><a href="commands#split">split</a></p>
<p><a href="commands#split">split</a> (it&#8217;s for compatibility with i3. Please prefer <code>join-with</code> over <code>split</code>)</p>
</li>
</ol>
</div>
Expand Down Expand Up @@ -1324,17 +1329,18 @@ <h3 id="normalization"><a class="anchor" href="#normalization"></a><a class="lin
</div>
</div>
<div class="paragraph">
<p>Normalizations make it easier to understand the tree structure by looking at how windows are placed on the screen.</p>
</div>
<div class="paragraph">
<p>You can disable normalizations by placing these lines to your config:</p>
<p>Normalizations make it easier to understand the tree structure by looking at how windows are placed on the screen.
Though you can disable normalizations by placing these lines to your config:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight nowrap"><code data-lang="toml"><span></span><span class="tok-n">enable-normalization-flatten-containers</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-kc">false</span>
<span class="tok-n">enable-normalization-opposite-orientation-for-nested-containers</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-kc">false</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Unless you&#8217;re hardcore i3 user who knows what they are doing, it&#8217;s recommended to keep the normalizations enabled.</p>
</div>
</div>
<div class="sect2">
<h3 id="floating-windows"><a class="anchor" href="#floating-windows"></a><a class="link" href="#floating-windows">3.3. Floating windows</a></h3>
Expand Down Expand Up @@ -1408,7 +1414,7 @@ <h2 id="emulation-of-virtual-workspaces"><a class="anchor" href="#emulation-of-v
That means, that if AeroSpace crashes badly you will still be able to manually "unhide" the windows by dragging these few pixels to the center of the screen.</p>
</div>
<div class="paragraph">
<p>If you want to minimize the visibility of hidden windows, it&#8217;s recommended to place Dock in the bottom (and additionaly turn automatic hiding)</p>
<p>If you want to minimize the visibility of hidden windows, it&#8217;s recommended to place Dock in the bottom (and additionally turn automatic hiding)</p>
</div>
</td>
</tr>
Expand Down Expand Up @@ -1514,7 +1520,7 @@ <h3 id="a-note-on-displays-have-separate-spaces"><a class="anchor" href="#a-note
<td class="tableblock halign-left valign-top"><p class="tableblock">👍 Yes</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Overal stability and performance</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Overall stability and performance</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">❌ Weird focus and performance issues may happen (see the list above)</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">👍 Public Apple API are more stable (which in turn affects AeroSpace stability)</p></td>
</tr>
Expand Down Expand Up @@ -1903,10 +1909,8 @@ <h3 id="assign-workspaces-to-monitors"><a class="anchor" href="#assign-workspace
</div>
</div>
<div class="sect1">
<h2 id="caveats"><a class="anchor" href="#caveats"></a><a class="link" href="#caveats">7. Caveats</a></h2>
<h2 id="dialog-heuristics"><a class="anchor" href="#dialog-heuristics"></a><a class="link" href="#dialog-heuristics">7. Dialog heuristics</a></h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="dialog-heuristics"><a class="anchor" href="#dialog-heuristics"></a><a class="link" href="#dialog-heuristics">7.1. Dialog heuristics</a></h3>
<div class="ulist">
<ul>
<li>
Expand All @@ -1931,11 +1935,8 @@ <h3 id="dialog-heuristics"><a class="anchor" href="#dialog-heuristics"></a><a cl
<p>Windows that are recognized as dialogs are floated by default.</p>
</div>
<div class="paragraph">
<p>It&#8217;s not possible to disable the heuristics, because the goal is to make the heuristics so good that there won&#8217;t problems with them.
If you find that some windows are not handled properly please <a href="https://github.com/nikitabobko/AeroSpace/issues/new">report an issue</a></p>
</div>
<div class="paragraph">
<p>Anyway, your alternatives are:</p>
<p>If you find that some windows are not handled properly please <a href="https://github.com/nikitabobko/AeroSpace/issues/new">report an issue</a> (don&#8217;t forget to attach <a href="./commands#debug-windows">debug-windows output</a>).
You can also use <code>on-window-detected</code> to force tile or force float all windows of a particular application:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
Expand All @@ -1944,7 +1945,7 @@ <h3 id="dialog-heuristics"><a class="anchor" href="#dialog-heuristics"></a><a cl
<div class="listingblock">
<div class="content">
<pre class="pygments highlight nowrap"><code data-lang="toml"><span></span><span class="tok-k">[[on-window-detected]]</span>
<span class="tok-n">check-further-callbacks</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-kc">true</span>
<span class="tok-n">if</span><span class="tok-p">.</span><span class="tok-n">app-id</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;...&#39;</span>
<span class="tok-n">run</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;layout tiling&#39;</span></code></pre>
</div>
</div>
Expand All @@ -1954,7 +1955,7 @@ <h3 id="dialog-heuristics"><a class="anchor" href="#dialog-heuristics"></a><a cl
<div class="listingblock">
<div class="content">
<pre class="pygments highlight nowrap"><code data-lang="toml"><span></span><span class="tok-k">[[on-window-detected]]</span>
<span class="tok-n">check-further-callbacks</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-kc">true</span>
<span class="tok-n">if</span><span class="tok-p">.</span><span class="tok-n">app-id</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;...&#39;</span>
<span class="tok-n">run</span><span class="tok-w"> </span><span class="tok-o">=</span><span class="tok-w"> </span><span class="tok-s1">&#39;layout floating&#39;</span></code></pre>
</div>
</div>
Expand All @@ -1963,11 +1964,18 @@ <h3 id="dialog-heuristics"><a class="anchor" href="#dialog-heuristics"></a><a cl
</div>
</div>
</div>
<div class="sect1">
<h2 id="common-pitfall-keyboard-keys-handling"><a class="anchor" href="#common-pitfall-keyboard-keys-handling"></a><a class="link" href="#common-pitfall-keyboard-keys-handling">8. Common pitfall: keyboard keys handling</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>If you can&#8217;t make AeroSpace handle some keys in your config, please make sure that you don&#8217;t have keys conflict with other software that might listen to global keys (e.g. skhd, Karabiner-Elements, Raycast)</p>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2024-08-16 10:05:58 +0200
Last updated 2024-10-13 14:21:16 +0200
</div>
</div>
</body>
Expand Down
2 changes: 1 addition & 1 deletion util/man-footer.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Bugs can be reported to https://github.com/nikitabobko/AeroSpace/issues/new

Copyright (C) 2023 Nikita Bobko +
Free use of this software is granted under the terms of the MIT License +
You can find the full text of AeroSpace license and its dependencies licenses in the 'license' directory of the distributed zip archieve.
You can find the full text of AeroSpace license and its dependencies in the 'legal' directory of the distributed zip archieve.

== AUTHOR

Expand Down
1 change: 1 addition & 0 deletions util/window-id-flag-desc.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Act on the specified window instead of the focused window
1 change: 1 addition & 0 deletions util/workspace-flag-desc.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Act on the specified workspace instead of the focused workspace
3 changes: 2 additions & 1 deletion version.html
View file
Original file line number Diff line number Diff line change
@@ -1 +1,2 @@
2bcb82065bfe1c49f83bdd8dd423a69669b27252
e3936aac3b39f7fd242d89ebbda7f6691f5bbdf8
git working directory is dirty

0 comments on commit 817287e

Please sign in to comment.