Dotfiles: Difference between revisions

Revision as of 15:35, 27 January 2019

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 your 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 your 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 by this Hacker News comment, which just takes three commands to set up:

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

You can then manage your dotfiles with the created alias.

Tip: To avoid accidentally commiting 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.[1]

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
dotdrop	dotdrop^AUR	Python	configuration file	Jinja2
dotfiles	dotfiles^AUR	Python	No	No
Dots	dots-manager^AUR	Python	directory-based	custom append points
GNU Stow	stow	Perl	directory-based[2]	No
Mackup	mackup^AUR	Python	automatic per application	No
mir.qualia	mir.qualia^AUR	Python	No	custom blocks
rcm	rcm^AUR	Perl	directory-based (by host or tag)	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
dotgit	dotgit^AUR	Bash	filename-based	No
homeshick	homeshick-git^AUR	Bash	repository-wise	No
homesick	homesick^AUR	Ruby	repository-wise	No
Pearl	pearl-git^AUR	Bash	repository-wise	No
vcsh	vcsh^AUR	Shell	repository-wise	No
yadm¹⁾	yadm-git^AUR	Shell	filename-based (by class, OS, hostname & user) [3]	Jinja2 (optional)[4]

Supports encryption of confidential files with GPG.[5]

User repositories

Author	Shell (Shell framework)	WM / DE	Editor	Terminal	Multiplexer	Audio	Monitor	Mail	IRC
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
awal	fish	i3	vim	st	tmux		i3status		The Lounge
ayekat	zsh	karuiwm	vim	rxvt-unicode	tmux	ncmpcpp/mpd	karuibar	mutt	irssi
bamos	zsh	i3/xmonad	vim/emacs	rxvt-unicode	tmux	mpv/cmus	conky/xmobar	mutt	ERC
brisbin33	zsh	xmonad	vim	rxvt-unicode	screen		dzen	mutt	irssi
BVollmerhaus	bash	i3-gaps	kakoune	rxvt-unicode			polybar	thunderbird
cinelli	zsh	dwm	vim	termite-git		pianobar	htop	mutt-kz	weechat
dikiaap	zsh	i3-gaps	neovim	alacritty	tmux		i3blocks
Earnestly	zsh	i3/orbment	vim/emacs	termite	tmux	mpd	conky	mutt	weechat
ErikBjare	zsh	xmonad/xfce4	vim	terminator	tmux		xfce4-panel		weechat
falconindy	bash	i3	vim	rxvt-unicode		ncmpcpp	conky	mutt
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
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
maximbaz	zsh	i3-gaps	neovim	kitty			py3status	thunderbird
meskarune	bash	herbstluftwm	vim	rxvt-unicode	screen		conky		weechat
neersighted	zsh	i3	vim	rxvt-unicode	tmux	ncmpcpp	htop	mutt	irssi
OK100	bash	dwm	vim	rxvt-unicode		cmus	conky, dzen	mutt	weechat
pablox-cl	zsh (zplug)	gnome3	neovim	kitty
reisub0	bash	awesome	neovim	termite		mpd	conky
sistematico	zsh/fish/bash	i3-gaps	vim/nano	termite	tmux	ncmpcpp	polybar	mutt	weechat
sitilge	zsh	awesome	neovim	termite				thunderbird
swalladge	zsh/bash	i3	neovim/vim	termite	tmux	cmus	i3pystatus	mutt
SyfiMalik	zsh	i3	vim	rxvt-unicode	tmux	ncmpcpp/mpd	polybar	mutt	weechat
thiagowfx	bash/zsh	i3	vim/emacs	rxvt-unicode		ncmpcpp	i3blocks
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
Wintervenom	bash	herbstluftwm	vim	rxvt-unicode	screen	mpd (mpc-utils)	hlwm-dzen2	mutt	weechat
wolfcore	bash	dwm	vim	rxvt-unicode	tmux	cmus	custom		weechat
zendeavor	zsh	i3	vim	rxvt-unicode	tmux	ncmpcpp	i3status		weechat

