Table of Contents generated with DocToc

• [awesome Window Manager configuration](#awesome-window-managerawesome-configuration)
  • intro
  • setup
    • install on Linux
    • dependencies and nice-to-haves
    • miscellaneous
  • usage
    • universal argument
    • window management
      • restart/quit/info
      • layout
      • multiple screens/multi-head/RANDR
      • misc
    • persistent dynamic tagging
      • tag persistence
      • 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

Please use the branch that matches your Awesome version:

• Awesome 3.x.
• Awesome 4.x.

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.
• 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 picom), 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).

• 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.

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 picom 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

• 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.

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 (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.

only the following layouts are enabled

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

all these keys work on the single currently focused client

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).

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

the five buttons on the upper right corner

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

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