Getting started

First, you should have built awesome 3. Most of the information in this guide still remain available for awesome 2.3, since the basic concepts haven’t changed.

Contents 1 Concepts 2 Launching awesome 3 Using awesome 3.1 Home screen 3.2 Basic mappings 3.2.1 Keyboard 3.2.2 Mouse 4 Configure awesome 4.1 Behaviour 4.2 Theming

Concepts

Before even using awesome, you should know a few terms that might not be usual.

Client 

a simple window.

Tag

A tag can be seen as a workspace. But if you look more closely, you see that you can show

a client on multiple tags. It's also possible to display more than one tag at the same time.

Master windows

The master windows are usually the ones requiring most attention. This concept comes from dwm, from which awesome got some ideas.

The other windows are just called non-master.

Floating window

Usually, windows don't overlap each other. Since some applications don't work well in this mode, it's possible to make clients floating.

Floating clients can be resized and moved freely as in non-floating window manager.

Layout

A layout is a way of organizing windows in a view. awesome offers the following layouts:

• colums - master windows are displayed in the left column (or the right one: there are two layouts) and the other windows are in multiple columns.
• rows - the same, with rows instead of columns.
• magnified - the master window (only one in this layout) is drawn in the middle of the screen, the other ones are stacked under it in columns.
• maximized - the master window uses all available place and the other ones are hidden.
• spiral - the master window stays in the left half of the screen, the next on uses the half of the other half, the third on half of the remaining half, and so on clockwise.
• zig-zag - as above, except windows are drawn from right to bottom, then right, instead of clockwise. It's easier than it sounds, just try it.
• floating - windows can be freely moved and resized, and they can overlap each other.

Launching awesome

• If you’re using a login manager as KDM or GDM, simply choose awesome in the session selection menu.
• If you start X system yourself, put this in your ~/.xinitrc:

#! /bin/sh
exec awesome

Using awesome

Home screen

Once you’ve launched awesome, you have a screen which shows the awesome logo, and a statusbar on top, like this one below (colors might be different, and some elements could be somewhere else):

This bar includes:

• an awesome logo.
• a list of available tags, with the currently selected tag emphasized.
• a list of clients in the current view, which is empty for now, since we haven’t any clients open yet.
• a logo of the current layout in use (colums, master windows on the left)
• the date (or UNIX timestamp in default configuration)

Basic mappings

All actions in awesome are done with a mouse or with key bindings using a main modificator. In the default config, this modificator is Mod4, meaning the “Super” key, on which usually shows a windows logo, an apple or a penguin. Some keyboards don’t have this key, so you’ll have to change the configuration as explained below. This modificator key will be called “Mod” from here on.

Here is a list of essential commands. There are so many more, and they are details in the man pages for awesome(1), that you should read (man 1 awesome).

Keyboard

Mod + <return>  

Launch a terminal

Mod + r  

Display a prompt in the bar to run a program. You have acces to an history (↑) and completion (↹).

Mod + shift + c  

Close the selected window.

Mod + j, k  

Select the next, previous window.

Mod + shift + j,k  

Move the selected window by swapping it with the next, previous one.

Mod + Ctrl + Esc  

Toggle the floating attribute of the window.

Mod + left, right  

Display the previous, next tag.

Mod + shift + space  

Change the layout (using ⇧ (Shift), doing so in the reverse order). To fully understand their caracteristics, try with many windows.

Mod + shift + h,l  

Increase, lower the number of master windows (only useful in some layouts).

Mod + Ctrl + h,l  

Increase, lower the number of columns for non-master windows (only useful in some layouts).

Mod + Ctrl + r  

Relaunch awesome: allows you to reload the configuration after you modified it.

Mod + shift + q  

Quit awesome

Mouse

Right click in an empty region  

Open a menu

Click on a window name in the list 

Focus and display this window.

Mod + drag a window  

Move the window. Freely if floating, swapping it with other ones if not.

Mod + drag with right button  

Resize a floating window, or the master zone in some layouts.

Click on a tag name in the list  

Display this tag.

Scroll on the tag list  

Display the previous or next tag.

Mod + click on a tag name  

Put the selected window in this tag.

Configure awesome

Behaviour

Awesome 3's configuration file is named rc.lua, and is located in ~/.config/awesome/. At first, you don’t have any personal config file, and the default one is used: in /etc/xdg/awesome/.

So, to configure awesome, begin with copying the system file into your directory:

$ cp /etc/xdg/awesome/rc.lua ~/.config/awesome/rc.lua

Then, you can edit it: the comments are made to help you quickly understand how to tweak awesome (including keybinding).

Theming

Awesome's theme config file is loaded by your rc.lua config file:

theme_path = "/usr/share/awesome/themes/default"

You can copy this file, e.g. into ~/.config/awesome/themes, then load it instead of the default one (relative path from you own directory):

theme_path = ".config/awesome/themes/default"

Again, this theme file is well commented, so you should be able to quickly understand how to set it up.