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
Detailed Documentation
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 Tmux
Effective Vim
Cheat Sheet - Shell
Tooling Choices
- Vim
Contributors
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.

Detailed Documentation

Additional detailed guides and configuration are available:

Claude Code - Claude Code CLI configuration, plugins, and MCP servers
Transcription - Voice-to-text transcription setup and tools
Terminal - Terminal themes and configuration
Desktop - Desktop environment setup

Quick Start

Run the commands below to quickly setup or update a machine. Note that the default behaviour in all cases is to not make any changes unless the user explicitly confirms them.

# 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. Once the private files such as SSH keys are copied the
# remote will be updated to use SSH.
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, GPG, and pinentry-mac installed (all of which are installed with make setup), 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 AWS configure to create the named profile - you will be asked to provide
# an access key and secret. If this is not setup the backup/restore scripts will
# prompt you to configure.
aws configure --profile 

# 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

Profiles are in terminal/iTerm2/ and loaded as dynamic profiles:

| Profile | Purpose | |---------|---------| | dwmkerr | Default terminal | | dwmkerr-recording | No transparency, for screen recordings | | dwmkerr-agent | Agent identity, dark purple background, isolated tmux |

Install profiles:

make iterm-profiles

See identities/README.md for identity setup details.

Global preferences:

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 (Alt+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.

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

Shell configuration which is private can be kept in ~/.shell.private.d/ - this folder will be loaded by ~/.shell.sh but not checked in.

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.

Claude Code

Configuration and setup for Claude Code CLI. See claude/README.md for full details including plugins and MCP servers.

Developer Guide

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

Dotfiles

Install / Use

README