Tree branch: Migrating ====================== Michael Stapelberg November 2010 == Introduction The tree branch (referring to a branch of i3 in the git repository) is the new version of i3. Due to the very deep changes and heavy refactoring of the source source, we decided to develop it in a separate branch (instead of using the next/master-branch system like before). == Current status Currently, the code is mostly working. Some of the i3 core developers have been using the tree branch version for a few weeks now. So, if you are eager to try out the new features and help us find bugs, give it a try! At the same time, a word of warning is appropriate: This version of i3 might crash unexpectedly, so please be careful with important data (do not work for two days without saving…). == Getting the latest tree branch version Check out the latest version: --------------------------------------------- $ git clone -b tree git://code.stapelberg.de/i3 --------------------------------------------- Then build and install it (has the same dependencies as the latest stable i3 version): ----------------------------- $ cd i3 $ make $ sudo cp i3 /usr/bin/i3-tree ----------------------------- …and execute +i3-tree+ instead of +i3+ in your Xsession. *IMPORTANT:* Please note that configuration file compatibility is not yet done. So, make sure you use/customize the provided +i3.config+ file. == Tree The most important change and reason for the name is that i3 stores all information about the X11 outputs, workspaces and layout of the windows on them in a tree. The root node is the X11 root window, followed by the X11 outputs, then workspaces and finally the windows themselve. In previous versions of i3 we had multiple lists (of outputs, workspaces) and a table for each workspace. That approach turned out to be complicated to use (snapping), understand and implement. === The tree consists of Containers The building blocks of our tree are so called +Containers+. A +Container+ can host a window (meaning an X11 window, one that you can actually see and use, like a browser). Alternatively, it could contain one or more +Containers+. A simple example is the workspace: When you start i3 with a single monitor, a single workspace and you open two terminal windows, you will end up with a tree like this: image::tree-layout2.png["layout2",float="right"] image::tree-shot4.png["shot4",title="Two terminals on standard workspace"] === Orientation and Split Containers [[OrientationSplit]] It is only natural to use so-called +Split Containers+ in order to build a layout when using a tree as data structure. In i3, every +Container+ has an orientation (horizontal, vertical or unspecified). So, in our example with the workspace, the default orientation of the workspace +Container+ is horizontal (most monitors are widescreen nowadays). If you change the orientation to vertical (+Alt+v+ in the default config) and *then* open two terminals, i3 will configure your windows like this: image::tree-shot2.png["shot2",title="Vertical Workspace Orientation"] An interesting new feature of the tree branch is the ability to split anything: Let’s assume you have two terminals on a workspace (with horizontal orientation), focus is on the right terminal. Now you want to open another terminal window below the current one. If you would just open a new terminal window, it would show up to the right due to the horizontal workspace orientation. Instead, press +Alt+v+ to create a +Vertical Split Container+ (to open a +Horizontal Split Container+, use +Alt+h+). Now you can open a new terminal and it will open below the current one: image::tree-layout1.png["Layout",float="right"] image::tree-shot1.png["shot",title="Vertical Split Container"] unfloat::[] You probably guessed it already: There is no limit on how deep your hierarchy of splits can be. === Level up Let’s stay with our example from above. We have a terminal on the left and two vertically split terminals on the right, focus is on the bottom right one. When you open a new terminal, it will open below the current one. So, how can you open a new terminal window to the *right* of the current one? The solution is to use +level up+, which will focus the +Parent Container+ of the current +Container+. In this case, you would focus the +Vertical Split Container+ which is *inside* the horizontally oriented workspace. Thus, now new windows will be opened to the right of the +Vertical Split Container+: image::tree-shot3.png["shot3",title="Level Up, then open new terminal"] == Commands The authoritive reference for commands is +src/cmdparse.y+. You can also find most commands in +i3.config+. Here comes a short overview over the important commands: === Manipulating layout ------------------------------- layout ------------------------------- === Changing Focus -------------------------- next prev -------------------------- .Examples: ------------------------- bindsym Mod1+Left prev h bindsym Mod1+Right next h bindsym Mod1+Down next v bindsym Mod1+Up prev v ------------------------- === Moving ----------------------------------------- move ----------------------------------------- .Examples: ----------------------------------------- bindsym Mod1+Shift+Left move before h bindsym Mod1+Shift+Right move after h bindsym Mod1+Shift+Down move before v bindsym Mod1+Shift+Up move after v ----------------------------------------- === Changing workspace --------------------------- workspace --------------------------- .Examples: --------------------------- bindsym Mod1+1 workspace 1 bindsym Mod1+2 workspace 2 … --------------------------- === Moving Containers to workspaces --------------------- move workspace --------------------- ------------------------------------- bindsym Mod1+Shift+1 move workspace 1 bindsym Mod1+Shift+2 move workspace 2 … ------------------------------------- === Changing border style --------------------------- border --------------------------- === Changing container mode ----------------------------- mode ----------------------------- == The rest What is not mentioned here explicitly is either unchanged and can be read in the http://i3.zekjur.net/docs/userguide.html[i3 User’s Guide] or it is not yet implemented.