Awesome

dotfiles

This repository contains all of my configuration for MacOS and Linux, with a focus on terminal, editor, shell, programming environments etc. This repository can easily be forked to allow you to create and customise your own machine setup.

This repository also contains some handy Shell Scripts and Aliases that others might find helpful.

Some key features are:

Support for setting up a clean machine with developer focused tooling
The ability to choose what features you do or don't install
Idempotent setup, which allows you to run the setup whenever you want to add or upgrade features
Small, simple scripts to setup 'features', such as Ruby and rbenv, Python, Vim and so on
Small, simple scripts which are sourced into your shell profile, providing things like auto-completion
Management of dotfiles such as ~/.vimrc and ~/.gitconfig
Optional management of private file, such as SSH keys, as long as you have access to an AWS S3 bucket

⚠️ Warning: I have tried wherever possible to ensure no destructive change will happen when working with the scripts or commands in this project, without explicit user intervention (i.e. the user typing yes to make changes). The goal is that you can run the setup scripts without changing anything unless you explicitly choose a feature. However, I cannot guarantee I haven't made an mistakes, so please exercise caution.

Screenshot on MacOSX

Screenshot: MacOSX

Screenshot on Ubuntu

Screenshot: Ubuntu

Introduction
Quick Start
SSH Keys, GPG Keys and Private Files
MacOS - Manual Steps
- iTerm2 Configuration
Features
Developer Guide
Ubuntu Terminal Configuration
Shell Prompt Theme
Shell Scripts and Aliases
- Shell Commands
- Shell Scripts
Cheat Sheet - TMux
Cheat Sheet - Vim
Effective Vim
Cheat Sheet - Shell
Tooling Choices
- Vim
TODO

Introduction

The goal of this project is to provide a single command which will setup key features of the system. Each feature should be orthogonal and not depend on other features.

The following is set up:

zsh as the default shell
tmux for terminal multiplexing, with my preferred theme and settings
vim as the default editor, with my preferred theme and settings
~/.shell-private.d as a folder excluded from version control, the contents of which are always loaded on shell startup (ideal for project specific secrets etc)
~/.shell as a version controlled folder, the contents of which are always loaded on shell startup

Quick Start

The fastest way to setup a new machine:

# MacOSX only - install command-line tools (so that we have git).
xcode-select --install

# Create a working environment, in my standard format.
mkdir -p ~/repos/github/dwmkerr
cd ~/repos/github/dwmkerr

# Clone the dotfiles - note that a new machine will not have my SSH key
# so this is over https.
git clone https://github.com/dwmkerr/dotfiles.git
cd dotfiles

# Setup the machine - the script will run interactively.
make setup

SSH Keys, GPG Keys and Private Files

SSH Keys, GPG Keys and Private Files (such as cloud configuration files, which contain sensitive information) can be backed up and restored to a folder on AWS.

This means that to transfer sensitive information from one machine to another, you can simple run backup-private-files on the source machine, and restore-private-files on the target machine.

Backing Up Private Files

As long as your AWS profile is configured, this is a one-liner:

make private-files-backup

You will be asked for confirmation before backing up any files.

Restoring Private Files

Assuming you have the AWS CLI installed, run the following commands to create a profile (you will need credentials, which should be in the password manager):

# Restore private files:
make private-files-restore

You will be asked for confirmation before restoring any files.

Configuring Backup and Restore

The following variables can be used to configure the backup and restore process. The values shown are the defaults, so these only need to be changed if you are using a different S3 bucket or AWS profile name.

# Define the name of the AWS profile used to access the S3 bucket.
# Default is "dwmkerr".
DOTFILES_PRIVATE_PROFILE="dwmkerr" # Use whatever name makes sense for you!
# Define the name of the AWS S3 bucket that stores private files.
# Default is "dwmkerr-dotfiles-private".
DOTFILES_PRIVATE_S3_BUCKET="dwmkerr-dotfiles-private"

# Run backup/restore as normal...,
make private-files-restore
make private-files-backup

# Backup private files:
make private-files-backup

MacOS - Manual Steps

The following steps have not yet been automated:

Sign into Chrome and setup sync
Install and into Bitwarden
Open Joplin and enable S3 synchronisation (AWS credentials are in Bitwarden)
For Terminal, install the profiles under ./terminal to give the One Dark / One Light themes

iTerm2 Configuration

Install the profile under ./terminal/dwmkerrj.json which configures:

The One Dark Theme
The Window to be automatically maximised to full screen
The Left Alt key to map to Esc+

Then for the global preferences, set:

