• Macbook Development Handbook
• Quickstart
• $HOME
• Environment Variables
• Workspaces
  • Named workspace
  • Path-based workspace
  • Other workspaces
  • Workspace types
  • Javascript
    • ts-npm-monorepo-standard
    • ts-yarn-monorepo-standard
    • ts-pnpm-monorepo-standard
    • ts-npm-single-standard
    • ts-yarn-single-standard
    • ts-pnpm-single-standard
  • Python
    • python-pip-standard
    • python-poetry-standard
    • python-conda-standard
  • Rust
    • rust-cargo-standard
  • Go
    • go-standard
  • Java
    • java-maven-standard
    • java-gradle-standard
  • C++
    • cpp-cmake-monorepo-standard
    • cpp-cmake-single-standard
  • Scala
    • scala-sbt-standard
    • scala-maven-standard
  • Kotlin
    • kotlin-gradle-standard
  • Swift
    • swift-xcode-standard
• Brew
  • Commands
• Git
  • Cheatsheet
  • Git based package management
• ITerm2
• zsh
  • Shell lifecycle
  • Configuration files
  • Variables
    • Arrays
    • Strings
    • Numeric
    • Scope and Function Handling
  • Basic Grammar
    • Simple Command
    • Redirection
    • Pipeline
    • Sublist
    • List
    • Examples
  • Conditionals
    • File Existence
    • File Attribute
    • File Comparison
    • String
    • Arithmetic
    • Options
    • Logical
  • Control Structures
  • Expansion
    • History
    • Alias
    • Process
    • Parameter
    • Command
    • Arithmetic
    • Brace
    • Filename expansion
    • Filename generation
    • Modifiers
      • Path manipulation
      • Text formatting
      • Miscellaneous
  • ZLE
  • Jobs
  • Completion system
  • Options
  • Stream manipulation
    • grep
    • sed
    • cut
    • sort
    • uniq
    • tr
    • tee
    • xargs
    • head
    • tail
    • awk
  • Filesystem
  • Process
  • Hardware and Drivers
  • OS
  • Disk
  • Networking
  • Cryptography
  • Remote access
  • Terminal
  • Compression
  • ripgrep
  • fd
  • bat
  • fzf
    • Basics
    • Field index expressions
    • Preview
    • Command execution
    • Aesthetics and layout
    • Building an fzf command
    • fzf cheatsheet
  • jq
  • exa
  • glances
  • Plugins
  • Aesthetics
• tmux
  • Sessions
  • Windows
    • Tabs
    • Temporary tools
    • Global background sessions
  • tmuxinator
  • tmux-thumbs
  • tmux-better-mouse-mode
  • Cheatsheet
• neovim
  • Configuration
  • LSP
  • Treesitter
  • Surround
  • Nerd-tree
  • Telescope
• VSCode
• Xcode
• Emacs
• Tools, LSPs, Configurations, etc.
  • C / C++ / CMake / Conan
  • Java / Maven
  • Python / pip
  • Scala / sbt
  • JavaScript / node / npm
  • Rust / cargo
  • golang
  • Haskell / cabal
  • Perl
  • Ruby / gem
  • PHP
  • C#
  • Dart / Flutter
  • Swift / Xcode
  • Kotlin / Gradle
  • Agda
  • Julia
  • Idris
  • R
  • sh / zsh
  • Lua
  • json
  • yaml
  • toml
  • xml
  • ini
  • html
  • css
  • markdown
  • latex
  • Solidity
  • Cadence
  • Move
  • protobuf
  • kubectl
  • minikube
  • Terraform
  • Helm
  • AWS
  • GCP
  • Azure
  • VirtualBox
  • Docker
  • NordVPN
  • Chrome
  • Discord
  • Slack
  • Spotify
  • Zoom
  • Google Drive
  • OneDrive
  • iCloud
• Devices

# Install base libraries from brew
brew install \
  git \
  exa \
  glances \
  btop \
  fzf \
  jq \
  tree \
  ripgrep \
  bat \
  fd \
  pstree \
  bash-completion \
  jesseduffield/lazygit/lazygit

# Other misc tools
gem install tmuxinator

# Initialize git
EMAIL="[email protected]"
ssh-keygen -t ed25519 -C "$EMAIL"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
pbcopy < ~/.ssh/id_ed25519.pub

