git.sur5r.net Git - i3/i3.github.io/blob - _docs/tree-migrating

   1 Tree branch: Migrating
   2 ======================
   3 Michael Stapelberg <michael+i3@stapelberg.de>
   4 November 2010
   5
   6 == Introduction
   7
   8 The tree branch (referring to a branch of i3 in the git repository) is the new
   9 version of i3. Due to the very deep changes and heavy refactoring of the source
  10 source, we decided to develop it in a seperate branch (instead of using the
  11 next/master-branch system like before).
  12
  13 == Current status
  14
  15 Currently, the code is mostly working. Some of the i3 core developers have been
  16 using the tree branch version for a few weeks now. So, if you are eager to try
  17 out the new features and help us find bugs, give it a try!
  18
  19 At the same time, a word of warning is appropriate: This version of i3 might
  20 crash unexpectedly, so please be careful with important data (do not work for
  21 two days without saving…).
  22
  23 == Getting the latest tree branch version
  24
  25 Check out the latest version:
  26 ---------------------------------------------
  27 $ git clone -b tree git://code.stapelberg.de/i3
  28 ---------------------------------------------
  29
  30 Then build and install it (has the same dependencies as the latest stable i3
  31 version):
  32 -----------------------------
  33 $ cd i3
  34 $ make
  35 $ sudo cp i3 /usr/bin/i3-tree
  36 -----------------------------
  37
  38 …and execute +i3-tree+ instead of +i3+ in your Xsession.
  39
  40 *IMPORTANT:* Please note that configuration file compatibility is not yet done.
  41 So, make sure you use/customize the provided +i3.config+ file.
  42
  43 == Tree
  44
  45 The most important change and reason for the name is that i3 stores all
  46 information about the X11 outputs, workspaces and layout of the windows on them
  47 in a tree. The root node is the X11 root window, followed by the X11 outputs,
  48 then workspaces and finally the windows themselve. In previous versions of i3
  49 we had multiple lists (of outputs, workspaces) and a table for each workspace.
  50 That approach turned out to be complicated to use (snapping), understand and
  51 implement.
  52
  53 === The tree consists of Containers
  54
  55 The building blocks of our tree are so called +Containers+. A +Container+ can
  56 host a window (meaning an X11 window, one that you can actually see and use,
  57 like a browser). Alternatively, it could contain one or more +Containers+. A
  58 simple example is the workspace: When you start i3 with a single monitor, a
  59 single workspace and you open two terminal windows, you will end up with a tree
  60 like this:
  61
  62 image::tree-layout2.png["layout2",float="right"]
  63 image::tree-shot4.png["shot4",title="Two terminals on standard workspace"]
  64
  65 === Orientation and Split Containers
  66
  67 [[OrientationSplit]]
  68
  69 It is only natural to use so-called +Split Containers+ in order to build a
  70 layout when using a tree as data structure. In i3, every +Container+ has an
  71 orientation (horizontal, vertical or unspecified). So, in our example with the
  72 workspace, the default orientation of the workspace +Container+ is horizontal
  73 (most monitors are widescreen nowadays). If you change the orientation to
  74 vertical (+Alt+v+ in the default config) and *then* open two terminals, i3 will
  75 configure your windows like this:
  76
  77 image::tree-shot2.png["shot2",title="Vertical Workspace Orientation"]
  78
  79 An interesting new feature of the tree branch is the ability to split anything:
  80 Let’s assume you have two terminals on a workspace (with horizontal
  81 orientation), focus is on the right terminal. Now you want to open another
  82 terminal window below the current one. If you would just open a new terminal
  83 window, it would show up to the right due to the horizontal workspace
  84 orientation. Instead, press +Alt+v+ to create a +Vertical Split Container+ (to
  85 open a +Horizontal Split Container+, use +Alt+h+). Now you can open a new
  86 terminal and it will open below the current one:
  87
  88 image::tree-layout1.png["Layout",float="right"]
  89 image::tree-shot1.png["shot",title="Vertical Split Container"]
  90
  91 unfloat::[]
  92
  93 You probably guessed it already: There is no limit on how deep your hierarchy
  94 of splits can be.
  95
  96 === Level up
  97
  98 Let’s stay with our example from above. We have a terminal on the left and two
  99 vertically split terminals on the right, focus is on the bottom right one. When
 100 you open a new terminal, it will open below the current one.
 101
 102 So, how can you open a new terminal window to the *right* of the current one?
 103 The solution is to use +level up+, which will focus the +Parent Container+ of
 104 the current +Container+. In this case, you would focus the +Vertical Split
 105 Container+ which is *inside* the horizontally oriented workspace. Thus, now new
 106 windows will be opened to the right of the +Vertical Split Container+:
 107
 108 image::tree-shot3.png["shot3",title="Level Up, then open new terminal"]
 109
 110 == Commands
 111
 112 The authoritive reference for commands is +src/cmdparse.y+. You can also find
 113 most commands in +i3.config+. Here comes a short overview over the important
 114 commands:
 115
 116 === Manipulating layout
 117
 118 -------------------------------
 119 layout <default|stacked|tabbed>
 120 -------------------------------
 121
 122 === Changing Focus
 123
 124 --------------------------
 125 next <horizontal|vertical>
 126 prev <horizontal|vertical>
 127 --------------------------
 128
 129 .Examples:
 130 -------------------------
 131 bindsym Mod1+Left prev h
 132 bindsym Mod1+Right next h
 133 bindsym Mod1+Down next v
 134 bindsym Mod1+Up prev v
 135 -------------------------
 136
 137 === Moving
 138
 139 -----------------------------------------
 140 move <before|after> <horizontal|vertical>
 141 -----------------------------------------
 142
 143 .Examples:
 144 -----------------------------------------
 145 bindsym Mod1+Shift+Left move before h
 146 bindsym Mod1+Shift+Right move after h
 147 bindsym Mod1+Shift+Down move before v
 148 bindsym Mod1+Shift+Up move after v
 149 -----------------------------------------
 150
 151 === Changing workspace
 152
 153 ---------------------------
 154 workspace <name>
 155 ---------------------------
 156
 157 .Examples:
 158 ---------------------------
 159 bindsym Mod1+1 workspace 1
 160 bindsym Mod1+2 workspace 2
 161 …
 162 ---------------------------
 163
 164 === Moving Containers to workspaces
 165
 166 ---------------------
 167 move workspace <name>
 168 ---------------------
 169
 170 -------------------------------------
 171 bindsym Mod1+Shift+1 move workspace 1
 172 bindsym Mod1+Shift+2 move workspace 2
 173 …
 174 -------------------------------------
 175
 176 === Changing border style
 177
 178 ---------------------------
 179 border <normal|none|1pixel>
 180 ---------------------------
 181
 182 === Changing container mode
 183
 184 -----------------------------
 185 mode <tiling|floating|toggle>
 186 -----------------------------
 187
 188 == The rest
 189
 190 What is not mentioned here explicitly is either unchanged and can be read in
 191 the http://i3.zekjur.net/docs/userguide.html[i3 User’s Guide] or it is not yet
 192 implemented.