@@ Line 7: / Line 7: @@
 {{Related|X resources}}
 {{Related articles end}}
-This article collects user repositories with custom configuration files, commonly known as ''dotfiles''.
+User-specific application configuration is traditionally stored in so called [[Wikipedia:dotfile|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 your 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 [[#Tools|a dedicated tool]]). Apart from explaining how to manage your dotfiles this article also contains [[#User repositories|a list of dotfile repositories]] from Arch Linux users.
-== Version control ==
+== Tracking dotfiles directly with Git ==
-Managing dotfiles with [[version control system]]s such as [[Git]] helps to keep track of changes, share with others, and synchronize dotfiles across various hosts.
+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|host-specific configuration]] generally requires merging changes into multiple [[Git#Branching|branches]].
-=== Using gitignore ===
+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 {{man|5|gitignore}} pattern of {{ic|*}}. 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).
-Keeping a [https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository git directory] inside the home folder allows to directly keep track of changes. It is recommended to selectively add file contents to the index with {{man|1|git-add}}.
+An alternative method without these drawbacks is the "bare repository and alias method" popularized by [https://news.ycombinator.com/item?id=11070797 this Hacker News comment], which just takes three commands to set up:
-To prevent untracked files (appearing in commits and removed by {{man|1|git-clean}}), first exclude all files with {{man|5|gitignore}}:
+ $ git init --bare ~/.dotfiles
+ $ alias config='/usr/bin/git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME'
+ $ config config status.showUntrackedFiles no
-{{hc|~/.git/info/exclude|
+You can then manage your dotfiles with the created [[alias]].
-*}}
-Then use {{ic|git add -f}}, for example:
- $ git add -f ~/.config/*
-And commit the changes with {{man|1|git-commit}}:
- $ git commit -a
 {{Tip|To avoid accidentally commiting confidential information, see [[Git#Filtering confidential information]].}}
-=== Maintaining dotfiles across multiple machines ===
+== Host-specific configuration ==
-{{Style|This section needs a rewrite}}
+A common problem with synchronizing dotfiles across various machines is host-specific configuration.
-One way of maintaining dotfiles across various machines across various hosts while still allowing for per-host customizations, is 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; as shared configuration is added to the master-branch, the per-machine branches are then rebased on top of the updated master.
+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.
-The drawback on having some of the configuration files in multiple branches is that you have to remember to maintain and synchronize changes. Use conditional logic to minimize the number of machine specific files. For example, bash scripts (i.e. {{ic|.bashrc}}) can apply different configuration depending on the machine name (or type, custom variable, etc.):
+In configuration scripts like [[Command-line shell#Configuration files|shell configuration files]] conditional logic can be used. For example, [[Bash]] scripts (i.e. {{ic|.bashrc}}) can apply different configuration depending on the machine name (or type, custom variable, etc.):
-  if <nowiki>[[ "$(uname -n)" == "archlaptop" ]];</nowiki> then
+  if <nowiki>[[ "$(hostname)" == "archlaptop" ]];</nowiki> then
       # laptop specific commands here
   else
@@ Line 46: / Line 39: @@
   fi
-Another approach is to manage machine-specific configuration with tools based on template engines, e.g. [https://pypi.python.org/pypi/mir.qualia/ qualia] or [https://github.com/deadc0de6/dotdrop Dotdrop]. This approach requires less manual work and doesn't cause merge conflicts.
+Similar can also be achieved with [[.Xresources]].[https://jnrowe.github.io/articles/tips/Sharing_Xresources_between_systems.html]
+If you find rebasing Git branches too cumbersome, you may want to use a [[#Tools|tool]] that supports ''file grouping'', or if even greater flexibility is desired, a tool that does ''processing''.
 == Tools ==
@@ Line 108: / Line 103: @@
 # Supports encryption of confidential files with [[GPG]].[https://thelocehiliosan.github.io/yadm/docs/encryption]
-== Repositories ==
+== User repositories ==
 {| class="wikitable sortable" style="text-align:center"