# ssh public key is now in clipboard.
# Add it to GitHub: https://www.github.com/settings/keys

# Clone all environment files
cd ~
git clone --recurse-submodules [email protected]:siddthesquid/env.git
export ENV_HOME=~/env

# Run bootstrapping code (as needed)
. ~/env/bootstrap/source_env_in_host_configs.zsh
. ~/env/bootstrap/symlink_configs_from_host_to_env.zsh
. ~/env/bootstrap/symlink_configs_from_env_to_host.zsh
. ~/env/bootstrap/update_xdg_dirs.zsh

# Install applications. (Some things in here may be manual)
pkg_add tmux
pkg_add neovim
pkg_add glances
pkg_add btop
pkg_add nordvpn
pkg_add google-chrome
pkg_add discord
pkg_add slack
pkg_add spotify
pkg_add zoom

For reference, this is what we expect the $HOME directory to look like:

.
: # Configuration files in the home directory
├── .zshrc (sources ~/env/configs/zsh/zshrc)
├── .zshenv (sources ~/env/configs/zsh/zshenv)
├── .gitconfig -> ~/env/configs/git/.gitconfig
├── .gitignore -> ~/env/configs/git/.gitignore
├── .tmux.conf -> ~/env/configs/tmux/.tmux.conf
├── .tmuxinator -> ~/env/configs/tmux/.tmuxinator
├── .vimrc -> ~/env/configs/neovim/.vimrc
├── .ripgreprc -> ~/env/configs/ripgrep/.ripgreprc
├── .config
│   └── nvim -> ~/env/configs/neovim/nvim
:
: # Credentials and such
├── .aws
│   ├── config
│   └── credentials
├── .npmrc
├── .pypirc
├── .condarc
├── .m2
│   └── settings.xml
:
: # Our development enviornment (this repo)
├── env
│   ├── bootstrap
│   ├── configs
│   │   ├── git
│   │   ├── neovim
│   │   │   └── nvim
│   │   │       ├── lua
│   │   │       │   ├── adapters
│   │   │       │   ├── core
│   │   │       │   ├── external
│   │   │       │   ├── modules
│   │   │       │   ├── siddthesquid
│   │   │       │   └── themes
│   │   │       └── init.lua
│   │   ├── ripgrep
│   │   ├── tmux
│   │   │   ├── external
│   │   │   ├── modules
│   │   │   └── settings
│   │   └── zsh
│   │       ├── applicatiosn
│   │       ├── external
│   │       └── settings
│   ├── libraries
│   ├── local (not checked in git)
│   │   ├── .zshenv -> ~./zshenv
│   │   ├── .zshrc -> ~./zshrc
│   │   ├── .zprofile -> ~./zprofile
│   │   ├── .zlogin -> ~./zlogin
│   │   └── .zlogout -> ~./zlogout
│   ├── packages
│   └── templates
:
: # Notes and cheatsheets
├── knowledge
:
: # Virtual machines
├── vms
:
: # Services. Should be start-up and start-down automatically.
├── services
│   ├── <service-1>
│   ├── <service-2>
│   :
:
: # Open source code
├── oss
│   ├── <project-1>
│   ├── <project-2>
│   :
:
: # Custom installation directory
├── opt
│   ├── lib
│   ├── bin
│   ├── include
│   ├── share
│   ├── etc
│   ├── var
│   ├── tmp
│   └── site-functions
:
: # Temporary projects
├── sandbox
│   ├── <project-1>
│   ├── <project-2>
│   :
:
: # Primary work
├── workspace
│   ├── <organization-1>
│   │   ├── <repo-1a>
│   │   ├── <repo-1b>
│   │   :
│   ├── <organization-2>
│   :   ├── <repo-2a>
│       :
:
: # Local documents
├── documents
:
: # Downloads - could be potentially unsafe.
├── downloads
:
: # cloud
├── drive     # personal
├── public    # public
├── shared    # permissioned
:

First, we have some global environment variables set and managed by zsh itself.

LANG=en_US.UTF-8
PWD=/Users/sidd
SHELL=/bin/zsh
TERM=xterm-256color
HOME=/Users/sidd
USER=sidd
OLDPWD=/Users/sidd
PATH=...