General: Selection - (Enabled) Applications in terminal may access clipboard
General: Window (Disabled) Native full screen windows
Keys: HotKey - (Enabled) Show/hide all windows with a system-wide hotkey (⌥ +Space)

These steps are work in progress.

Restore Parallels virtual machines from backup.
Restore the ~/.private/ folder from a secure backup, to bring back project specific secrets.

Some other tools I install which I have paid subscriptions for or are essentials:

Amplitube
Creative Cloud
Cyberduck
Dash
Epic Games Launcher
Guitar Pro 8

Features

Each of the 'features' listed below typically has a ./setup.d/x-<feature-name>.sh script to install or upgrade the feature. Some also have a ./.shell.d/x-<feature-name>.sh file which is sourced by interactive shells if commands need to be run on shell startup (such as enabled pyenv and similar features. The numbers are used to ensure that if there are dependencies on features, we try and install in the right order.

Private Files

Private files, such as GPG and SSH keys can be backed up or restored with the commands below:

make private-files-backup
make private-files-restore

Package Manager

Installs or upgrades Homebrew on OSX.
Updates apt on Ubuntu.
Installs and updates snap on Ubuntu.

OSX Configuration

Various preferences for OSX, such as showing the path bar on the Finder windows, smaller icons, etc.

Git

Sets up gnupg and the git user settings.

Node

Sets up nvm (Node Version Manager) and the current LTS version of node.

Python

Sets up pyenv (Python Environment Manager) and python3.

Ruby

Sets up rvm (Ruby Version Manager) and ruby.

Golang

Sets up golang and $GOPATH.

Vim

Sets up vim and vim config file. Plugins are installed with PlugInstall.

TMux

This installs tmux and the Tmux Plugin Manager.

Shell

This installs bash, zsh and sets zsh as the default shell for the user. Sets the command prompt and sources the .shell.sh file.

Installs On My Zsh, which I use for themes and some conveniences, and copies over the zsh themes.

To enable features to be used in shells, the shell configuration file will source our special shell.sh file. This file then goes and sources the appropriate files from ~/.shell.d.

OSX Applications

Many applications I used, such as WhatsApp, Visual Studio Code, T-Mux.

This also installs common CLI applications, such as tree, as well as GNU tools (coretools, gsed etc).

Commandline Tools

ag is setup and will use a global ignore file at ~/.ignore. vim-ack also uses this file.

Developer Guide

There's not much to say really, just follow the principles below:

Try to keep features orthogonal, so that they don't rely on each other
Try to remember to support bash as well as zsh
Try to remember to support Linux as well as MacOSX

Ubuntu Terminal Configuration

Set the OneDark Theme with:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/denysdovhan/gnome-terminal-one/master/one-dark.sh)"

Shell Prompt Theme

The set_ps1.sh can be used to set PS1 styles:

$ set_ps1 debian

The PS1 is converted to Z-Shell format if the current shell is zsh. My current 'default' theme is named dwmkerr.

Shell Scripts and Aliases

The following features are loaded as part of my configuration. Check the link to the source if you'd like to copy over an individual feature for your own use.

Shell Commands

The following shell commands are setup:

Command	Usage
Quick Aliases	`shell.d/aliases.sh`
`serve`	Serve the current folder over HTTP on port 3000.
`vinilla`	Open `vi` without loading the `vimrc` (i.e. vanilla configuration).
Basic Functions
`eachdir`	Run a command in each child directory.
`D`	Get the date in ISO86091 format (e.g. `2021-04-24`).
`mkd`	Make a directory, using `-p` and `cd` into it.
`restart_shell`	Restart the current shell process, useful when profile changes.
`revcut`	Cut, but in reverse (i.e. from the last to the first delimiter).
Git Functions
`ghclone`	Clone from GitHub, e.g: `ghclone dwmkerr/effective-shell`.

Shell Scripts

Script	Usage
`./scripts/test-shell.d.sh`	Source each `./shell.d` file in turn, time result. Good for checking for errors.

Cheat Sheet - TMux

Command	Usage
Sessions
`tmux detach -E 'bash --noprofile --norc`	Detach the current session and open a vanilla shell.
-------------------------------------------	-------------------------------------------------------
`<leader> R`	Reload Tmux configuration (i.e. source the `~/.tmux.conf` file).
`man tmux`	Get help on commands.
`<leader> ?`	Get help on commands.
`Ctrl + h/j/k/l`	Navigate splits (vim aware)
`Meta + h/l`	Move through tabs.
`Ctrl + Meta + h/j/k/l`	Move through tabs.
`move-window -r`	Re-order the tab numbers (useful if there are gaps).
`<leader> / S`	Show Sessions with window preview, hit `x` to delete.
`<leader> / $`	Rename session.
`new -s <name>`	New session with name.
`<leader> / Ctrl+S`	Save Tmux Session
`<leader> / Ctrl+R`	Restore Tmux Session
`<leader> /`	Last split
`<leader> {`	Swap pane left
`<leader> }`	Swap pane right

