# Environments Handbook

I switched contexts a lot when using technologies, either for work or personal projects, constantly remembering my existing config are overwhelming

Primarily for personal guide.

---

# Essentials

* I moved from WebStorm to use VSCode. As it’s getting too slow to handle medium-sized monorepo while waiting Windows stable build for [Zed](https://zed.dev/)
    
* [Berkeley Mono Typeface](https://berkeleygraphics.com/typefaces/berkeley-mono/)
    
* [**Bitwarden**](https://bitwarden.com/)
    

---

# Windows

## Terminal

Enhanced `cmd.exe` by defining couple aliases, saved in `%userprofile%\alias.cmd`. Private alias.cmd is used

### GNU utilities

Git for Windows is built on top of *patched* MSYS2 to make git works better in Windows pathing system, they also ship small subsets of familiar GNU utilities like `ls`, `mkdir`, etc built to work for Windows, to make this available via terminal, I exposed `C:\Program Files\Git\usr\bin` path which contains such executables.

> Due to requirement of C family toolchains, for example `gcc`, MSYS2 is used to provides this toolchain in Windows. Default install `C:\msys64`.
> 
> Note: make sure to provide paths for MSYS2 binaries **BEFORE** Git for Windows to as Git for Windows to prevent common executable conflicts.

Other than that, it's generally preferred to use binaries from Git for Windows because of the likelihood of its included binaries has been patched to handle Windows pathing system better.

**Caveat!** Git for Windows and MSYS2 binaries paths might also contain executables that are natively included by Windows (example: `ssh`), using Windows built-in binaries are typically always preferred.

To make interop easier to deal with, **make sure to expose these built-in binaries paths BEFORE MSYS2 and Git for Windows**. Check interop correctness especially for `gpg` by GnuPG and `ssh` from built-in OpenSSH.

## Tooling

1. [Rapid Environment Variables](https://www.rapidee.com/en/about)
    
2. [WizTree](https://diskanalyzer.com/)
    

## Useful Fixes for Windows

1. [Missing UWP Icons due to Google Drive File Streams](https://superuser.com/questions/1319157/some-windows-10-uwp-icons-not-displaying-on-search-or-in-settings)
    

---

# MacOS

[homebrew](https://brew.sh/) as main package manager

## Terminal

> This terminal section also applies for WSL2

MacOS has been shipping `zsh` by default, I avoid bloating my terminal with too many plugins, fast startup and staying lightweight are preferred.

> Set `zsh` as default sh for WSL2: `chsh -s $(which zsh)`

Setup: [install zdharma-continuum/zinit](https://github.com/zdharma-continuum/zinit?tab=readme-ov-file) and configure

```plaintext
# Remove defualt ~/.zshrc that might be created during your first `zsh` run
# Add to ~/.zshrc after installing zdharma-continuum/zinit
# After the `Zinit` autoload block

zinit for \
    light-mode \
  zsh-users/zsh-autosuggestions \
    light-mode \
  zdharma-continuum/fast-syntax-highlighting \
  zdharma-continuum/history-search-multi-word \
    light-mode \
    pick"async.zsh" \
    src"pure.zsh" \
  sindresorhus/pure
```

> In WSL2, syntax-highlight have performance issues due the inclusion of Windows paths by default. To improve performance, excluding Windows paths can be done by following [this](https://github.com/zsh-users/zsh-syntax-highlighting/issues/790). But following the guide might also remove desired binaries from system path, e.g `code` for VSCode. It can be added back by creating function that act as alias that handle arguments passing.

```bash
# .zshrc
code() {
    /mnt/c/Program\ Files/Microsoft\ VS\ Code/bin/code "$@"
}
```

---

# Language

## Java

* Adoptium JDK 21 via Homebrew for MacOS, directly on Windows
    

## Python

* Via [`uv`](https://docs.astral.sh/uv/)
    
* You generally don’t want to replace system python. Use virtualenv instead.
    

## Go (Golang)

* Direct install
    

## Javascript/Node.js

* Use `nvm` to maintain installed node version. [Windows](https://github.com/coreybutler/nvm-windows) | MacOS/WSL2
    
* [https://pnpm.io/](https://pnpm.io/) is now preferred
    

## MSYS2 for C Developement (Windows)

* Install MSYS2
    
* For Clang/LLVM toolchain (recommended)
    
    * `pacman -S mingw-w64-ucrt-x86_64-clang`
        
* For GCC
    
    * `pacman -S mingw-w64-ucrt-x86_64-gcc`
        
* Recommended to just use UCRT - [Why UCRT?](https://stackoverflow.com/questions/67848972/differences-between-msvcrt-ucrt-and-vcruntime-libraries)
    
* [MSYS2 Environments](https://www.msys2.org/docs/environments/)
    

Notes about MSYS2’s common GNU binaries - [above](#gnu).

---

# Git

> Use [Git for Windows](https://gitforwindows.org) then expose git binaries path
> 
> Use Git from Homebrew for MacOS.

## Commit Signing

1. Enable GPG signing globally `git config --global commit.gpgsign true`.
    
2. By default git will use `gpg` command by default to perform signing.
    
3. Then you need to tell [which GPG key to use](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key#telling-git-about-your-gpg-key) for signing.
    

Windows-only note

> By installing GnuPG (GPG) individually, you can use `gpg` command on Windows. But it's easier to install it via [GPG4Win](https://www.gpg4win.org/about.html) which also includes Kleopatra (make sure to tick it during installation) that provide interface for GPG keys & settings management e.g passphrase TTL.
> 
> When freshly installing GPG4Win, make sure to also follow [Start The Agent on Startup guide](https://gist.github.com/matusnovak/302c7b003043849337f94518a71df777#start-the-agent-on-startup) right after

## Associating GPG key with email on Git provider

To make sure git provider recognize signed commit properly, they need to associate an email with certain GPG key, this should be done once.

* [Github](https://docs.github.com/en/authentication/managing-commit-signature-verification/associating-an-email-with-your-gpg-key)
    
* [Gitlab](https://docs.gitlab.com/ee/user/project/repository/gpg_signed_commits/#add-a-gpg-key-to-your-account)
    

## Use Windows built-in OpenSSH client for Git for Windows

With Windows including `ssh-agent` and OpenSSH client by default, this provide a lightweight and solid ssh baseline setup, just make sure to [config Git to use it for its ssh command](https://poshsecurity.com/blog/using-the-openssh-client-included-in-windows-10-1809-as-your-gits-ssh-client)

## [Configure WSL to use Windows Git Credential Manager](https://www.edwardthomson.com/blog/git_credential_manager_with_windows_subsystem_for_linux)