dotfiles

User-specific application configuration is traditionally stored in so called dotfiles (files whose filename starts with a dot). It is common practice to track dotfiles with a version control system such as Git to keep track of changes and synchronize dotfiles across various hosts. There are various approaches to managing dotfiles (e.g. directly tracking dotfiles in the home directory v.s. storing them in a subdirectory and symlinking/copying/generating files with a shell script or a dedicated tool). Apart from explaining how to manage dotfiles this article also contains a list of dotfile repositories from Arch Linux users.

Tracking dotfiles directly with Git

The benefit of tracking dotfiles directly with Git is that it only requires Git and does not involve symlinks. The disadvantage is that host-specific configuration generally requires merging changes into multiple branches.

The simplest way to achieve this approach is to initialize a Git repository directly in your home directory and ignoring all files by default with a gitignore(5) pattern of *. This method however comes with two drawbacks: it can become confusing when you have other Git repositories in your home directory (e.g. if you forget to initialize a repository you suddenly operate on your dotfile repository) and you can no longer easily see which files in the current directory are untracked (because they are ignored).

An alternative method without these drawbacks is the "bare repository and alias method" popularized on Ask Hacker News: What do you use to manage your dotfiles?, which just takes three commands to set up:

$ git init --bare ~/.dotfiles
$ alias dotfiles='/usr/bin/git --git-dir="$HOME/.dotfiles/" --work-tree="$HOME"'
$ dotfiles config status.showUntrackedFiles no

Note: Usually one's dotfiles all have default permissions, but if specific file permissions for some files are a must, another approach should be used, as git does not store permissions (Discussion)

Your dotfiles can be replicated on a new system like:

$ git clone --bare <git-repo-url> $HOME/.dotfiles
$ alias dotfiles='/usr/bin/git --git-dir="$HOME/.dotfiles/" --work-tree="$HOME"'
$ dotfiles checkout
$ dotfiles config --local status.showUntrackedFiles no

In case of already having some stock dotfiles which might get overwritten, you'll encounter something similar to the following the error:

$ dotfiles checkout
error: The following untracked working tree files would be overwritten by checkout:
    .bashrc
    .gitignore
Please move or remove them before you can switch branches.
Aborting

You could use $ dotfiles checkout -f which will rewrite the already existing files, or in a safer approach take a backup of all the files with the following script and then using checkout:

mkdir -p .dotfiles-backup && \
dotfiles checkout 2>&1 | egrep "\s+\." | awk {'print $1'} | \
xargs -I{} mv {} .dotfiles-backup/{}

You can then manage your dotfiles with the created alias. If you are using Bash and would like bash completion for this alias, simply install bash-complete-alias^AUR, then add the alias and the following line to your ~/.bashrc.

$ complete -F _complete_alias dotfiles

Another way to get completion in bash is adding the following to your ~/.bashrc (taken from [1]):

source /usr/share/bash-completion/completions/git
__git_complete dotfiles __git_main

Tip: To avoid accidentally committing confidential information, see Git#Filtering confidential information.

Host-specific configuration

A common problem with synchronizing dotfiles across various machines is host-specific configuration.

With Git this can be solved by maintaining a master branch for all shared configuration, while each individual machine has a machine-specific branch checked out. Host-specific configuration can be committed to the machine-specific branch; when shared configuration is modified in the master branch, the per-machine branches need to be rebased on top of the updated master.

In configuration scripts like shell configuration files conditional logic can be used. For example, Bash scripts (i.e. .bashrc) can apply different configuration depending on the machine name (or type, custom variable, etc.):

if [[ "$(hostname)" == "archlaptop" ]]; then
    # laptop specific commands here
else
    # desktop or server machine commands
fi

Similar can also be achieved with .Xresources.[2]

If you find rebasing Git branches too cumbersome, you may want to use a tool that supports file grouping, or if even greater flexibility is desired, a tool that does processing.

Tools

File grouping: How configuration files can be grouped to configuration groups (also called profiles or packages).
Processing: Some tools process configuration files to allow them to be customized depending on the host.

