From ArchWiki

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:
Please move or remove them before you can switch branches.
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-aliasAUR, 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
    # desktop or server machine commands

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.


File grouping
How configuration files can be grouped to configuration groups (also called profiles or packages).
Some tools process configuration files to allow them to be customized depending on the host.
Name Package Written in File grouping Processing
dotbot dotbotAUR Python configuration file No
chezmoi chezmoi Go directory-based Go templates
dot-templater dot-templater-gitAUR Rust directory-based custom syntax
toml-bombadil toml-bombadil Rust configuration file tera
dotdrop dotdropAUR Python configuration file Jinja2
dotfiles dotfilesAUR Python No No
Dots dots-managerAUR Python directory-based custom append points
dotter dotter-rsAUR Rust configuration file Handlebars
dt-cli dt-cliAUR Rust configuration file Handlebars
GNU Stow stow Perl directory-based[3] No
Mackup mackupAUR Python automatic per application No
mir.qualia mir.qualiaAUR Python No custom blocks
rcm rcmAUR 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 dotbareAUR Shell (fzf) repository-wise No
dotgit dotgitAUR Python filename-based No
homeshick homeshick-gitAUR Bash repository-wise No
homesick Ruby repository-wise No
Pearl pearl-gitAUR Python repository-wise No
vcsh vcsh Shell repository-wise No
yadm(1) yadm Shell filename-based
(by class/OS/distro/hostname/user)[4]
Built-in templates/Jinja2/ESH[5]
dfm dfmAUR Perl repository-wise No
  1. 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
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/kitty missioncenter, custom 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 ( awesome neovim alacritty tmux mpv, mpvs htop neomutt weechat lf
tuurep Bash openbox neovim alacritty tmux polybar
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

See also