Dotfiles usage guide

1 stow -t /etc etc

pacman.conf: pacman package manager configuration file. To use repos in archlinuxcn, you need to import PGP Keys from archlinuxcn:

$ sudo pacman -Sy && sudo pacman -S archlinuxcn-keyring

2 stow home

.profile sets OS_TYPE and DISTRO_TYPE.

.zshenv sets zsh configuration place. However, you can set it in .pam.environment if you like (According to linux-pam/linux-pam@ecd5267, Reading ~/.pam_environment is deprecated and the feature will be removed at some point in the future.).

If you already have .profile in home directory, stow bash will fail. Remove the original .profile or use --adopt option.

3 stow config

3.1 fontconfig

Use man fonts-conf to see configuration file format. After finishing editing $HOME/.config/fontconfig/fonts.conf, to apply changes, you may need to do one of the following:

If you only edit pattern elements, simply restarting applications is sufficient to load the new configuration.
If you edit scan elements, before restarting applications, you may need to do fc-cache -fv to re-scans the font directories.
Reload .Xresources with xrdb ~/.Xresources
Restart the display server 4.1. X11/X.Org Server
- With display manager: sudo systemctl restart display-manager
- Without display manager: maybe sudo pkill X
NOTE: This will forcefully quit all graphical programs, you’ll lose any unsaved work, and you’ll be logged out. Non-graphical programs will not be affected. 4.2. Wayland/KWin
- For KWin on X: kwin_x11 --replace, with --replace, the running apps in KDE would survive the restart of kwin.
- For KWin on Wayland: It is the session, basically, there’s no way to recover.
- For Plasmashell: plasmashell --replace (new in Plasma 5.13), kquitapp5 plasmashell && kstart5 plasmashell (older, kquitapp5 tells plasmashell on DBus to gracefully quit).
Reboot your machine

3.2 i3

For i3 user guide, you can refer to i3: i3 User’s Guide or i3 - Gentoo Wiki as a supplement. All i3-gaps features become available with i3 4.22. This config mainly changes the following:

Modifier key changed to Win. In i3, commands are invoked with a modifier key, referred to as $mod. This is Alt (Mod1) by default, with Super (Mod4) being a popular alternative. Super is the key usually represented on a keyboard as a Windows icon, or on an Apple keyboard as a Command key.
Four navigation shortcuts, j, k, l and “semicolon” changed to vim style, h, j, k, l.
- and \ to split in horizontal and vertical orientation

Other key bindings keep same with the default, generally are:

General
- <Enter> open a terminal (konsole)
- d open program launcher (Rofi)
- E exit i3
- C reload config file
- R restart i3 in place
Mode (<Esc> or <Enter> to back to normal mode)
- r resize mode
- o execution mode
- z system mode
- G gaps mode
Window
- s stacked layout
- w tabbed layout
- e vertical and horizontal layout (switches to and between them)
- f toggle fullscreen
- Q kill window (does normal close if application supports it)

To memorize i3’s shortcuts, you can have a look at i3 - Reference Card. To debug i3, i3: Debugging i3: How To is a getting started article.

If you want to bind some symbol keys but don’t know what they’re called. You can run xev (xev -event keyboard if you only care for key presses) from a terminal and press your desired key. xev should output information about the events it got from X11.

Some tools you must install:

feh to set wallpaper.
Rofi as program launcher(d, first char of dmenu) and window selector(/, vim search key).
alacritty as terminator.
i3lock-fancy as screen locker.

To use another window manager instead of the default KWin in the Plasma desktop environment developed by KDE, you can refer to Tutorials/Using Other Window Managers with Plasma - KDE UserBase Wiki. Specifically, to use i3 as WM, first you need to config i3 to avoid tiling popups and dropdown windows from Plasma, then create ~/.config/plasma-workspace/env/wm.sh and made sure that it has execution privileges to config Plasma to load i3 (If it doesn’t work, you can add export KDEWM=/usr/bin/i3 in ~/.xprofile). You can refer to KDE Plasma with i3 WM Instead of KWin | Max’s Blog for more detail. Following are some dotfiles I found related with this situation:

If you have installed multiple window managements and desktop environments, you can choose which one to use in the login page.

3.3 polybar

The config syntax of polybar mainly contains two parts: bar and module, remains are mainly customized variables or module specific keys. For example, following defines a bar named mybar which contains only one module called mymodule at the center of mybar:

[bar/mybar]
modules-center = mymodule

[module/mymodule]
str = My Module

Each module actually should have a type filed, you can click to view all of them in section Modules of polybar/polybar Wiki. The following is a very basic polybar configuration of real which defines a bar named mybar with a module called date:

[bar/mybar]
modules-right = date

[module/date]
type = internal/date
date = %Y-%m-%d%