In general, any variables that start with STS_ are specific to this devx setup. (STS stands for siddthesquid).

There are a few global variables that are exported by this repo. They can be overriden in ~/.zshenv.

export STS_ENV_HOME="${STS_ENV_HOME:-$HOME/env}"
export STS_KNOWLEDGE_HOME="${STS_KNOWLEDGE_HOME:-$HOME/knowledge}"
export STS_VMS_HOME="${STS_VMS_HOME:-$HOME/vms}"
export STS_SERVICES_HOME="${STS_SERVICES_HOME:-$HOME/services}"
export STS_OSS_HOME="${STS_OSS_HOME:-$HOME/oss}"
export STS_OPT_HOME="${STS_OPT_HOME:-$HOME/opt}"
export STS_SANDBOX_HOME="${STS_SANDBOX_HOME:-$HOME/sandbox}"
export STS_WORKSPACE_HOME="${STS_WORKSPACE_HOME:-$HOME/workspace}"

Below is some copypasta for paths within this repo for scripts to use.

# Base
STS_ENV_BOOTSTRAP="$STS_ENV_HOME/bootstrap"
STS_ENV_CONFIGS="$STS_ENV_HOME/configs"
STS_ENV_LIBRARIES="$STS_ENV_HOME/libraries"
STS_ENV_PACKAGES="$STS_ENV_HOME/packages"

# Config
STS_ENV_CONFIGS_GIT="$STS_ENV_CONFIGS/git"
STS_ENV_CONFIGS_NEOVIM="$STS_ENV_CONFIGS/neovim"
STS_ENV_CONFIGS_RIPGREP="$STS_ENV_CONFIGS/ripgrep"
STS_ENV_CONFIGS_TMUX="$STS_ENV_CONFIGS/tmux"
STS_ENV_CONFIGS_ZSH="$STS_ENV_CONFIGS/zsh"

# Zsh specific
STS_ENV_ZSH_APPLICATIONS="$STS_ENV_CONFIGS_ZSH/applications"
STS_ENV_ZSH_SETTINGS="$STS_ENV_CONFIGS_ZSH/settings"
STS_ENV_ZSH_EXTERNAL="$STS_ENV_CONFIGS_ZSH/external"

# tmux specific
STS_TMUX_EXTERNAL="$STS_ENV_CONFIGS_TMUX/external"
STS_TMUX_SETTINGS="$STS_ENV_CONFIGS_TMUX/settings"
STS_TMUX_MODULES="$STS_ENV_CONFIGS_TMUX/modules"

And then we have some variables that are specific to tmux sessions. We can use them in scripts that assume they are running in a tmux session. The values below are examples.

# Managed by tmux
TMUX=/private/tmp/tmux-501/default,19725,
TMUX_PANE=%19

# Custom - these should not change
STS_SESSION_WORKSPACE="~/workspace/some-org/some-repo"
STS_SESSION_TYPE="ts-pnpm-monorepo"

Whenever we want to work on a project, we can either open a named or path-based workspace. Each tmux session is named based on the root directory. This way, we won't accidentally open multiple sessions in the same directory.

The below table has all of the named workspaces. They would each get their own tmux session and be named accordingly.

background is a tmux session that will never be attached to directly. We will use it to pop-up over other sessions for quick access to certain persistent windows. The below table lists the background projects. They would each get their own tmux window and be named accordingly.

Certain directories (as listed in the below table) are marked as valid workspaces, meaning that launching a session in any of these directories will automatically open (or reopen) tmux in the root directory of the workspace. These session names will start with either ~/ or / depending on the path.

If we want to open a session in a directory not listed above, we have two options:

• Open a session with cwd as the current directory
• Find the rootmost folder (with ~ or / prefix) that is a valid workspace and open a session in that directory
• Find the first folder that is a valid package (which could be a subfolder in a larger workspace) or workspace

In general, care is needed to make sure two sessions aren't opening the same files for editing.

We want to configure some tmux and neovim settings specific to the type of repo/workspace we are working with. This section details the different types of sessions we care about. We care about

• what identifies a session as a particular type
• tmux specific bindings and configurations
• neovim LSPs and diagnostics tools
• during which lifecycle events we want to run certain scripts