Name	Package	Written in	File grouping	Processing
dotbot	dotbot^AUR	Python	configuration file	No
chezmoi	chezmoi	Go	directory-based	Go templates
dot-templater	dot-templater-git^AUR	Rust	directory-based	custom syntax
toml-bombadil	toml-bombadil	Rust	configuration file	tera
dotdrop	dotdrop^AUR	Python	configuration file	Jinja2
dotfiles	dotfiles^AUR	Python	No	No
Dots	dots-manager^AUR	Python	directory-based	custom append points
dotter	dotter-rs^AUR	Rust	configuration file	Handlebars
dt-cli	dt-cli^AUR	Rust	configuration file	Handlebars
GNU Stow	stow	Perl	directory-based[3]	No
Mackup	mackup^AUR	Python	automatic per application	No
mir.qualia	mir.qualia^AUR	Python	No	custom blocks
rcm	rcm^AUR	Shell	directory-based (by host or tag)	No
yas-bdsm	–	Shell	directory-based	No

Tools wrapping Git

If you are uncomfortable with Git, you may want to use one of these tools, which abstract the version control system away (more or less).

Name	Package	Written in	File grouping	Processing
dotbare	dotbare^AUR	Shell (fzf)	repository-wise	No
dotgit	dotgit^AUR	Python	filename-based	No
homeshick	homeshick-git^AUR	Bash	repository-wise	No
homesick	–	Ruby	repository-wise	No
Pearl	pearl-git^AUR	Python	repository-wise	No
vcsh	vcsh	Shell	repository-wise	No
yadm⁽¹⁾	yadm	Shell	filename-based (by class/OS/distro/hostname/user)[4]	Built-in templates/Jinja2/ESH[5] (optional)
dfm	dfm^AUR	Perl	repository-wise	No

Supports encryption of confidential files with GPG or OpenSSL. [6]

User repositories

Note: This table is used as a reference/examples of dotfiles, if you are submitting your dotfiles to the table, please ensure they are kept clean, commented and up to date.

Warning: These dotfiles have not been verified by any of the Arch Linux staff, use at your own risk.

