~/.Dotfiles

$HOME, sweet $HOME

My dotfiles for configuring Vim, ZSH, Tmux, Git, etc

Contents

• Introduction to Dotfiles
  • What are dotfiles?
  • Dotfile Management Systems
  • So copy paste, right?
  • XDG Directories
  • Applying Dotfiles
  • Containerized Userspace
  • Security
• My Dots
  • Setup
  • Directory Structure
  • Configuring
  • Aliases
  • Utilities
  • Packages
  • ZSH
  • Vim
  • Tmux
  • Git
  • Dependencies

Intro

What are dotfiles?

One of the beautiful things about Linux, is how easily customizable everything is. Usually these custom configurations are stored in files that start with a dot (hence dotfiles!), and typically located in your users home ~, or better yet ~/.config (even this can be customized, for apps that respect the XDG Base Directory spec). Some examples of dotfiles that you're likely already familiar with include .gitconfig, .zshrc or .vimrc.

You will often find yourself tweaking your configs over time, so that your system perfectly matches your needs. It makes sense to back these files up, so that you don't need to set everything up from scratch each time you enter a new environment. Git is a near-perfect system for this, as it allows for easy roll-backs, branches and it's well supported with plenty of hosting options (like here on GitHub).

Once everything's setup, you'll be able to SSH into a fresh system or reinstall your OS, then just run your script and go from zero to feeling at right at home within a minute or two.

It's not hard to create your own dotfile repo, it's great fun and you'll learn a ton along the way!

Dotfile Management Systems

You can make things simple, or complex as you like.

The two most common methods are either symlinking, or using a git bare repo, these are explained in more detail in the Applying Dotfiles section. You can either do things manually, write a simple script, or use a pre-build dotfile management system (like dotbot, chezmoi, yadm or GNU Stow).

In terms of managing dependencies, using either git submodules or git subtree will let you keep dependencies in your project, while also separate from your own code and easily updatable.

So copy paste, right?

Zach Holman wrote a great article titled Dotfiles Are Meant to Be Forked. I personally disagree with this, since your dotfiles are ususally highly personalized, so what's right for one developer, likely won't be what someone else is looking for. They're also usually something you build up over time, and althgouh some repos may provide a great starting point, it's really important to know what everything does, and how it works.

By all means feel free to take what you want from mine. I've taken care to ensure that each file is standalone, and well documented so that certain files can just be dropped into any system. But I cannot stress enough the importance of reading through files to ensure it's actually what you want.

If you're looking for some more example dotfile repos to get you started, I can highly recomend taking a look at: holman.

There's even more to check out at webpro/awesome-dotfiles, dotfiles.github.io and r/unixporn.

XDG Directories

One of my goals was to try and keep the top-level user home directory as clean as possible by honouring the XDG base directory specification, which lets you specify the locations for config, cache, data, log and other files. This is done by setting environmental variables within .zshenv.

You can modify any of these values, but by default the following paths are used:

Applying Dotfiles

There are several different approaches to managing dotfiles. The two most common would be either symlinking, or git bare repo.

Option 1 - Symlinking

Symlinks let you maintain all your dotfiles in a working directory, and then link them to the appropriate places on disk, sort of like shortcuts.

For example, if your dotfiles are in ~/Documents/dotfiles, you could create a zshrc file there, and link it with:

ln -s ~/Documents/dotfiles/zsh/.zshrc ~/.zshrc

This would obviously get cumbersome very quickly if you had a lot of files, so you would really want to automate this process. You could either create your own script to do this, or use a tool specifically designed for this.

I personally use Dotbot, as it doesn't have any dependencies - just include it as a sub-module, define a list of links in a simple YAML file, and hit go. GNU Stow is also a popular choice, and it's usage is explained well in this article by Alex Pearce. There's many other tools which do a similar thing, like Homesick, Rcm, dotdrop or mackup.

Option 2 - Git Bare Repo

Bare repositories let you add files from anywhere on your system, maintaining the original directory structure, and without the need for symlinks (learn more). Just initiialize or clone using the --bare flag, then add a global alias to manage files with git.

# Initialise a new repo, or clone an existing one with the --bare flag
git init --bare $HOME/dotfiles

# Next create an alias that sets the directory to your dotfile (add to .zshrc/ .bashrc)
alias dotfiles='$(where git) --git-dir=$HOME/dotfiles/ --work-tree=$HOME'

# Hide untracked files
dotfiles config --local status.showUntrackedFiles no

Then, from anywhere in your system you can use your newly created alias to add, commit and push files to your repo using all the normal git commands, as well as pull them down onto another system.