We will rely on Brew to install most packages. Packages are installed in /usr/local/Cellar and symlinked to /usr/local/bin. We will also use Brew to manage services.

We've already installed git in quickstart. Let's look at how it's been customized for productivity.

~/.gitconfig -> ~/env/configs/git/.gitconfig has a number of aliases and configurations. Below is a quick cheatsheet.

We want a consistent and repeatable workflow when installing stuff from git. Packages will roughly have the following overall lifecycle, where possible:

graph LR
    CLEAN -- "ADD" --> DOWNLOADED
    DOWNLOADED -- "BUILD" --> BUILT
    BUILT -- "INSTALL" --> INSTALLED
    INSTALLED -- "LOAD COMPLETION" --> COMPLETABLE
    INSTALLED -- "USE" --> INSTALLED
    COMPLETABLE -- "REMOVE COMPLETION" --> INSTALLED
    INSTALLED -- "UNINSTALL" --> BUILT
    BUILT -- "REMOVE" --> CLEAN

• We need a way of checking what state we are in
• Version numbers are required
• Calling a function should invoke all previous functions, if not invoked

The process roughly looks as follows:

1. Clone the repo
2. Checkout a particular version or branch
3. Build
4. Copy artifacts to $INSTALL_DIR/<project>-<version>
5. Symlink $INSTALL_DIR/<project> to $INSTALL_DIR/<project>-<version>

zsh...

• is a shell interpreter. It is a "shell" over the OS kernel, giving a user low-level access to (more-or-less) whatever the computer hardware can do, all via the command line
• is a process that attaches (stdin, stdout, stderr) to a TTY/terminal, which is another process
• parses bytes sequences sent to it from the terminal/terminal emulator, processes them, and then hands the output back to the terminal, potentially with ANSI escape sequences for compliant terminals to interpret
• manages environment variables, which can be inherited by other programs, scripts, or subshells
• provides a complete, though quirky, programming language, which allows aliases, functions, and scripts to be written
• can spawn and manage other processes (or jobs)
• provides useful DevX tooling like compinit (completion) and ZLE (zsh line editor)
• alternatives include sh, ksh, bash, csh, and fish. but we will use zsh as it is feature rich and has good adoption.

zsh is singlethreaded - it runs one command after another. In between commands, we can query the environment for it's current state. A command can

zsh can be run in a number of contexts

• login shell provided by OS (accessible in Linux)
• launching terminal gives you a default shell
• tmux panes
• script launched from within zsh
• as a script from some other application

In all cases, the shell processes commands on a single thread. Commands can take the form of

• builtins
• functions
• scripts
• binaries (on PATH)

zsh can be configured based on whether it is a login or interactive shell.

Interactive - If zsh is launched in interactive mode, that means the user is typing the commands into the shell. Otherwise, a file must be provided. We can check if zsh is running interactively with

[[ -o interactive ]]

Login - zsh can also be launched in login mode. All that practically means is that it will source ~/.zprofile instead of ~/.zshrc. We can check if zsh is running in login mode with

[[ -o login ]]

Based on the above properties, we know which files will be sourced.

Generally, we only need to use

• ~/.zshenv for configuring PATH, *_HOME, and fpath
• ~/.zshrc for interactive shell usage

The shell manages a number of variables during its life. For any process, an environment variable is a key value string pair. However, with zsh, we can add supplemental attributes to variables, which limits how the variables can be modified and represented.

Shells process

• lists: which are a sequence of sublists
• sublists: which are a sequence of pipelines
• pipelines: which are a sequence of commands
• commands: which are a sequence of words

A simple command in Zsh is a basic unit of execution.

FOO=bar echo $FOO

A pipeline connects the output of one command to the input of another.

A sublist is a sequence of pipelines with conditional execution.

A list is a sequence of sublists with various terminators.

# Simple Command Example
echo foo # Echoes the word 'foo'.

# Pipeline Example
echo foo | sed 's/foo/bar/' # Replaces 'foo' with 'bar' in the output of echo.

# Sublist Example
dmesg | grep panic && print yes # Prints 'yes' if 'panic' is found in `dmesg` output.

# List Example
command1; command2 & command3 # `command1` then `command2` (foreground), and `command3` (background).

