Jump to content

# Dotfiles

4 languages

- Español
- 日本語
- Português
- 中文（简体）

From ArchWiki

Related articles

- XDG Base Directory support
- X resources

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-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
    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 | 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] (optional)
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 (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 |

## See also

- gregswiki:DotFiles
- XMonad Config Archive
- dotshare.it
- dotfiles.github.io
- terminal.sexy - Terminal color scheme designer

Categories:

- Configuration files
- Configuration management

Hidden category:

- Pages with dead links