Cheong’s dotfiles

These are the base dotfiles that I start with when I set up a new environment (for more specific local needs I use the *.local files).

Table of Contents

• 🔧 Setup
• 📸 Screenshots
  • 🔁 Git
  • ⌨️ tmux & Vim
• 💄 Customize
  • 🌐 Local Settings
    • 🐚 ~/.bash.local
    • 🔁 ~/.gitconfig.local
    • ⌨️ ~/.vimrc.local
• ↕️ Update
• 🔍 Tips and Tricks
  • 🤔 How to test dotfiles?
  • 🔥 How to wipe freespace on macbook hard drive?
  • 🔎 How to see currently defined aliases and functions?
  • 📝 Commonly used aliases/functions
• ❓ FAQs
  • 🤔 Should you install XtraFinder?
• 🙏 Acknowledgements
• 📚 References
• 📑 License

Setup

Caution

DO NOT run the setup script if you do not fully understand what it does. Seriously, DON'T!

To set up the dotfiles:

1. Grant full disk access to the 'Terminal Application' in 'System Preferences > Privacy & Security > Full Disk Access'. Otherwise, there will be issues with the customization of preferences.

2. Run the appropriate snippet in the terminal:

   With confirmation prompts?	Snippet
   Yes	bash -c "$(curl -LsS https://raw.github.com/wingy3181/dotfiles/main/src/os/setup.sh)"
   No	bash -c "$(curl -LsS https://raw.github.com/wingy3181/dotfiles/main/src/os/setup.sh) -y"

   That's it! ✨

   The setup process will:

   • Download the dotfiles on your computer (by default it will suggest ~/.dotfiles).
   • Create some additional directories
   • Symlink the Git, shell, tmux, and Vim related files.
   • Install applications / command-line tools for macOS.
   • Set custom macOS preferences.
   • Install Vim plugins.

Setup process in action:

setup-process-in-action.mp4

Screenshots

Git

Output for git status:

Output for git log:

tmux & Vim

Customize

Environment Variables

The dotfiles can be controlled during the installation by using the following environment variables (This is mainly used for the GitHub Actions CI build):

DOTFILES_DEBUG_MODE

If the DOTFILES_DEBUG_MODE environment variable is set to true, it will output the standard out and error of the internal commands of each step to console.

Otherwise, it will execute them quietly/silently.

INSTALL_APPLICATION_IF_READABLE_NAME_MATCH_REGEX

If the INSTALL_APPLICATION_IF_READABLE_NAME_MATCH_REGEX environment variable is set, it will be used as a regular expression against the application's readable name (in .\src\os\macos\installs\install_apps.sh) and will only be installed if it matches.

This is used to split the GitHub Actions CI build into multiple jobs so that it doesn't exceed the usage limits

Local Settings

The dotfiles can be easily extended to suit additional local requirements by using the following files:

~/.bash.local

The ~/.bash.local file will be automatically sourced after all the other Bash related files, thus, allowing its content to add to or overwrite the existing aliases, settings, PATH, etc.

Here is an example:

#!/bin/bash

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

# Set PATH additions.

PATH="/Users/wingy3181/projects/dotfiles/src/bin/:$PATH"

export PATH

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

# Set local aliases.

alias g="git"

~/.gitconfig.local

The ~/.gitconfig.local file will be automatically included after the configurations from ~/.gitconfig, thus, allowing its content to overwrite or add to the existing Git configurations.

Note: Use ~/.gitconfig.local to store sensitive information such as the Git user credentials, e.g.:

[commit]

    # Sign commits using GPG.
    # https://help.github.com/articles/signing-commits-using-gpg/

    gpgSign = true

[user]

    name = Cheong Yip
    email = account@example.com
    signingkey = XXXXXXXX

~/.vimrc.local

The ~/.vimrc.local file will be automatically sourced after ~/.vimrc, thus, allowing its content to add or overwrite the settings from ~/.vimrc.

Here is an example:

" Disable arrow keys in insert mode.