Author	Shell (Shell framework)	WM / DE	Editor	Terminal	Multiplexer	Audio	Monitor	Mail	IRC	File Manager	RSS reader
alfunx	Zsh	Awesome	Vim	Kitty	tmux	Ncmpcpp/Mpd	Htop/lain	Thunderbird
Ambrevar	Eshell	EXWM	Emacs	Emacs (Eshell)	Emacs TRAMP + dtach	EMMS	Conky/Dzen	mu4e	Circe
ananthu	Zsh	Bspwm	Neovim	Alacritty		Mpv	Htop, Polybar	Neomutt	WeeChat	Ranger
awal	Fish	i3	Vim	St	tmux		i3status		The Lounge
ayekat	Zsh	karuiwm	Vim	Rxvt-unicode	tmux	Ncmpcpp/Mpd	karuibar	Mutt	Irssi
bachoseven	Zsh	Dwm source	Neovim	St source	tmux	Ncmpcpp	bottom	Neomutt	WeeChat	Lf	newsboat
bamos	Zsh	i3/xmonad	vim/emacs	rxvt-unicode	tmux	mpv/cmus	conky/xmobar	mutt	ERC
benmezger	zsh/bash	i3-gaps	emacs	rxvt-unicode/alacritty	tmux	mopidy/ncmpcpp	i3status-rs	mu4e/neomutt/mbsync	weechat
brisbin33	zsh	xmonad	vim	rxvt-unicode	GNU Screen		dzen	mutt	irssi
BVollmerhaus	fish	i3-gaps	kakoune	kitty			polybar			ranger
christian-heusel	Zsh	i3	Neovim	st / terminator	byobu / tmux		htop	neomutt/thunderbird	WeeChat	nemo / ranger
CuterThanYou	Zsh	i3 / Hyprland	Neovim	Alacritty / Foot		Mpv	Polybar / Yambar			Lf / Thunar	Newsboat
cinelli	Zsh	dwm	Vim	termite-git		pianobar	htop	mutt-kz	weechat
dikiaap	Zsh	i3-gaps	neovim	alacritty	tmux		i3blocks			nnn
Earnestly	Zsh	i3/orbment	vim/emacs	termite	tmux	mpd	conky	mutt	weechat
ErikBjare	Zsh	xmonad/Xfce4	Vim	terminator	tmux		xfce4-panel		weechat
erikw	Zsh/Bash	DWM/macOS	NeoVim	urxvtc	tmux	mpd		mutt	irssi
falconindy	Bash	i3	Vim	rxvt-unicode		ncmpcpp	conky	mutt
filiparag	fish	bspwm	Vim	alacritty	tmux	mpv, playerctl	htop, polybar	mail-notification		PCManFM
Freed-Wu	zsh	openbox	neovim	wezterm	tmux	cmus	bottom	neomutt	WeeChat	neovim	newsboat
gardenapple	Zsh (fish-like)	Hyprland	neovim	kitty			htop	aerc		vifm	Newsboat
graysky	Zsh	xfce4	Vim	terminal		ncmpcpp	custom	thunderbird
hugdru	Zsh	awesome	neovim	rxvt-unicode	tmux			thunderbird	weechat
insanum	Bash	herbstluftwm	Vim	evilvte	tmux		dzen	mutt-kz
isti115	pwsh	sway	neovim	alacritty	tmux	mpv / playerctl	waybar / htop / ytop			ranger
jasonwryan	bash/zsh	dwm	Vim	rxvt-unicode	tmux	ncmpcpp	custom	mutt	irssi
jdevlieghere	Zsh	xmonad	Vim	terminal	tmux		htop	mutt	weechat
jelly	Zsh	i3	Vim	termite	tmux	ncmpcpp		mutt-kz-git	weechat
jl2	Zsh	swayfx	geany	foot			missioncenter, eww (bar)		srain	thunar
MarkusZoppelt	Zsh	gnome	Neovim	Alacritty	tmux
maximbaz	Zsh	sway	kakoune	kitty			waybar	neomutt		nnn
mehalter	Zsh	i3-gaps	neovim	termite	tmux	cmus	gotop	neomutt	weechat	ranger
meskarune	Bash	herbstluftwm	Vim	rxvt-unicode	GNU Screen		conky		weechat
neersighted	fish	i3	neovim	alacritty	tmux	ncmpcpp
nimaipatel	fish	awesome	neovim	alacritty		ncmpcpp
oibind	fish	awesome	neovim	st	tmux		htop-vim		weechat	lf
OK100	Bash	dwm	Vim	rxvt-unicode		cmus	conky, dzen	mutt	weechat
orhun	Bash	i3-gaps	neovim	alacritty			i3status		weechat	tere
pablox-cl	zsh (zplug)	GNOME	neovim	kitty
patri9ck	Zsh	bspwm	Vim	kitty						Thunar
peterzuger	Zsh	i3-gaps	emacs	rxvt-unicode	GNU Screen	moc	htop
polyzen	Zsh	i3	Neovim	Alacritty	tmux	mpv	i3status,htop	himalaya		ranger	Newsboat
potamides	Bash	awesome	neovim	termite	tmux	ncmpcpp	conky,htop	mutt	weechat	ranger
reisub0	fish	qtile	neovim	kitty		mpd	conky
sistematico	zsh/fish/bash	i3-gaps	vim/nano	termite	tmux	ncmpcpp	polybar	mutt	weechat
sitilge^{[dead link 2024-01-13 ⓘ]}	Zsh	sway	neovim	alacritty			htop	thunderbird
thecashewtrader	Eshell	EXWM	Emacs	Emacs (VTerm)	Emacs	Bongo	htop	mu4e	ERC	Dired	Elfeed
thiagowfx	bash/zsh	i3	Vim	alacritty	tmux	playerctl	i3status			ranger
tplasdio	bash (ble.sh)	awesome	neovim	alacritty	tmux	mpv, mpvs	htop	neomutt	weechat	lf
tuurep	Bash	openbox	neovim	alacritty	tmux		polybar
unrealapex	Zsh	Dwm	Neovim	St		Ncmpcpp	htop	Neomutt	Irssi	fff	Newsboat
vodik	Zsh	xmonad	Vim	termite-git	tmux	ncmpcpp	custom	mutt	weechat
w0ng	Zsh	dwm	Vim	rxvt-unicode	tmux	ncmpcpp	custom	mutt	irssi
whitelynx	fish	i3	neovim	kitty			i3pystatus
whynothugo	Zsh	sway	neovim	alacritty		mpv	waybar, top	neomutt		nemo
wryonik	Zsh	i3-gaps-rounded	Vim	terminator		cmus	htop, i3blocks, gotop			ranger, nautilus

Tracking dotfiles directly with Git

Host-specific configuration

Tools

Tools wrapping Git

User repositories

See also