i3(1)
=====
-Michael Stapelberg <michael+i3@stapelberg.de>
-v3.epsilon, March 2010
+Michael Stapelberg <michael@i3wm.org>
+v4.3, September 2012
== NAME
== SYNOPSIS
-i3 [-a] [-c configfile] [-C] [-d <loglevel>] [-v] [-V]
+i3 [-a] [-c configfile] [-C] [-d all] [-v] [-V]
== OPTIONS
-C::
Check the configuration file for validity and exit.
--d::
-Specifies the debug loglevel. To see the most output, use -d all.
+-d all::
+Enables debug logging.
+The 'all' parameter is present for historical reasons.
-v::
Display version number (and date of the last commit).
-V::
Be verbose.
+--force-xinerama::
+Use Xinerama instead of RandR. This option should only be used if you are stuck
+with the old nVidia closed source driver (older than 302.17) which does not
+support RandR.
+
+--get-socketpath::
+Retrieve the i3 IPC socket path from X11, print it, then exit.
+
+--shmlog-size <limit>::
+Limits the size of the i3 SHM log to <limit> bytes. Setting this to 0 disables
+SHM logging entirely. The default is 0 bytes.
+
== DESCRIPTION
=== INTRODUCTION
=== IMPORTANT NOTE TO nVidia BINARY DRIVER USERS
If you are using the nVidia binary graphics driver (also known as 'blob')
-you need to use the +--force-xinerama+ flag (in your .xsession) when starting
-i3, like so:
+before version 302.17, you need to use the +--force-xinerama+ flag (in your
+~/.xsession) when starting i3, like so:
----------------------------------------------
exec i3 --force-xinerama -V >>~/.i3/i3log 2>&1
=== TERMINOLOGY
-Client::
-A client is X11-speak for a window.
+Tree::
+i3 keeps your layout in a tree data structure.
-Table::
-Your workspace is managed using a table. You can move windows around and create
-new columns (move a client to the right) or rows (move it to the bottom)
-implicitly.
-+
-By "snapping" a client in a specific direction, you increase its colspan/rowspan.
+Window::
+An X11 window, like the Firefox browser window or a terminal emulator.
-Container::
-A container contains a variable number of clients. Each cell of the table is a
-container.
+Floating Window::
+A window which "floats" on top of other windows. This style is used by i3 to
+display X11 windows with type "dialog", such as the "Print" or "Open File"
+dialog boxes in many GUI applications. Use of floating windows can be
+fine-tuned with the for_window command (see HTML userguide).
+
+Split container::
+A split container contains multiple other split containers or windows.
+
-Containers can be used in various modes. The default mode is called "default"
+Containers can be used in various layouts. The default mode is called "default"
and just resizes each client equally so that it fits.
Workspace::
-A workspace is a set of clients (technically speaking, it’s just a table).
-Other window managers call this "Virtual Desktops".
+A workspace is a set of containers. Other window managers call this "Virtual
+Desktops".
+
In i3, each workspace is assigned to a specific virtual screen. By default,
screen 1 has workspace 1, screen 2 has workspace 2 and so on… However, when you
Here is a short overview of the default keybindings:
+Mod1+Enter::
+Open a new terminal emulator window.
+
+Mod1+d::
+Open dmenu for starting any application by typing (part of) its name.
+
j/k/l/;::
Direction keys (left, down, up, right). They are on your homerow (see the mark
on your "j" key). Alternatively, you can use the cursor keys.
Mod1+<direction>::
Focus window in <direction>.
-Mod3+<direction>::
-Focus container in <direction>.
-
Mod1+Shift+<direction>::
Move window to <direction>.
-Mod3+Shift+<direction>::
-Move container to <direction>.
-
-Mod1+Control+<direction>::
-Snap container to <direction>.
-
Mod1+<number>::
Switch to workspace <number>.
Mod1+f::
Toggle fullscreen mode.
-Mod1+h::
+Mod1+s::
Enable stacking layout for the current container.
Mod1+e::
Enable default layout for the current container.
+Mod1+w::
+Enable tabbed layout for the current container.
+
Mod1+Shift+Space::
-Toggle tiling/floating for the current window.
+Toggle tiling/floating for the current container.
-Mod1+t::
-Select the first tiling window if the current window is floating and vice-versa.
+Mod1+Space::
+Select the first tiling container if the current container is floating and
+vice-versa.
Mod1+Shift+q::
Kills the current window. This is equivalent to "clicking on the close button",
happens.
Mod1+Shift+r::
-Restarts i3 in place (without losing any windows, but at this time, the layout
-and placement of windows is not retained).
+Restarts i3 in place. Your layout will be preserved.
Mod1+Shift+e::
Exits i3.
When starting, i3 looks for configuration files in the following order:
1. ~/.config/i3/config (or $XDG_CONFIG_HOME/i3/config if set)
-2. /etc/xdg/i3/config (or $XDG_CONFIG_DIRS/i3/config if set)
-3. ~/.i3/config
+2. ~/.i3/config
+3. /etc/xdg/i3/config (or $XDG_CONFIG_DIRS/i3/config if set)
4. /etc/i3/config
You can specify a custom path using the -c option.
.Sample configuration
-------------------------------------------------------------
-font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1
-
-# Start terminal (Mod1+Enter)
-bindcode Mod1+36 exec /usr/bin/urxvt
-
-# Start dmenu (Mod1+v)
-bindcode Mod1+55 exec /usr/bin/dmenu_run
-
-# Kill current client (Mod1+Shift+q)
-bindcode Mod1+Shift+24 kill
-
-# Beamer on/off
-bindcode Mod1+73 exec /home/michael/toggle_beamer.sh
-
-# Screen locking
-bindcode Mod1+68 exec /usr/bin/i3lock
-
-# Restart i3 inplace (Mod1+Shift+r)
-bindcode Mod1+Shift+27 restart
-
-# Exit i3 (Mod1+Shift+e)
-bindcode Mod1+Shift+26 exit
-
-# Brightness
-bindcode Mod1+97 exec sudo sh -c "echo up > /proc/acpi/ibm/brightness"
-bindcode Mod1+103 exec sudo sh -c "echo down > /proc/acpi/ibm/brightness"
-
-# Fullscreen (Mod1+f)
-bindcode Mod1+41 f
-
-# Stacking (Mod1+h)
-bindcode Mod1+43 s
-
-# Default (Mod1+e)
-bindcode Mod1+26 d
-
-# Toggle tiling/floating of the current window (Mod1+Shift+Space)
-bindcode Mod1+Shift+65 t
-
-# Go into the tiling layer / floating layer, depending on whether
-# the current window is tiling / floating (Mod1+t)
-bindcode Mod1+28 focus ft
-
-# Focus (Mod1+j/k/l/;)
-bindcode Mod1+44 h
-bindcode Mod1+45 j
-bindcode Mod1+46 k
-bindcode Mod1+47 l
-
-# Focus Container (Mod3+j/k/l/;)
-bindcode Mod3+44 wch
-bindcode Mod3+45 wcj
-bindcode Mod3+46 wck
-bindcode Mod3+47 wcl
-
-# Snap (Mod1+Control+j/k/l/;)
-bindcode Mod1+Control+44 sh
-bindcode Mod1+Control+45 sj
-bindcode Mod1+Control+46 sk
-bindcode Mod1+Control+47 sl
-
-# Move (Mod1+Shift+j/k/l/;)
-bindcode Mod1+Shift+44 mh
-bindcode Mod1+Shift+45 mj
-bindcode Mod1+Shift+46 mk
-bindcode Mod1+Shift+47 ml
-
-# Move Container (Mod3+Shift+j/k/l/;)
-bindcode Mod3+Shift+44 wcmh
-bindcode Mod3+Shift+45 wcmj
-bindcode Mod3+Shift+46 wcmk
-bindcode Mod3+Shift+47 wcml
-
-# Workspaces
-bindcode Mod1+10 1
-bindcode Mod1+11 2
-...
-
-# Move to Workspace
-bindcode Mod1+Shift+10 1
-bindcode Mod1+Shift+11 2
-...
+# i3 config file (v4)
+
+# Font for window titles. Will also be used by the bar unless a different font
+# is used in the bar {} block below.
+# This font is widely installed, provides lots of unicode glyphs, right-to-left
+# text rendering and scalability on retina/hidpi displays (thanks to pango).
+font pango:DejaVu Sans Mono 8
+# Before i3 v4.8, we used to recommend this one as the default:
+# font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1
+# The font above is very space-efficient, that is, it looks good, sharp and
+# clear in small sizes. However, its unicode glyph coverage is limited, the old
+# X core fonts rendering does not support right-to-left and this being a bitmap
+# font, it doesn’t scale on retina/hidpi displays.
+
+# use Mouse+Mod1 to drag floating windows to their wanted position
+floating_modifier Mod1
+
+# start a terminal
+bindsym Mod1+Return exec /usr/bin/urxvt
+
+# kill focused window
+bindsym Mod1+Shift+q kill
+
+# start dmenu (a program launcher)
+bindsym Mod1+d exec /usr/bin/dmenu_run
+
+# change focus
+bindsym Mod1+j focus left
+bindsym Mod1+k focus down
+bindsym Mod1+l focus up
+bindsym Mod1+semicolon focus right
+
+# alternatively, you can use the cursor keys:
+bindsym Mod1+Left focus left
+bindsym Mod1+Down focus down
+bindsym Mod1+Up focus up
+bindsym Mod1+Right focus right
+
+# move focused window
+bindsym Mod1+Shift+j move left
+bindsym Mod1+Shift+k move down
+bindsym Mod1+Shift+l move up
+bindsym Mod1+Shift+semicolon move right
+
+# alternatively, you can use the cursor keys:
+bindsym Mod1+Shift+Left move left
+bindsym Mod1+Shift+Down move down
+bindsym Mod1+Shift+Up move up
+bindsym Mod1+Shift+Right move right
+
+# split in horizontal orientation
+bindsym Mod1+h split h
+
+# split in vertical orientation
+bindsym Mod1+v split v
+
+# enter fullscreen mode for the focused container
+bindsym Mod1+f fullscreen toggle
+
+# change container layout (stacked, tabbed, default)
+bindsym Mod1+s layout stacking
+bindsym Mod1+w layout tabbed
+bindsym Mod1+e layout default
+
+# toggle tiling / floating
+bindsym Mod1+Shift+space floating toggle
+
+# change focus between tiling / floating windows
+bindsym Mod1+space focus mode_toggle
+
+# focus the parent container
+bindsym Mod1+a focus parent
+
+# focus the child container
+#bindsym Mod1+d focus child
+
+# switch to workspace
+bindsym Mod1+1 workspace 1
+bindsym Mod1+2 workspace 2
+# ..
+
+# move focused container to workspace
+bindsym Mod1+Shift+1 move workspace 1
+bindsym Mod1+Shift+2 move workspace 2
+# ...
+
+# reload the configuration file
+bindsym Mod1+Shift+c reload
+# restart i3 inplace (preserves your layout/session, can be used to upgrade i3)
+bindsym Mod1+Shift+r restart
+# exit i3 (logs you out of your X session)
+bindsym Mod1+Shift+e exit
+
+# display workspace buttons plus a statusline generated by i3status
+bar {
+ status_command i3status
+}
-------------------------------------------------------------
=== ~/.xsession
.Sample xsession
-------------------------------------------------------------
# Disable DPMS turning off the screen
-xset dpms force on
+xset -dpms
xset s off
# Disable bell
# Enable zapping (C-A-<Bksp> kills X)
setxkbmap -option terminate:ctrl_alt_bksp
-# Enforce correct locales from the beginning
-unset LC_COLLATE
-export LC_CTYPE=de_DE.UTF-8
-export LC_TIME=de_DE.UTF-8
-export LC_NUMERIC=de_DE.UTF-8
-export LC_MONETARY=de_DE.UTF-8
+# Enforce correct locales from the beginning:
+# LC_ALL is unset since it overwrites everything
+# LANG=de_DE.UTF-8 is used, except for:
+# LC_MESSAGES=C never translates program output
+# LC_TIME=en_DK leads to yyyy-mm-dd hh:mm date/time output
+unset LC_ALL
+export LANG=de_DE.UTF-8
export LC_MESSAGES=C
-export LC_PAPER=de_DE.UTF-8
-export LC_NAME=de_DE.UTF-8
-export LC_ADDRESS=de_DE.UTF-8
-export LC_TELEPHONE=de_DE.UTF-8
-export LC_MEASUREMENT=de_DE.UTF-8
-export LC_IDENTIFICATION=de_DE.UTF-8
+export LC_TIME=en_DK.UTF-8
# Use XToolkit in java applications
export AWT_TOOLKIT=XToolkit
=== I3SOCK
-If no ipc-socket is specified in the configfile, this variable is used
-to determine the path, at wich the unix domain socket is created, on which
-i3 listenes to incoming connections.
+This variable overwrites the IPC socket path (placed in
+/tmp/i3-%u.XXXXXX/ipc-socket.%p by default, where %u is replaced with your UNIX
+username, %p is replaced with i3’s PID and XXXXXX is a string of random
+characters from the portable filename character set (see mkdtemp(3))). The IPC
+socket is used by external programs like i3-msg(1) or i3bar(1).
== TODO
and the "how to hack" guide. If you are building from source, run:
+make -C docs+
-You can also access these documents online at http://i3.zekjur.net/
+You can also access these documents online at https://i3wm.org/
-i3-input(1), i3-msg(1), i3-wsbar(1)
+i3-input(1), i3-msg(1), i3bar(1), i3-nagbar(1), i3-config-wizard(1),
+i3-migrate-config-to-v4(1)
== AUTHOR
projects / i3 / i3 / blobdiff