Cheat Sheet - Vim

Here's a quick reference. My <Leader> is \, so I've written shortcuts as \x rather than <Leader>x for brevity. I still need to port the above to the structure below.

Command	Usage
Custom Commands
`<leader>t`	Open current file in NERDTree.
`<leader>w`	Write buffer.
`<leader>\\`	Open buffer in new tab.
`<leader>d`	Open word under cursor in Dash.
`<leader>t`	Show current buffer in NERDTree.
`<leader>F`	Toggle focus mode.
Other Commands
`\[<Space>`	blank line above
`]<Space>`	blank line below
`sj`	Splitjoin down (i.e. split a line downwards).
`sk`	Splitjoin up (i.e. join a line upwards).
`:Tabularize /=`	Line up selection, using '='
Navigation
`gd`	Where possible, will go to a local definition. Supercharged by vim-coc.
`gd`	https://vi.stackexchange.com/questions/42414/for-vim-and-specifically-coc-vim-is-it-idomatic-to-use-gd-to-open-a-link/42415#42415
`gf`	Open file under cursor.
`gx`	Open link or address under cursor.
Spelling
`]s` and `[s`	Next/Previous spelling error.
`z=` and `zg`	Check dictionary / add to dictionary.
Markdown	Provided by `vim-markdown`
`]]` and `[[`	Next and previous headers.
`gx`	Open link in standard editor.
Focus	From `vim-goyo` and `vim-limelight`
`:Goyo`	Enter focus mode.
`:Limelight 0.8` and `:Limelight!`	Go into limelight, 80% ultra focus, and toggle limelight.
`let g:limelight_paragraph_span = 1`	Span more paragraphs in limelight.
Markdown Tables
`\tm`	Enter/Exit 'table mode', which will dynamically format markdown tables.
`ci｜`	Example of the `｜` motion for cells - i.e. 'change-in-cell'.

Note: including the vertical pipe | in the table above would cause rendering issues. So instead, the unicode character ｜ is used to illustrate the commands. Do not use the unicode character, use the normal ASCII 0x7C character.

Other useful stuff:

By default vim doesn't treat - as part of a word (for motions, search, autocomplete, etc). Use set iskeyword+=- to change this. This is the changed in my vimrc but a useful one to remember.

Effective Vim

Here's some of the stuff I find most useful.

The Golden Rule

If you repeat yourself or do dumb formatting crap, find the idiomatically correct way to do something or use a plugin. Always look up native ways first.

NerdTree

C-n to toggle/focus the tree
R in the tree to refresh
<leader>t to 'tree' the current file, i.e. show the current buffer in NerdTree.

fzf-lua

<leader>space buffers
<leader>f files
<leader>g ripgrep (works amazingly)

COC

I've barely scratched the surface and will force myself to learn more.

<leader>rn rename
gd go to definition, gr go to references
<leader>A show code actions, e.g. import missing reference
<leader>qf apply default code action, e.g. import missing reference

JavaScript, TypeScript, React

I use vim-polyglot and vim-coc with vim-tsserver - this seems to cover most of my needs without any additional plugins.

Potential Improvements

I'm looking into coc-prettier etc to make sure that auto formatting will happen if/when needed when typing, rather than blindly on save
Eliminate unneeded plugins and conf

Fuzzy Find

I'm currently using fzf-lua after spending a few years on fzf.vim. It seems lightening fast but a little harder to decipher some of the documentation. The main customisations andre:

WIP

fd is required to be installed something like this with 'fd_opts' would allow for excluding node modules etc :lua require('fzf-lua').files({ fzf_opts = {['--layout'] = 'reverse-list'} })

Split-Join

I find the sj and sk commands invaluable, until something like this becomes native it's a super useful plugin.

Vim Tab Completion

COC is used - it's basically setup like VS Code - tab selects the first option. Then <C-n> and <C-p> to cycle (or up/down).

Cheat Sheet - Shell

These are just some common commands I often forget:

Command	Usage
`tput cvvis`	Show the cursor. Useful if it disappears when a command hides it and fails to restore it.

Tooling Choices

Vim

Why Vim Plug over Vundle?

I was impressed enough with the comments on this post to make the switch, particularly as coc doesn't support Vundle, meaning I had to give Plug a try.