Table of Contents generated with DocToc

• [awesome Window Manager configuration](#awesome-window-managerawesome-configuration)
  • intro
  • setup
    • install on Linux
    • dependencies
    • miscellaneous
  • usage
    • window management
      • restart/quit/info
      • layout
      • multiple screens/multi-head/RANDR
      • misc
    • dynamic tagging
      • add/delete/rename
      • view
      • move
    • client management
      • operation
      • change focus
      • swap order/select master
      • move/copy to tag
      • change space allocation in tile layout
      • misc
    • app bindings
      • admin
      • everyday
      • the rest
    • tag list
    • task list
    • root window/"the desktop"
    • window/task/client title bar
  • customization
  • todo

awesome Window Manager configuration

intro

awesome is awesome. I use it on all Arch Linux desktop/laptop machines that I have control over (admittedly, it is not designed for handheld smartphones/tablets).

Me using it to demo Figurehead.

Search YouTube for "awesome wm" to see awesome in action.

Among my favorites features:

• keyboard driven workflow (again, see this in action on YouTube).
• customizable through the Lua programming language.
• one-key-combo switching between tiling and stacking window management styles.
• the ability to do dynamic tagging (meaning it is not enabled by the default configuration---at least up to v3.5.4 (Brown Paper Bag) released on 2 April 2014).

This repo holds my personal take of awesome's configuration. Hightlights:

• persistent dynamic tagging across (both regular and randr-induced) restarts.
  • dynamic tagging means tags can be created/moved/renamed/deleted on the fly without touching the configuration.
  • persistent means tags and the clients/programs associated with each tag is preserved across awesome restart.
    • apparently, I am not the only one who desire this
  • this is the feature I have desired for that is lacking in current default configuration.
• confirmation before quit/restart to minimize data loss accidents.
  • you have to type "yes" (case insensitive) before quitting/restarting.
  • this minimizes the chance that you lose your work by accidents.
• keybindings for tuning transparency (using xcompmgr), stay-on-top, sticky.
  • these features combined, along with tiling and floating layouts, allow you to type in one window while seeing the content of others.
• keybindings to my preferred applications.
• only cycle through the most sensible (IMHO) layouts.
• keybinding optimized for Arch Linux over Thinkpad W530 (my current workhorse).

setup

install on Linux

• install awesome with either:
  • your preferred package manager (sudo pacman -S awesome --needed --noconfirm on Arch Linux) or
  • manually: my awesome fork has an installation shell script.
• Clone to $HOME/.config/awesome.

cd $HOME/.config && git clone https://github.com/pw4ever/awesome-wm-config.git awesome

• setup .xinitrc or Display Manager accordingly

dependencies

These dependencies are mostly derived from the application keybindings. Some are needed to enable basic features like theming (feh), Desktop Entry Specification-style autostart (dex), audio setup (alsa-utils), backlight (xorg-xbacklight), Webcam (cheese), music player (mpd and mpc), screen lock (xscreensaver), network management (network-manager-applet), terminal (sakura), and screen setup (arandr), etc..

On Arch Linux:

sudo pacman -S --needed --noconfirm feh dex xdg-utils screenfetch scrot xcompmgr kdeaccessibility wmname
sudo pacman -S --needed --noconfirm alsa-utils gnome-alsamixer xorg-xbacklight xf86-input-synaptics cheese mpd mpc workrave
sudo pacman -S --needed --noconfirm xscreensaver networkmanager network-manager-applet mate-power-manager arandr xfce4-appfinder xfce4-screenshooter
sudo pacman -S --needed --noconfirm pcmanfm gvfs udisks udiskie lxsession lxappearance xarchiver 
sudo pacman -S --needed --noconfirm sakura conky gksu
sudo pacman -S --needed --noconfirm gvim emacs firefox chromium putty remmina synergy
sudo pacman -S --needed --noconfirm fcitx-im fcitx-googlepinyin fcitx-configtool

miscellaneous

• make sure that you can write to /tmp (for dynamic tagging), e.g., through tmpfs
• populate your $HOME/.config/autostart with Desktop Entry Specification-style autostart files (optionally with OnlyShowIn=awesome if you only want them to auto-start in awesome).
• my autostart setup can be found here.

usage

Take a look at the "rc.lua" configuration file ($HOME/.config/awesome/rc.lua; perhaps by pressing the keybinding Modkeyc which will open rc.lua with the primary editor---for me, Vim).

Most keybindings are prefixed with the Modkey. This config associates Modkey to X Window's Mod4. On many machines, this associates the Super_L (tip: use xmodmap in terminal emulator to verify/change this), which usually translate to the (intuitively) Windows key.

Some keybinding requires further input (e.g., rename a tag), which will grab the key focus from your application. The Esc key is used to cancel partial input.

window management

restart/quit/info

key combo	function	comment
ModkeyCtrlr	restart	"r" for restart; used for apply updated "rc.lua" config file
ModkeyShiftq	quit	"q" for quit; used for apply updated "rc.lua" config file
Modkey\	system info popup
Modkeyf1	open help in browser

layout

key combo	function	comment
ModkeySpace	change to next layout
ModkeyShiftSpace	change to prev layout

mouse action	function
left button	change to next layout
right button	change to prev layout
scroll up	change to prev layout
scroll down	change to next layout

only the following layouts are enabled

layout	comment
floating	allow window stacking; the default
tile	tiling with master on the left
fair	fair allocation of screen space
fullscreen	the focused client fullscreened
magnifier	the focused client centered but not fullscreened

in the floating mode, the following mouse actions on client window are enabled

mouse action	function
Modkeyleft button	move client
Modkeyright button	resize client

multiple screens/multi-head/RANDR

key combo	function	comment
ModkeyCtrlj	focus on the next screen	"j" is easy to reach
ModkeyCtrlk	focus on the prev screen	"k" is easy to reach
Modkeyo	send client to the other screen

misc

key combo	function	comment
Modkeyf2	prompt a program to launch	inherited from awesome defaults
Modkeyr	prompt a program to launch	"r" for run
Modkeyf3	toggle touchpad	depend on synclient from xf86-input-synaptics
Modkeyf4	prompt Lua code to be eval-ed in awesome	inherited from awesome defaults
Modkeyc	edit "rc.lua" with the primary editor	"c" for configuration file
ModkeyShift/	show main menu
Modkeyx	show main menu	MSFT Windows key
ModkeyX	show main menu	MSFT Windows key
Modkey;	show task action menu
ModkeyShift;	show tag action menu
Modkey'	choose from clients on current tag
ModkeyCtrl'	prompt to choose from clients on current tag
ModkeyShift'	choose from all clients
ModkeyShiftCtrl'	prompt to choose from all clients
Modkey`	lock screen with screensaver
ModkeyEnter	launch user terminal
ModkeyAltEnter	launch root terminal

dynamic tagging

add/delete/rename

key combo	function	comment
Modkeya	create a new tag after the current one and view it	"a" for add
ModkeyShifta	create a new tag before the current one and view it	"a" for add
ModkeyShiftd	delte the current tag if there is no client on it	"d" for delete
ModkeyShiftr	rename the current tag	"r" for rename

view

key combo	function	comment
Modkeyp	view previous tag	"p" for previous
Modkeyn	view next tag	"n" for next
Modkeyz	view last tag
Modkeyg	prompted for a tag to view	with tag name completion with Tab
Modkey+[1-9,0]	view the first-ninth, tenth tag	prompt for "add a new tag" if not already existed
ModkeyCtrl+[1-9,0]	view also the first-ninth, tenth tag	prompt for "add a new tag" if not already existed

move

key combo	function	comment
ModkeyCtrlp	move the current tag backward by 1 position
ModkeyCtrln	move the current tag forward by 1 position

client management

operation

key combo	function	comment
ModkeyShiftc	kill focused client
Altf4	kill focused client	MSFT Windows key
Modkeyf	toggle fullscreen status	hides statusbar
Modkeym	toggle maximized status	leaves statusbar visible
ModkeyLeft	move window to left half screen	leaves statusbar visible
ModkeyRight	move window to right half screen	leaves statusbar visible
ModkeyUp	move window to top half screen	leaves statusbar visible
ModkeyDown	move window to bottom half screen	leaves statusbar visible
ModkeyAltLeft	extend client to the left	by 1/7 of the margin
ModkeyAltRight	extend client to the right	by 1/7 of the margin
ModkeyAltUp	extend client to the top	by 1/7 of the margin
ModkeyAltDown	extend client to the bottom	by 1/7 of the margin
ModkeyAltShiftLeft	shrink client from right	by 1/11 of client width; leave client width at least 256 pixels
ModkeyAltShiftRight	shrink client from left	by 1/11 of client width; leave client width at least 256 pixels
ModkeyAltShiftUp	shrink client from bottom	by 1/11 of client height; leave client height at least 256 pixels
ModkeyAltShiftDown	shrink client from top	by 1/11 of client height; leave client height at least 256 pixels
ModkeyShiftm	minimize	minimized client need mouse click on tasklist to restore
ModkeyCtrlSpace	toggle floating status
Modkeyt	toggle ontop status
Modkeys	toggle sticky status
Modkey,	toggle horizontal maximized status
Modkey.	toggle vertical maximized status
Modkey[	decrease opacity by 10%	need composite manager, e.g., xcompmgr
Modkey]	increase opacity by 10%	need composite manager, e.g., xcompmgr
ModkeyShift[	disable composite manager
ModkeyShift]	enable composite manager

change focus

key combo	function	comment
Modkeyj	focus on the next client in current tag	"j" is easy to reach
ModkeyTab	focus on the next client in current tag	MSFT Windows key
Modkeyk	focus on the prev client in current tag	"k" is easy to reach
ModkeyShiftTab	focus on the prev client in current tag	MSFT Windows key
Modkeyu	jump to the urgent client	"u" for urgent

swap order/select master

key combo	function	comment
ModkeyCtrlEnter	select current client as the master	master is featured on the screen
ModkeyShiftj	swap current client with the next one	"j" is easy to reach
ModkeyShiftk	swap current client with the prev one	"k" is easy to reach

move/copy to tag

all these keys work on the single currently focused client

key combo	function	comment
ModkeyShiftp	send the client to the previous tag	"p" for previous
ModkeyShiftn	send the client to the next tag	"n" for next
ModkeyShiftg	move the client to the named tag	with tag name completion by Tab
ModkeyCtrlShiftg	toggle the named tag for the client	with tag name completion by Tab
ModkeyShift1-9,0	move the client to {first-ninth, tenth} tag	prompt for "add a new tag" if not already existed
ModkeyCtrlShift1-9,0	toggle the {first-ninth, tenth} tag for the client	prompt for "add a new tag" if not already existed

change space allocation in tile layout

key combo	function	comment
Modkey=	reset master width to 50%	"=" for equal partition of screen
Modkeyl	increase master width by 5%	"l" towards right on keyboard
Modkeyh	decrease master width by 5%	"h" towards left on keyboard
ModkeyShiftl	increase number of masters by 1	"l" towards right on keyboard
ModkeyShifth	decrease number of masters by 1	"h" towards left on keyboard
ModkeyCtrll	increase number of columns by 1	"l" towards right on keyboard
ModkeyCtrlh	decrease number of columns by 1	"h" towards left on keyboard

misc

key combo	function	comment
ModkeyShift`	toggle the visibility of current client's titlebar

app bindings

shortcut keys are bound for most common apps; the keybinding is designed to be balanced between the left (pressing the Modkey) and the right hand (an additional easy to reach key).

admin

key combo	app	my choice
ModkeyAltEnter	root terminal	gksudo sakura
Modkey`	screen saver/locker	xscreensaver
ModkeyHome	screen saver/locker	xscreensaver
ModkeyEnd	suspend	systemctl suspend
ModkeyAltHome	hibernate (will confirm)	systemctl hibernate
ModkeyAltEnd	hybrid sleep (will confirm)	systemctl hybrid-sleep
ModkeyInsert	reboot (will confirm)	systemctl reboot
ModkeyDelete	power off (will confirm)	systemctl poweroff
Modkey/	GUI appfinder	xfce4-appfinder

everyday

key combo	app	my choice
ModkeyAltl	file manager	pcmanfm
Modkeye	file manager	pcmanfm; MSFT Windows key
ModkeyE	file manager	pcmanfm; MSFT Windows key
ModkeyEnter	user terminal	sakura
ModkeyAltp	remote terminal	putty
ModkeyAltr	remote terminal	remmina
Modkeyi	primary editor	gvim
ModkeyShifti	secondary editor	emacs
Modkeyb	primary browser	chromium
ModkeyShiftb	secondary browser	firefox
ModkeyAltv	secondary browser	virtualbox
ModkeyShift\	screen magnifier	kmag
PrtSc	screen shooter	xfce4-screenshooter

the rest

• currently optimized for Thinkpad W530 keyboard layout
• take a look at the config for details.

tag list

mouse action	function
left button	view the tag
Modkeyleft button	move current client to the tag
middle button	toggle whether to view the tag
Modkeymiddle button	toggle the tag for current client
right button	show tag action menu
Modkeyright button	delete the tag if empty
scroll up	view the prev tag
scroll down	view the next tag

task list

mouse action	function
left button	toggle task minimize status
middle button	choose from clients on current tag
Modkeymiddle button	choose from all clients
right button	show task action menu
scroll up	focus on prev task
scroll down	focus on next task

root window/"the desktop"

mouse action	function
left button	choose from all clients
middle button	show tag action menu
right button	show main menu
scroll up	view the prev tag
scroll down	view the next tag

window/task/client title bar

mouse action	function
left button	move the window
right button	resize the window

the five buttons on the upper right corner

button (fromt left to right)	function
1	toggle floating status
2	toggle maximized status
3	toggle sticky/show-in-all-tags status
4	toggle always-on-top status
5	close window

customization

The items can be changed with awesome-client. Example:

customization.option.wallpaper_change_p=true -- enable random wallpaper choosing
customization.timer.change_wallpaper.timeout=7.5 -- choose a wallpaper every 7.5 seconds

value	type	meaning	default value
customization.option.wallpaper_change_p	boolean	random wallpaper choosing enabled?	true
customization.timer.change_wallpaper.timeout	number	randomly choose a wallpaper from the "wallpaper" directory after every this number of seconds	15

todo

• improve persistent dynamic tagging: preserve tag configuration (e.g., layout style and client positions)