dotfiles add ~/.config/my-file
dotfiles commit -m "A short message"
dotfiles push

Both Chezmoi and YADM are a dotfile management tools, which wrap bare git repo functionality, adding some additional QoL features.

To learn more, DistroTube made an excellent video about bare git repos, and Marcel Krčah has written a post outlining the benefits.

Containerized Userspace

You can also containerize your dotfiles, meaning with a single command, you can spin up a fresh virtual environment on any system, and immediately feel right at home with all your packages and configurations.

This is awesome for a number of reasons: 1) Super minimal dependency installation on the host 2) Blazing fast, as you can pull your built image from a registry, instead of compiling everything locally 3) Cross-platform compatibility, whatever your host OS is, you can always have a familiar Linux system in the container 4) Security, you can control which host resources are accessible within each container

For this, I'm using an Alpine-based Docker container defined in the Dockerfile, to try it out, just run docker run lissy93/dotfiles.

Other options could include spinning up VMs with a predefined config, either using something like Vagrant or a NixOS-based config.

Security

Something that is important to keep in mind, is security. Often you may have some personal info included in some of your dotfiles. Before storing anything on the internet, double check there's no sensitive info, SSH keys, API keys or plaintext passwords. If you're using git, then any files you wouldn't want to be commited, can just be listed in your .gitignore. If any .gitignore'd files are imported by other files, be sure to check they exist, so you don't get errors when cloning onto a fresh system.

Another solution, is to encrypt sensitive info. A great tool for this is pass as it makes GPG-encrypting passwords very easy (this article outlines how), or you could also just use plain old GPG (as outlined in this article).

My Dotfiles

Note This repo is still a work in progress

Setup

Warning Prior to running the setup script, read through everything and confirm it's what you want.

Let's Go!

bash <(curl -s https://raw.githubusercontent.com/Lissy93/dotfiles/master/lets-go.sh)

This will execute the quick setup script (in lets-go.sh), which just clones the repo (if not yet present), then executes the install.sh script. You can re-run this at anytime to update the dotfiles. You can also optionally pass in some variables to change the install location (DOTFILES_DIR) and source repo (DOTFILES_REPO) to use your fork.

The install script is idempotent, it can be run multiple times without changing the result, beyond the initial application. It will take care of checking that all dependencies are present, and will prompt the user to install missing packages, using the appropriate package manager (currently supports brew, pacman, apt and pkg). The install script takes care of installing / updating ZSH, Tmux and Vim all plugins.

Alternatively, you can clone the repo yourself, cd into it, allow execution of install.sh then run it to install or update.

git clone --recursive [email protected]:Lissy93/dotfiles.git ~/.dotfiles
chmod +x ~/.dotfiles/install.sh
~/.dotfiles/install.sh

Directory Structure

~
└── .
    ├── bash/
    ├── tmux/
    ├── vim/
    ├── zsh/
    ├── .github/
    ├── lets-go.sh
    └── install.sh
    └── symlinks.yml

Configuring

The locations for all symlinks are defined in .install.conf.yaml. These are managed using Dotbot, and will be applied whenever you run the install.sh script. The symlinks set locations based on XDG paths, all of which are defined in .zshenv.

The bootstrap configurations are idempotent (and so the installer can be run multiple times without causing any problems). To only install certain parts of the config, pass the --only flag to the install.sh script, similarly --except can be used to exclude certain directives.

Aliases

Into to Aliases

An alias is simply a command shortcut. These are very useful for shortening long or frequently used commands.

For example, if you often find yourself typing git add . you could add an alias like alias gaa='git add .', then just type gaa. You can also override existing commands, for example to always show hidden files with ls you could set alias ls='ls -a'.

Aliases should almost always be created at the user-level, and then sourced from your shell config file (usually .bashrc or .zshrc). System-wide aliases would be sourced from /etc/profile. Don't forget that for your changes to take effect, you'll need to restart your shell, or re-source the file containing your aliases, e.g. source ~/.zshrc.

You can view a list of defined aliases by running alias, or search for a specific alias with alias | grep 'search-term'. The unalias command is used for removing aliases.

My Aliases

All aliases in my dotfiles are categorised into files located in zsh/aliases/ which are imported in zsh/.zshrc.

The following section lists all (or most) the aliases by category:

Utilities

The dotfiles also contains several handy bash scripts to carry out useful tasks with slightly more ease.

Each of these scripts is standalone, without any dependencies, and can be executed directly to use. Alternatively, they can be sourced from within a .zshrc / .bashrc, for use anywhere via their alias.

For usage instructions about any of them, just append the --help flag.

• Transfer - Quickly transfer files or folders to the internet
• Web Search - Open a specific search engine with a given query
• QR Code - Generates a QR code for a given string, to transfer data to mobile device
• Weather - Shows current and forecasted weather for your location
• Color Map - Just outputs your terminal emulators supported color pallete
• Welcome - Used for first login, prints personalised greeting, system info, and other handy info
• Online - Checks if you are connected to the internet

Transfer

Quickly transfer a file, group of files or directory via the transfer.sh service.
To get started, run transfer <file(s) / folder>, for more info, run transfer --help

If multiple files are passed in, they will automatically be compressed into an archive. You can change the file transfer service, or use a self-hosted instance by setting the URL in FILE_TRANSFER_SERVICE The file can be either run directly, or sourced in your .zshrc and used via the transfer alias.

For info, run transfer --help
Source: utils/transfer.sh

Web Search

Quickly open web search results for a given query using a selected search engine. To get started, run web-search, or web-search --help for more info.

Usage:

All parameters are optional, to get started just run web-search or web-search <search provider (optional)> <query (optional)>, the ws alias can also be used. If a search engine isn't specified, you'll be prompted to select one from the list. Similarly, if a query hasn't been included you'll be asked for that too.

• web-search - Opens interactive menu, you'll be prompted to select a search engine from the list then enter your query
• web-search <search term> - Specify a search term, and you'll be prompted to select the search engine
  • For example, web-search Hello World!
• web-search <search engine> - Specify a search engine, and you'll be prompted for your search term
  • For example, web-search duckduckgo
• web-search <search engine> <search engine> - Specify both a search engine and query, and results will open immediately
  • For example, web-search wikipedia Matrix Defense

The alias ws will also resolve to web-search, if it's not already in use. You can either run the script directly, e.g.~/.config/utils/web-search.sh (don't forget to chmod +x the file first, to make it executable), or use the web-search / ws alias anywhere, once it has been source'd from your .zshrc.

