Table of Contents generated with DocToc
Please use the branch that matches your Awesome version:
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:
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.
- this is the feature I have desired for that is lacking in current default configuration.
-
Emacs-inspired universal argument: Specify a numeric argument for, e.g., repetition or precise resizing. Idea/prototype credit: @AnthonyAaronHughWong in #3.
- 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 your preferred package manager. Example:
sudo pacman -S awesome --needed --noconfirm
on Arch Linux.
- Clone this repo 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 and nice-to-haves
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 (xfce4-screensaver
), network management (network-manager-applet
), terminal (kitty
), task manager (xfce4-taskmanager
), and screen setup (arandr
), etc..
Although not strictly dependencies, some of the packages are, in my opinion, nice to have.
On Arch Linux:
sudo pacman -S --needed --noconfirm feh dex xdg-utils screenfetch scrot xcompmgr wmname gnome-keyring seahorse
sudo pacman -S --needed --noconfirm xorg-xbacklight xf86-input-synaptics cheese workrave
sudo pacman -S --needed --noconfirm alsa-utils pulseaudio pulseaudio-alsa pulseaudio-alsa pulseaudio-bluetooth pavucontrol pulsemixer
sudo pacman -S --needed --noconfirm networkmanager network-manager-applet arandr
sudo pacman -S --needed --noconfirm pcmanfm gvfs udiskie xarchiver mc ranger
sudo pacman -S --needed --noconfirm kitty tmux polkit
sudo pacman -S --needed --noconfirm gvim neovim neovim-qt python-neovim emacs firefox chromium putty remmina goldendict
sudo pacman -S --needed --noconfirm fcitx-im fcitx-googlepinyin fcitx-configtool
sudo pacman -S --needed --noconfirm jdk-openjdk openjdk-doc
sudo pacman -S --needed --noconfirm nmap openssh aria2 wget the_silver_searcher
sudo pacman -S --needed --noconfirm ttf-bitstream-vera ttf-croscore ttf-dejavu ttf-droid ttf-roboto noto-fonts ttf-liberation ttf-ubuntu-font-family
sudo pacman -S --needed --noconfirm ttf-anonymous-pro ttf-freefont adobe-source-code-pro-fonts ttf-linux-libertine adobe-source-sans-pro-fonts
sudo pacman -S --needed --noconfirm adobe-source-han-sans-otc-fonts adobe-source-han-serif-otc-fonts
sudo pacman -S --needed --noconfirm xclip xsel clipmenu
sudo pacman -S --needed --noconfirm xfce4 xfce4-goodies
sudo pacman -S --needed --noconfirm mpd mpc ncmpcpp xfmpc
sudo aura -Ax --needed --noconfirm google-chrome
sudo aura -Ax --needed --noconfirm rstudio-desktop-bin
sudo aura -Ax --needed --noconfirm stardict-oald stardict-wordnet dict-wn dict-foldoc
miscellaneous
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.
universal argument
Universal Argument (UniArg), inspired by the namesake Emacs feature, supplies a positive numeric argument to the following command. Depending on the context, it may supply a number of repetitions (search for uniarg:key_repeat
in rc.lua
) or a numeric argument (search for uniarg:key_numarg
in rc.lua
) such as percentage of volume adjustment or pixels to resize the client window. For example, with the UniArg being 3, "open terminal" operation (ModkeyEnter by default) will open 3 terminals.
Universal argument is activated when inputing a great-than-1 integer, and is deactivated when inputing a less-than-2 integer or a non-number. When universal argument is deactivated, the default behavior kicks in, which follows some heuristics to do sensible things such as the "extend client by 1/7 of the margin" and "shrink client by 1/11 of client width and leave client width at least 50 pixels" behavior for client window side expansion/shrinking documented below.
There are two modes of universal argument: Regular and persistent. Regular universal argument only applies to the next operation, while persistent universal argument applies to all following operations until changed or deactivated.
key combo |
function |
comment |
Modkeyu
|
prompt for universal argument |
see above paragraphs for details |
ModkeyShiftu
|
prompt for persistent universal argument |
see above paragraphs for details |
window management
restart/quit/info
key combo |
function |
comment |
ModkeyCtrlr
|
restart |
"r" for restart; used for apply updated "rc.lua" config file |
ModkeyCtrlShiftr
|
restart |
"r" for restart; restart without confirming with user |
ModkeyShiftq
|
quit |
"q" for quit; exit the current Awesome session |
ModkeyShiftCtrlq
|
forcibly quit |
"q" for quit; quit without confirming with user |
Modkey\
|
system info popup |
|
Modkeyf1
|
open help in browser |
|
CtrlShiftEsc
|
open task manager |
xfce4-taskmanager |
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 next screen by index |
|
ModkeyShifto
|
send client to previous screen by index |
|
ModkeyCtrlAltShiftRight
|
send tag to next right screen |
|
ModkeyCtrlAltShiftLeft
|
send tag to next left screen |
|
ModkeyCtrlAltShiftUp
|
send tag to next up screen |
|
ModkeyCtrlAltShiftDown
|
send tag to next down screen |
|
ModkeyCtrlo
|
send tag to next screen |
|
ModkeyCtrlShifto
|
send tag to prev screen |
|
ModkeyCtrlShift\
|
select next display arrangement |
https://awesomewm.org/recipes/xrandr/ |
ModkeyCtrlAlt\
|
XRandR config popup |
https://github.com/k3rni/foggy |
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;
|
toggle task action menu |
|
ModkeyShift;
|
toggle 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
|
attach/launch terminal multiplexer |
|
persistent dynamic tagging
tag persistence
key combo |
function |
comment |
ModkeyCtrlAltt
|
toggle tag persistence |
tags persist across exit/restart by default |
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 50 pixels |
ModkeyAltShiftRight
|
shrink client from left |
by 1/11 of client width; leave client width at least 50 pixels |
ModkeyAltShiftUp
|
shrink client from bottom |
by 1/11 of client height; leave client height at least 50 pixels |
ModkeyAltShiftDown
|
shrink client from top |
by 1/11 of client height; leave client height at least 50 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 |
Modkeyy
|
jump to the urgent client |
"y" next to "u" (taken by universal argument) 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 |
Modkey`
|
screen saver/locker |
xfce4-screensaver |
ModkeyCtrl`
|
display power off |
xset dpms force off |
ModkeyHome
|
screen saver/locker |
xfce4-screensaver |
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
|
primary file manager |
ranger |
ModkeyAltShiftl
|
secondary file manager |
pcmanfm |
Modkeye
|
primary file manager |
ranger; MSFT Windows key |
ModkeyShifte
|
secondary file manager |
pcmanfm |
ModkeyEnter
|
terminal |
kitty |
ModkeyAltEnter
|
terminal multiplexer |
tmux |
ModkeyAltp
|
remote terminal |
putty |
ModkeyAltr
|
remote terminal |
remmina |
Modkeyi
|
primary editor |
gvim |
ModkeyShifti
|
secondary editor |
emacs |
Modkeyb
|
primary browser |
chromium |
ModkeyCtrlb
|
private primary browser |
chromium --incognito |
ModkeyShiftb
|
secondary browser |
firefox |
ModkeyShiftCtrlb
|
private secondary browser |
firefox --private |
Modkeyv
|
clipboard manager |
clipmenu |
ModkeyAltv
|
hypervisor |
virtualbox |
ModkeyAltm
|
MPD client |
ncmpcpp |
ModkeyShift\
|
screen magnifier |
kmag |
PrtSc |
screen shooter |
xfce4-screenshooter |
the rest
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.option.launch_compmgr_p |
boolean |
launch composite manager on startup? |
false |
customization.timer.change_wallpaper.timeout |
number |
randomly choose a wallpaper from the "wallpaper" directory after every this number of seconds |
15 |
customization.option.tag_persistent_p |
boolean |
tag persistent across restart? false for clean slate |
true |
customization.option.low_battery_notification_p |
boolean |
warn about low battery condition |
true |
customization.widgets.bat.warning_threshold |
number |
low battery notification threshold in percentage |
10 |
customization.widgets.bat.instance |
string |
battery under monitor for low battery notification |
"BAT0" |
todo
- [ ] improve persistent dynamic tagging: preserve tag configuration (e.g., layout style and client positions)