Skip to main content

Master and Stack

When you open three windows in a tiling layout, how does SomeWM decide which one gets the big left area and which ones stack on the right?

The Two Sections​

Most tiling layouts split the screen into two sections:

SectionAlso calledRole
MasterPrimaryThe prominent area, usually larger. Holds your main focus window.
StackSecondaryThe remaining area. Holds everything else.

In the default tile layout, master is the left half and the stack is the right half. Open one window and it fills the screen. Open a second and the screen splits: first window in master, second in the stack. Open a third and it shares the stack area with the second.

Client List Order Determines Position​

The key concept: position in the client list determines which section a window lands in.

The compositor maintains a list of all clients in creation order (see Client Stacking for how this differs from visual z-order). When a layout runs, it reads this list and assigns windows to sections:

  • The first master_count clients go to the master section
  • All remaining clients go to the stack section

With the default master_count of 1, the first client in the list is master and everything else is stack.

-- Get clients in layout order (creation order, not z-order)
local clients = client.get(s)

-- clients[1]              -> master (first master_count clients)
-- clients[2], clients[3]  -> stack  (everything else)

This is why raising a window to the top of the z-order doesn't make it master. Layouts ignore z-order entirely.

Tag Properties​

These properties are set on a tag and control how layouts divide space. Change them at runtime with keybindings or set defaults in your tag configuration.

PropertyDefaultWhat it controls
master_count1Number of clients in the master section
master_width_factor0.5Proportion of screen width for master (0.0 to 1.0)
master_fill_policy"expand"What master does when the stack is empty
column_count1Number of columns in the stack section

master_count​

How many clients belong in the master section. The rest go to the stack.

-- Set on a tag
awful.tag.incnmaster(1)   -- Add one master slot (Mod4+Shift+l)
awful.tag.incnmaster(-1)  -- Remove one master slot (Mod4+Shift+h)

-- Or set directly
t.master_count = 2

With master_count = 2 and 5 windows open, the first 2 fill the master area (split vertically between them) and the remaining 3 share the stack.

master_width_factor​

How much screen width master gets, as a fraction. 0.5 means an even split. 0.66 gives master two-thirds of the width.

-- Adjust with keybindings (default rc.lua)
awful.tag.incmwfact(0.05)   -- Mod4+l: master wider
awful.tag.incmwfact(-0.05)  -- Mod4+h: master narrower

-- Or set directly
t.master_width_factor = 0.66

master_fill_policy​

Controls what happens when there are no stack clients. With "expand" (the default), a single window fills the entire screen. With "master_width_factor", a single window only takes its proportional share, leaving empty space where the stack would be.

column_count​

How many columns to use in the stack section. With column_count = 2 and 4 stack clients, they form a 2x2 grid in the stack area.

awful.tag.incncol(1)   -- Add a stack column (Mod4+Ctrl+l)
awful.tag.incncol(-1)  -- Remove a stack column (Mod4+Ctrl+h)

Moving Clients Between Sections​

You can move a client to the master or stack section by changing its position in the client list:

MethodEffect
c:to_primary_section()Move to master (front of client list)
c:to_secondary_section()Move to stack (end of client list)
c:swap(other)Swap positions with another client

New Windows Always Go to Stack​

By default, new clients become master, pushing everything else down. This surprises most people. To make new windows go to the stack instead, add a callback to your default rule:

ruled.client.append_rule {
    rule = {},
    properties = {
        -- your existing default properties
    },
    callback = function(c)
        c:to_secondary_section()
    end,
}

Swap Master with Focused Client​

The default keybinding Mod4+Return (with Shift, if using the default rc.lua) swaps the focused client with the current master:

awful.key({ modkey, "Shift" }, "Return", function(c)
    c:swap(awful.client.getmaster())
end)

Which Layouts Use Master and Stack​

Not all layouts use the master/stack model:

LayoutUses master/stack?Notes
tile.rightYesMaster left, stack right (default)
tile.leftYesMaster right, stack left
tile.bottomYesMaster top, stack bottom
tile.topYesMaster bottom, stack top
spiralPartialUses master_width_factor for proportions, ignores master_count
dwindlePartialSame as spiral but splits in alternating directions
fairNoAll clients get equal space
fair.horizontalNoAll clients get equal space, horizontal split
maxNoFocused client fills the screen
magnifierSpecialFocused client is always "master", others shrink behind it
floatingNoNo automatic tiling at all

Tasklist Order​

The tasklist widget in the wibar displays clients in the same order as the client list. Master appears leftmost, stack clients appear to the right. If you use to_secondary_section() to send new windows to the stack, they also appear on the right side of the tasklist.

See Also​