For info, run web-search --help
Source: utils/web-search.sh

bash <(curl -s https://raw.githubusercontent.com/Lissy93/dotfiles/master/utils/web-search.sh)

Packages

The dotfiles can also optionally install any packages that you may need. This is useful for quickly setting up new systems, but it's important that you remove / comment out any packages that you don't need.

The list of software is stored in the installs/ directory, and the file that's used will vary depending on the host operating system.

• Arch (and Arch-based systems, like Manjaro) - uses pacman
• Debian (and Debian-based systems, like Ubuntu) - uses apt
• Alpine - uses apk
• Mac OS - .Brewfile uses Homebrew
• Windows - windows.sh uses winget and scoop

ZSH

// TODO

Vim

The entry point for the Vim config is the vimrc, but the main editor settings are defined in vim/editor.vim

Vim Plugins

Vim plugins are managed using Plug defined in vim/plugins.vim. To install them from GitHub, run :PlugInstall (see options) from within Vim. They will also be installed or updated when you run the main dotfiles setup script (install.sh).

The following plugins are being used:

Tmux

Fairly standard Tmux configuration, strongly based off Tmux-sensible. Configuration is defined in .tmux.conf

Tmux plugins are managed using TMP and defined in .tmux.conf. To install them from GitHub, run prefix + I from within Tmux, and they will be cloned int ~/.tmux/plugins/.

Plugins

• Tmux-sensible: tmux-plugins/tmux-sensible - General, sensible Tmux config
• Tmux-continuum: tmux-plugins/tmux-continuum - Continuously saves and environment with automatic restore
• Tmux-yank: tmux-plugins/tmux-yank - Allows access to system clipboard
• Tmux-prefix-highlight: tmux-plugins/tmux-prefix-highlight - Highlight Tmux prefix key when pressed
• Tmux-online-status: tmux-plugins/tmux-online-status - Displays network status
• Tmux-open: tmux-plugins/tmux-open - Bindings for quick opening selected path/ url
• Tmux-mem-cpu-load: thewtex/tmux-mem-cpu-load - Shows system resources

Git

// TODO

Dependencies

These dot files make use of the following packages, and hence they are required

• zsh - Interactive Shell
• nvim - Extensible Vim-based text editor
• tmux - Detachable terminal multiplexer
• ranger - CLI-based file manager with VI bindings
• git - Version control system

They can be easily installed/ updated with your package manger, e.g:

• Ubuntu Server: sudo apt install -y zsh neovim tmux ranger git
• Arch Linux: sudo pacman -S zsh neovim tmux ranger git
• Alpine: apk add zsh neovim tmux ranger git
• MacOS: brew install zsh neovim tmux ranger git

Depending on your setup, the following utils may also be required: make, ctags, fzf and python3-pip