In a word, configuring polybar is just to config each module and place them according to your desired order in bar. By default polybar also installs a sample configuration with many preconfigured modules in /usr/share/doc/polybar/config. Also, jaagr/dots lists examples of possible module by polybar author and arcolinux-polybar gives examples for almost all modules.

Where to find other configurations?

If you use i3wm, you probably cannot stand the title bar in tabbed/stacking mode while using polybar. Luckily, there are many third party libraries that help displaying window titles directly in polybar (Remember make script executable with chmod +x):

meelkor/polybar-i3-windows. Python script that shows application icon and window titles of all workspaces. Title order changes with window movement.
tam-carre/polywins. Shell script that shows window title of current workspace. Title order doesn’t change with window movement in same workspace unless reload i3 config.
aroma1994/polybar-windows. Shell script that shows window title of current workspace. Title order doesn’t change with window movement in same workspace unless reload i3 config. Have some bugs highlighting current focused window.
folke/polydock
melangue/bspwm-window-titles

Once you choose one, you can now hide i3 title bar by setting window title font size to zero with something like font pango:DejaVu Sans Mono 0 in configuration file. (There are some solutions with 4.12. Default border style for new windows like default_border pixel 1 or for_window [class="^.*"] border pixel 1 but all don’t work for me)

To make the bar fancy, most configurations are highly dependent on extra icons which requires specific font. To display them normally, check the font- variables and download them. If you want to make your own polybar, you can choose icon font among popular icon fonts, then you can go to the cheatsheet page for easier search:

Nerd Fonts Cheatsheet. Except patched fonts listed in assets, there is also other third-party patched font such as laishulu/Sarasa-Mono-SC-Nerd, jonz94/Sarasa-Gothic-Nerd-Fonts.
FontAwesome v5 Cheatsheet
Material icons Cheetsheet
Search Material Design Icons
Search Feather Icons
Search react-native-vector-icons

In my polybar configuration, I consider following icons:

battery/ramp-battery
brightness/ramp-brightness
calendar
clock
upload/download speed
volume/ramp-volume, headphone
wifi/wifi-off/ramp-wifi
wired/wired-off
microphone/microphone-off, speaker/speaker-off

I choose nerd font to cover most of them.

If you use polybar in KDE, you might suffer from tray disappear. You can have a look at Plasma System Tray not working on Polybar · Issue #2313 · polybar/polybar, the reason is that applications on your system don’t actually provide a tray icon for polybar when running in KDE. Similarly, if there are multiple polybar instances or another program is already displaying the tray, only a single application can display the tray at a time, you can refer to Unable to display tray area after boot · Issue #2077 (comment) · polybar/polybar for more information.

To pickup polybar color, you mainly need to design the bar’s background and foreground color, then the module’s text/icon background and foreground color. You may get inspiration from the following polybar themes:

3.4 terminator

Documentation for all of Terminator’s keybindings and config options in man pages is included in the source/packages. See:

man terminator
man terminator_config

3.5 tmux

3.5.1 Simple Guide

tmux documentation can be found at Wiki · tmux/tmux. For a local one, you can refer to man 1 tmux. Here lists some useful information:

Tmux Command	Short Form
set-option	set
set-window-option	setw
bind-key	bind
unbind-key	unbind
display-message	display
run-shell	run
if-shell	if

Variable Name	Alias	Replaced With
	#(command)	First line of command’s output
	#[attributes]	Color or attribute change
host	#H	Hostname of local host
host_short	#h	Hostname of local host (no domain name)
pane_id	#D	Unique pane ID
pane_index	#P	Index of pane
pane_path	#T	Path of pane (can be set by application)
pane_title	#T	Title of pane (can be set by application)
session_name	#S	Name of session
window_flags	#F	Window flags
window_index	#I	Index of window
window_name	#W	Name of window
	##	A literal ‘#’

3.5.2 Introduction

This setting remaps prefix key to ` by set-option -g prefix `. After you are familiar with this binding, if you are on a remote box, you can simply do a c-b : and type it.

M-hjkl selects panes with vi movement commands.
M-HL selects windows with vi movement commands.
C-S-letter is same with C-letter.
M-✥ : doesn’t respond
S-✥ : ⇄: move pane to window
M-S-✥: ⇄: move pane from window
C-M-✥: swap panes
C-✥ : small pane size
C-S-✥: large pane size
C-M-S-✥: unbind yet

3.5.3 Tmux Plugin Manager

I’m using TPM to manage tmux plugins. To use it, you need to clone TPM first:

$ git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

Then reload TMUX environment to make sure TPM is sourced:

# type this in terminal if tmux is already running
$ tmux source ~/.config/tmux/.tmux.conf

To install a plugin, you need to do the following steps:

Add new plugin to ~/.tmux.conf with =set -g @plugin ‘…’=
Reload TMUX environment so TPM is sourced: $ tmux source ~/.config/tmux/.tmux.conf
Press prefix + I (capital i, as in *I*nstall) to fetch the plugin.