inoremap <Down>  <ESC>:echoe "Use j"<CR>
inoremap <Left>  <ESC>:echoe "Use h"<CR>
inoremap <Right> <ESC>:echoe "Use l"<CR>
inoremap <Up>    <ESC>:echoe "Use k"<CR>

" Disable arrow keys in normal mode.

nnoremap <Down>  :echoe "Use j"<CR>
nnoremap <Left>  :echoe "Use h"<CR>
nnoremap <Right> :echoe "Use l"<CR>
nnoremap <Up>    :echoe "Use k"<CR>

Update

To update the dotfiles you can either run the setup script or, if you want to update one particular part, run the appropriate os script.

Tips and Tricks

How to test dotfiles?

Method 1: Using GitHub Actions

1. Use either workflows:
   1. Manual (source)
   2. Scheduled (source)

Method 2: Using a Virtual Machine

1. Install UTM on macOS
2. Download the macOS image
3. Create a new VM in UTM using the downloaded macOS image
4. (Optional) Before running and starting the VM, move the image to an external SSD.
5. Run the VM and install the dotfiles as per the setup instructions.
6. Within the macOS virtual machine due to the limitation of signing into your Apple ID account, XCode needs to be manually downloaded and installed from here.

How to wipe freespace on macbook hard drive?

Run the command diskutil secureErase freespace 3 /Volumes/Macintosh\ HD

• https://www.backblaze.com/blog/how-to-wipe-a-mac-hard-drive/

How to see currently defined aliases and functions?

Aliases

dotfiles\src\shell\bash_aliases
dotfiles\src\shell\macos\bash_aliases
~\.bash_it\aliases\enabled\*.plugin.bash

• alias - show aliases and their definitions (including bash-it enabled aliases)
• bash-it show aliases - show aliases enabled via bash-it

Functions

dotfiles\src\shell\bash_functions
~\.bash_it\plugins\enabled\*.plugin.bash

• declare -F - list name of all functions defined (source)
• type <function name> - show function definition
• glossary - show functions enabled via bash-it with short description of each function
• bash-it show <completions | plugins> - show completions/plugins enabled via bash-it

Commonly used aliases/functions

• afk - Lock computer
• datauri - Create data URI from a file
• delete-files <file-pattern> - Delete files that match a certain pattern from the current directory. This lists the files deleted via the -ls option
• empty-trash - Empty the trash, the main HDD, all mounted volumes clear Apple's system logs to improve shell startup speed and clear history of files downloaded (logged internally in macOS)
• git sc <search-text> - Search commits by source code
• git sm <search-text> - Search commits by commit message
• ip - Show external ip address
• local-ip - Show local internal ip address
• sh <search=text> - Search history
• st <searchtext> - Search for text recursively within the current directory

FAQs

Should you install XtraFinder?

XtraFinder is a Finder add-on that adds tabs and cut/paste functionality to Finder. It is not available on the App Store and requires you to disable System Integrity Protection (SIP) in order to install it.

SIP is a security feature that prevents malicious software from modifying protected files and folders on your Mac. It is not recommended to disable SIP unless you know what you are doing and are willing to compromise your system's security

For more information, see the following documentations:

• https://www.trankynam.com/xtrafinder/doc/
• https://support.apple.com/en-us/102149

There are scripts to optionally install XtraFinder and custom preferences for it in the dotfiles. However, it is not recommended to install it due to the security risks mentioned.

Acknowledgements

A majority of this code is taken from Cătălin Mariș' dotfiles.

Inspiration and code was taken from many sources, including:

• Mathias Bynens' dotfiles
• Cătălin Mariș' dotfiles
• Zach Holman's dotfiles
• Paul Miller's dotfiles
• Adam Eivy's dotfiles
• Simon Owen's dotfiles
• Paul Irish's dotfiles
• Sourabh Bajaj's "Mac OS X Setup Guide"
• Ryan Winchester's "Set up OS X for Web Development in 10 Minutes".

References

dotfiles

• GitHub does dotfiles
• Awesome dotfiles
• Setting Up a Mac Dev Machine From Zero to Hero With Dotfiles.

License

The code is available under the MIT license.