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

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:

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.