If you want to manage plugins via the command line, you can add the following config to .tmux.conf:

$ set-environment -g TMUX_PLUGIN_MANAGER_PATH '~/.tmux/plugins/'

Then run the following command in terminal:

$ ~/.tmux/plugins/tpm/bin/install_plugins

See Managing plugins via the command line · tmux-plugins/tpm for more detail.

If you are suffering from network problem, such as couldn’t perform git clone, you can edit the clone_plugin() function in ~/.tmux/plugins/tpm/scripts/install_plugins.sh.

3.5.4 Troubleshooting

3.5.4.1 Scrolling issues

If you have issues scrolling with Shift-Page Up/Down or Shift-Mouse Scroll in your terminal and your goal is just to copy text after selecting. Then the easiest way to do the same thing is to use tmux’s native scrollback, following are steps to do that:

Enter copy mode with C-b [ or just scroll the buffer.
Use your desired ways to go to the position from where you want to start copying. Available ways are: 2.1 The arrow keys 2.2 Emacs keybindings 2.3 Vim keybindings
Press keys to start copying. 2.1 Default is Emacs keybindings: C-Space or C-@ 2.2 Add following config into your ~/.tmux.conf to enable Vim keybindings

bind-key -T copy-mode-vi v send-keys -X begin-selection
bind-key -T copy-mode-vi y send-keys -X copy-selection
bind-key -T copy-mode-vi r send-keys -X rectangle-toggle

Use your deired ways to go to the end of text you want to copy.
Press keys to copy from tmux buffer. 5.1 Default is Emacs keybindings: M-w or C-w
Use C-b ] to paste copied text from tmux clipboard.

You can also try solution from Scrolling issues | tmux - ArchWiki which enables scrolling while pressing Shift:

set -ga terminal-overrides ',xterm*:smcup@:rmcup@'

3.5.5 Possible Error

If you have a different version of tmux, you may get some errors. For example, with tmux 2.6, you may get

~/.config/tmux/.tmux.conf:56: invalid or unknown command: unbind \"
~/.config/tmux/.tmux.conf:57: unknown key: \\

To fix these, you could either upgrade the tmux or just adjust the syntax to version 2.6 by checking tmux list-keys

unbind '"'
bind \ split-window -h

3.6 xkeysnail

Letter Frequency lists punctuation frequency

Punctuation Frequency:

, . - ” _ ’ ) ( ; = : / * ! ? $ > { } [ ] \ + | & < % @ # ^ ` ~

_ ( ) ; , = . * ” - / $ > { } : ’ \ [ ] & + < | @ # ! % ? ~ ^ ` (Programming)

After excluding brackets and predefined leader key(~;[‘~), we have 15 punctuation left. According to rules 1) Frequency 2) Mirror Symmetry, I map these punctuation to keys in left hand area of QWERTY keyboard:

!, Exclamation mark         (Warning)
@, Commercial at            (Z)
#, Number sign, *H*ash      (Symmetry->G)
$, *D*ollar sign, Peso sign (Unique->D)
%, Percent sign             (Least frequent->T)
^, Circumflex accent, Caret (Least frequent->B)
&, Ampersand                (R)
*, *A*sterisk               (Most frequent->A)
_, Low line, Underscore     (Most frequent->F)
+, Plus sign       (X)
-, Hyphen-*M*inus  (Symmetry->V)
=, *E*quals sign   (Most frequent->E)
?, *Q*uestion mark (Unique->Q)
;, *S*emicolon     (Unique->S)
:, *C*olon         (Most frequent->C)

3.7 zsh

Download zsh

Platform	Command
Arch	sudo pacman -S zsh
Ubuntu	sudo apt install zsh

Download antigen

$ mkdir ~/.antigen & cd ~/.antigen
# Common download
$ curl -L git.io/antigen > antigen.zsh
# On Ubuntu lower version
$ sudo wget https://raw.githubusercontent.com/zsh-users/antigen/v2.2.3/bin/antigen.zsh
# On Arch
$ yay -S antigen-git

ZSH loads the following files in order. $ZDOTDIR is used instead of $HOME if set.

/etc/zsh/zshenv (always)

If NO_RCS is set, none of the following are run.

[@2] ~/.zshenv (Usually run for all shells)
/etc/zsh/zprofile (login)
~/.zprofile (login)
/etc/zsh/zshrc (interactive)
~/.zshrc (interactive)
/etc/zsh/zlogin (login)
~/.zlogin (login)

If a login shell, the following are run on logout or exit.

~/.zlogout
/etc/zlogout

4 themes

Telegram Desktop: WindowBg to #f5f2ee.
KDE theme: Appearance -> Colors -> Genshin from CSSlayer

Ynjxsjmh / dotfiles