Let's suppose a string of text has been submitted to zsh for processing. A series of expansions will happen before it's tokenized into words and processed. These expansions happen in the following order:

1. History
2. Alias
3. Process, parameter, command, arithmetic, and brace (left to right)
4. Filename expansion
5. FIlename generation

ripgrep replaces grep. It's faster to use, and respects .gitignore files by default. The configuration file is ~/.ripgreprc -> ~/env/configs/ripgrep/.ripgreprc (as set by RIPGREP_CONFIG_PATH) and contains some basic settings.

fzf provides a fuzzy finder interface for a given list of strings. It's features include

• fuzzy search through any list of strings
• multi-select
• preview window with custom commands and syntax highlighting
• keybindings and events for custom behavior
• customizable UI

For our development environment, we will try to keep the convention of having fzf based commands launched with tmux popups and have a specific purpose, with carefully picked keybindings and helpful previews. This way, we can keep the UI standardized.

At its core, fzf is inputs a list of strings and outputs a list of selected strings based on a sequence of regex filters. fzf allows a few filtering strategies:

We can choose how to format and search the input list by specifying a regex delimiter and using field index expressions to select the fields at certain indices. The below are the relevant flags:

We can customize the borders, colors, and layout of the fzf window. We will generally try to keep these consistent as much as possible. The biggest questions we want to answer are:

• do we want this to be a tmux popup or inline in the terminal?
  • popup: can be called from anywhere, but output must target an existing pane
  • cli: output is persistent and can be called asynchronously, but must be called from a specific pane
• should the preview, if any, be on the right or bottom?
  • right side: more space for multiline preview
  • bottom: show more details for active selection

When designing an fzf function, we need to figure out

1. the goal of our function
2. the desired layout
3. default source of inputs and initial filters
4. which fields of the input to actually display
5. which fields of the input to limit the search to
6. whether multi-select is applicable
7. the text filter algorithm
8. what the preview window should look like
9. how selected text should be transformed on completion
10. what to do with the selected text on completion
11. how keybindings affect the input list
12. which keybindings perform what operations on selected text
13. how keybindings affect the preview window (if applicable)

In our libraries folder, we've predefined a few fzf commands. The below is a quick reference, along with possible tmux bindings to launch them.

• zsh-autosuggestions
• zsh-syntax-highlighting
• zsh-completions

There are four types of sessions we care about:

• default
• project/workspace
• IDE integrated
• remote access

When loading the terminal, we automatically attach to the default session, or create it if it does not exist.

Certain folders will be marked as valid project/workspace directories. We can also choose any arbitrary directory to be a project/workspace directory through some provided command.

When we ssh into a remote machine, we automatically attach to the remote session, or create it if it does not exist.

• Development
• Main Terminal shell
• Custom shells
• Files
• Services
• Tasks
• Git
• Package Management
• Scratchpad

• Utility functions
• Monitor
• Process

• Knowledge
• Env

nvim is our text editor of choice. It runs on the terminal and is configurable.

In our nvim setup, we attach a single nvim instance to facilitate all textual editing for any given "project". The below step-by-step gives a rough idea of how this works:

1. Open nvim on either a single file or directory
2. Determine the root directory of the project
3. Determine the type of workspace based on files and their contents
4. Load all configurations associated with the workspace type

So for example, nvim might find a package.json in the root directory and understand that it's a PNPM monorepo root. It will then load all configurations associated with PNPM monorepo workspaces. Configurations include things like keybindings, LSPs, linters, formatters, etc.

Each tmux session ideally represents a single project or workspace, and every project is associated with a root directory. This means that whenever we open a tmux session, we can automatically open nvim in the root directory of the project.

• Mouse

  • Trackpad
  • Multiple mice

• Keyboard

  • Built-in
  • Multiple keyboards

• Monitors

  • Laptop
  • External
  • iPad

• Video In

  • Built-in Camera
  • Camera
  • Virtual Camera Filter
  • Screen

• Audio Out

  • Wireless Headphones
  • Wired Headphones
  • Built-in Speakers
  • External Speakers
  • Airpods

• Audio In

  • Built-in Microphone
  • External Microphone
  • Virtual Microphone
  • Audio Interface
  • Airpods

• WiFi

• Network

• Bluetooth

• iPhone

• iPad

• Vision

• AirPods