i3 User’s Guide
===============
Michael Stapelberg <michael+i3@stapelberg.de>
-June 2009
+August 2009
This document contains all information you need to configuring and using the i3
window manager. If it does not, please contact me on IRC, Jabber or E-Mail and
=== Keyboard bindings
-You can use each command (see below) using keyboard bindings. At the moment,
-keyboard bindings require you to specify the keycode (38) of the key, not its key
-symbol ("a"). This has some advantages (keybindings make sense regardless of
-the layout you type) and some disadvantages (hard to remember, you have to look
-them up every time).
+A keyboard binding makes i3 execute a command (see below) upon pressing a
+specific key. i3 allows you to bind either on keycodes or on keysyms (you can
+also mix your bindings, though i3 will not protect you from overlapping ones).
+
+* A keysym (key symbol) is a description for a specific symbol, like "a" or "b",
+ but also more strange ones like "underscore" instead of "_". These are the ones
+ you also use in Xmodmap to remap your keys. To get the current mapping of your
+ keys, use +xmodmap -pke+.
+
+* Keycodes however do not need to have a symbol assigned (handy for some hotkeys
+ on some notebooks) and they will not change their meaning as you switch to a
+ different keyboard layout.
+
+My recommendation is: If you often switch keyboard layouts because you try to
+learn a different one, but you want to keep your bindings at the same place,
+use keycodes. If you don’t switch layouts and like a clean and simple config
+file, use keysyms.
*Syntax*:
---------------------------------
+----------------------------------
+bindsym [Modifiers+]keysym command
bind [Modifiers+]keycode command
---------------------------------
+----------------------------------
*Examples*:
--------------------------------
# Fullscreen
-bind Mod1+41 f
+bind Mod1+f f
# Restart
-bind Mod1+Shift+27 restart
+bind Mod1+Shift+r restart
+
+# Notebook-specific hotkeys
+bind 214 exec /home/michael/toggle_beamer.sh
--------------------------------
Available Modifiers:
*Examples*:
------------------------
set $m Mod1
-bind $m+Shift+27 restart
+bindsym $m+Shift+r restart
------------------------
Variables are directly replaced in the file when parsing, there is no fancy
actually displaying it on the screen), you’d need to have to match on Firefox
in this case.
-You can prefix or suffix workspaces with a +~+ to specify that matching clients
-should be put into floating mode. If you specify only a +~+, the client will
+You can prefix or suffix workspaces with a `~` to specify that matching clients
+should be put into floating mode. If you specify only a `~`, the client will
not be put onto any workspace, but will be set floating on the current one.
*Syntax*:
exec sudo i3status | dzen2 -dock
--------------------------------
+=== Automatically putting workspaces on specific screens
+
+If you use the assigning of clients to workspaces and start some clients
+automatically, it might be handy to put the workspaces on specific screens.
+Also, the assignment of workspaces to screens will determine the workspace
+which i3 uses for a new screen when adding screens or when starting (e.g., by
+default it will use 1 for the first screen, 2 for the second screen and so on).
+
+*Syntax*:
+----------------------------------
+workspace <number> screen <screen>
+----------------------------------
+
+Screen can be either a number (starting at 0 for the first screen) or a
+position. When using numbers, it is not guaranteed that your screens always
+get the same number. Though, unless you upgrade your X server or drivers, the
+order usually stays the same. When using positions, you have to specify the
+exact pixel where the screen *starts*, not a pixel which is contained by the
+screen. Thus, if your first screen has the dimensions 1280x800, you can match
+the second screen right of it by specifying 1280. You cannot use 1281.
+
+*Examples*:
+---------------------------
+workspace 1 screen 0
+workspace 5 screen 1
+
+workspace 1 screen 1280
+workspace 2 screen x800
+workspace 3 screen 1280x800
+---------------------------
+
+=== Named workspaces
+
+If you always have a certain arrangement of workspaces, you might want to give
+them names (of course UTF-8 is supported):
+
+*Syntax*:
+---------------------------------------
+workspace <number> <name>
+workspace <number> screen <screen> name
+---------------------------------------
+
+For more details about the screen-part of this command, see above.
+
+*Examples*:
+--------------------------
+workspace 1 www
+workspace 2 work
+workspace 3 i ♥ workspaces
+--------------------------
+
+=== Changing colors
+
+You can change all colors which i3 uses to draw the window decorations and the
+bottom bar.
+
+*Syntax*:
+--------------------------------------------
+colorclass border background text
+--------------------------------------------
+
+Where colorclass can be one of:
+
+client.focused::
+ A client which currently has the focus.
+client.focused_inactive::
+ A client which is the focused one of its container, but it does not have
+ the focus at the moment.
+client.unfocused::
+ A client which is not the focused one of its container.
+bar.focused::
+ The current workspace in the bottom bar.
+bar.unfocused::
+ All other workspaces in the bottom bar.
+
+Colors are in HTML hex format, see below.
+
+*Examples*:
+--------------------------------------
+# class border backgr. text
+client.focused #2F343A #900000 #FFFFFF
+--------------------------------------
+
+=== Interprocess communication
+
+i3 uses unix sockets to provide an IPC interface. At the moment, this interface
+is only useful for sending commands. To enable it, you have to configure a path
+where the unix socket will be stored. The default path is +/tmp/i3-ipc.sock+.
+
+*Examples*:
+----------------------------
+ipc-socket /tmp/i3-ipc.sock
+----------------------------
+
+You can then use the i3-msg command to perform any command listed in the next
+section.
+
+== List of commands
+
+=== Manipulating layout
+
+To change the layout of the current container to stacking or back to default
+layout, use +s+ or +d+. To make the current client (!) fullscreen, use +f+, to
+make it floating (or tiling again) use +t+:
+
+*Examples*:
+--------------
+bind Mod1+s s
+bind Mod1+l d
+
+# Toggle fullscreen
+bind Mod1+f f
+
+# Toggle floating/tiling
+bind Mod1+t t
+--------------
+
+=== Focussing/Moving/Snapping clients/containers/screens
+
+To change the focus, use one of the +h+, +j+, +k+ and +l+ commands, meaning
+respectively left, down, up, right. To focus a container, prefix it with +wc+,
+to focus a screen, prefix it with +ws+.
+
+The same principle applies for moving and snapping, just prefix the command
+with +m+ when moving and with +s+ when snapping:
+
+*Examples*:
+----------------------
+# Focus clients on the left, bottom, top, right:
+bindsym Mod1+j h
+bindsym Mod1+k j
+bindsym Mod1+j k
+bindsym Mod1+semicolon l
+
+# Move client to the left, bottom, top, right:
+bindsym Mod1+j mh
+bindsym Mod1+k mj
+bindsym Mod1+j mk
+bindsym Mod1+semicolon ml
+
+# Snap client to the left, bottom, top, right:
+bindsym Mod1+j sh
+bindsym Mod1+k sj
+bindsym Mod1+j sk
+bindsym Mod1+semicolon sl
+
+# Focus container on the left, bottom, top, right:
+bindsym Mod3+j wch
+…
+----------------------
+
+=== Changing workspaces/moving clients to workspaces
+
+To change to a specific workspace, the command is just the number of the
+workspace, e.g. +1+ or +3+. To move the current client to a specific workspace,
+prefix the number with an +m+.
+
+Furthermore, you can switch to the next and previous workspace with the
+commands +nw+ and +pw+, which is handy for example if you have workspace
+1, 3, 4 and 9 and you want to cycle through them with a single key combination.
+
+*Examples*:
+-------------------------
+bindsym Mod1+1 1
+bindsym Mod1+2 2
+...
+
+bindsym Mod1+Shift+1 m1
+bindsym Mod1+Shift+2 m2
+...
+
+bindsym Mod1+o nw
+bindsym Mod1+p pw
+-------------------------
+
=== Jumping to specific windows
Especially when in a multi-monitor environment, you want to quickly jump to a specific
If the current window is floating, the next tiling window will be selected
and vice-versa.
-=== Changing colors
-
-You can change all colors which i3 uses to draw the window decorations and the
-bottom bar.
-
-*Syntax*:
---------------------------------------------
-colorclass border background text
---------------------------------------------
+=== Changing border style
-Where colorclass can be one of:
+To change the border of the current client, you can use +bn+ to use the normal
+border (including window title), +bp+ to use a 1-pixel border (no window title)
+and +bb+ to make the client borderless.
-client.focused::
- A client which currently has the focus.
-client.focused_inactive::
- A client which is the focused one of its container, but it does not have
- the focus at the moment.
-client.unfocused::
- A client which is not the focused one of its container.
-bar.focused::
- The current workspace in the bottom bar.
-bar.unfocused::
- All other workspaces in the bottom bar.
-
-Colors are in HTML hex format, see below.
+*Examples*:
+------------------
+bindsym Mod1+t bn
+bindsym Mod1+y bp
+bindsym Mod1+u bb
+------------------
+
+=== Reloading/Restarting/Exiting
+
+You can make i3 reload its configuration file with +reload+. You can also
+restart i3 inplace with the +restart+ command to get it out of some weird state
+(if that should ever happen) or to perform an upgrade without having to restart
+your X session. However, your layout is not preserved at the moment, meaning
+that all open windows will be in a single container in default layout. To exit
+i3 properly, you can use the +exit+ command, however you don’t need to (e.g.,
+simply killing your X session is fine aswell).
*Examples*:
---------------------------------------
-# class border backgr. text
-client.focused #2F343A #900000 #FFFFFF
---------------------------------------
+----------------------------
+bindsym Mod1+Shift+r restart
+bindsym Mod1+Shift+w reload
+bindsym Mod1+Shift+e exit
+----------------------------
projects / i3 / i3 / commitdiff