Dotfiles

Dotfiles repository managed with GNU Stow for macOS and Linux (Ubuntu).

Table of Contents

• Dotfiles
  • Table of Contents
  • Installation
  • Core System Tools
    • Shells
    • Terminal Emulators
    • Core CLI Tools
    • Shell Enhancements
    • CLI Utilities
    • Terminal Multiplexers
    • Version Control
  • Development Environment
    • Language Server Protocols (LSPs)
    • Python Tooling
    • Java
    • Markdown Tooling
    • Rust
    • Formatters
  • Personal Knowledge Management (PKM)
  • Media and Document Processing
  • Browsers
  • Unused / Archived Programs

---

Installation

For first-time setup, run:

chmod +x scripts/setup.sh
./scripts/setup.sh

---

Core System Tools

Shells

• Nushell

  • Modern structured-shell with pipelines and tables.

  brew install nushell

• ZSH

  • Highly customizable traditional Unix shell.

  • ZSH Specific Plugins:

    • ZSH Autosuggestions
    • ZSH Syntax Highlighting
    • ZSH Autocomplete

    brew install zsh-autosuggestions
    brew install zsh-syntax-highlighting
    brew install zsh-autocomplete

• Bash (Optional)

  • Classic Unix shell.

  brew install bash

  • Bash Specific Plugins:

    • Bash Completion

    brew install bash-completion@2

    Homebrew reccomends to add the following to .bash_profile:

    [[ -r "$HOMEBREW_PREFIX/etc/profile.d/bash_completion.sh" ]] && . "$HOMEBREW_PREFIX/etc/profile.d/bash_completion.sh"

    This ensures Bash completion is initialized properly in macOS login shells, which source .bash_profile by default.
    However, in this dotfiles setup, all interactive shell logic — including Bash completions — is centralized in .bashrc, and .bash_profile simply sources .bashrc. This avoids duplication, keeps .bash_profile minimal, and ensures that completions are still available in both login and interactive shells without repeating logic.
    For a modular and maintainable setup, it is therefore preferable to keep the completion logic in .bashrc only. See, Bash Startup Files

Terminal Emulators

• Ghostty

  • GPU-accelerated, fast terminal emulator.

  brew install --cask ghostty

• Wezterm

  • Highly configurable GPU-accelerated terminal emulator.

  brew install --cask wezterm

Core CLI Tools

• GNU Stow

  • Dotfiles symlink farm manager which takes distinct sets of software and/or data located in separate directories on the filesystem, and makes them appear to be installed in a single directory tree.
  • Docs: https://www.gnu.org/software/stow/manual/stow.html

  brew install stow

• Keychain

  • Keychain helps you to manage SSH and GPG keys in a convenient and secure manner. It acts as a frontend to ssh-agent and ssh-add, but allows you to easily have one long running ssh-agent process per system, rather than the norm of one ssh-agent per login session.

  brew install keychain

Shell Enhancements

• Direnv

  • Load/unload environment variables based on $PWD
  • GitHub: https://github.com/direnv/direnv

  brew install direnv

• shellcheck

  • Static analysis and lint tool, for (ba)sh scripts

  brew install shellcheck

• shfmt

  • Shell formatter for POSIX sh, bash, zsh, ksh, and fish.

  brew install shfmt

• Atuin

  • Shell history replacement with structured search and optional sync for zsh, bash, fish and nushell
  • Docs: https://docs.atuin.sh

  brew install atuin

• Carapace

  • Shell completion engine for multiple shells.

  brew install carapace

• Starship

  • Cross-shell minimal prompt with extensive customization.

  brew install starship

• Yazi

  • Docs: https://yazi-rs.github.io/
  • Fast, modern terminal file manager with preview support.

  brew install yazi

CLI Utilities

• zoxide

  • Smarter cd command with fuzzy matching.

  brew install zoxide

• eza

  • Modern ls replacement with color and git support.

  brew install eza

• fzf

  • Powerful fuzzy finder for files and history.

  brew install fzf

• fd

  • Simple, fast alternative to find.

  brew install fd

• ripgrep

  • Fast and recursive grep alternative.

  brew install ripgrep

• bat (Optional)

  • Syntax-highlighted and paginated alternative to cat.

  brew install bat

• ollama

  • Command line tool for the Ollama library.

  brew install ollama

• mermaid-cli

  • Command line tool for the Mermaid library.
    • Note: Requires Puppeteer

  npm install -g mermaid-cli
  npm install -g puppeteer

Terminal Multiplexers

• Zellij

  • Terminal workspace manager and multiplexer.

  brew install zellij

• tmux (Optional)

  • Traditional terminal multiplexer.

  brew install tmux

  • Tmux Plugin Manager

    • Tmux plugin manager

    brew install tpm

    To initialize TPM add this to your tmux configuration file (~/.tmux.conf or $XDG_CONFIG_HOME/tmux/tmux.conf):

    run '$HOMEBREW_PREFIX/opt/tpm/share/tpm/tpm'

Version Control

• Git

  • Distributed version control system.

  brew install git

• LazyGit

  • Simple TUI for git commands.

  brew install lazygit

• Git LFS

  • Support for large files in git repositories.

  brew install git-lfs

• Git Filter Repo

  • Efficient git history rewriting tool.

  brew install git-filter-repo

• Delta

  • Docs: https://dandavison.github.io/delta/introduction.html
  • A syntax-highlighting pager for git, diff, grep, and blame output

  brew install git-delta

• GitLeaks

  • GitHub: https://github.com/gitleaks/gitleaks
  • Gitleaks is a tool for detecting secrets like passwords, API keys, and tokens in git repos, files, and whatever else you wanna throw at it via stdin.

  brew install gitleaks

Development Environment

• Neovim

  • Hyperextensible Vim-based text editor.

  brew install neovim

• Helix

  • Postmodern modal text editor.

  brew install helix

• Zed

  • High-performance collaborative code editor.

  brew install --cask zed

• VS Code

  • Extensible code editor.

  brew install --cask visual-studio-code

  • Note: When first opening VS Code, ssh-agent did not work properly. See, VS Code SSH Passphrase Error and Solution

Language Server Protocols (LSPs)

• VS Code Language Servers

  • Extracted LSP servers:
    • HTML: vscode-html-language-server
    • CSS: vscode-css-language-server
    • JSON: vscode-json-language-server
    • ESLint: vscode-eslint-language-server

  brew install vscode-langservers-extracted

• TypeScript Language Server

  brew install typescript-language-server

• TexLab

  • LaTeX Language Server.

  brew install texlab

• Yaml Language Server

  brew install yaml-language-server

• Solargraph

  • Ruby Language Server
  • Note: Primarily used for handling Homebrew related tasks on my machine.

  brew install solargraph

Python Tooling

• Python

  • Latest version of the Python programming language.

  brew install [email protected]

• BasedPyright

  • Open source LSP and pype checker for Python based on Pyright.

  brew install basedpyright

• Pylyzer

  • Fast static analysis for Python.

  brew install pylyzer

• uv

  • Extremely fast Python package installer and resolver.

  brew install uv

• IPython

  • Rich interactive Python shell.

  brew install ipython

• Jupytext

  • Sync Jupyter notebooks and plain text scripts.

  brew install jupytext

• ruff

  • Extremely fast Python linter and formatter.

  brew install ruff

• isort

  • Automatically sort Python imports.

  brew install isort

Java

• OpenJDK

  • Open-source Java Development Kit.

  brew install openjdk

  If you need to add to PATH:

  echo 'export PATH="/opt/homebrew/opt/openjdk/bin:$PATH"' >> ~/.zshrc

  And for compilers:

  export CPPFLAGS="-I/opt/homebrew/opt/openjdk/include"

Markdown Tooling

• Marksman

  • Markdown Language Server.

  brew install marksman

• Markdownlint CLI

  • Markdown linter and style checker.

  brew install markdownlint-cli

Rust

• Rust

  • Systems programming language.

  brew install rust

Formatters

• Prettier

  • Code formatter supporting multiple languages.

  brew install prettier

• cSpell

  • GitHub: https://github.com/streetsidesoftware/cspell

  • Spell checker for code and text.

  brew install cspell

---

Personal Knowledge Management (PKM)

• Obsidian

  • Personal knowledge base and markdown editor.

  brew install --cask obsidian

• Anki

  • Spaced repetition flashcard software.

  brew install --cask anki
  brew install webp
  brew install avif

• Calibre

  • Comprehensive e-book management software.

  brew install --cask calibre

---

Media and Document Processing

• LibreOffice

  • Free office suite and language pack

  brew install --cask libreoffice
  brew install --cask libreoffice-language-pack

• Zathura Document Viewer

  • GitHub
  • Lightweight document viewer.

  brew install zathura

  • MuPDF Plugin for Zathura:

    brew install zathura-pdf-mupdf
    mkdir -p $(brew --prefix zathura)/lib/zathura
    ln -s $(brew --prefix zathura-pdf-mupdf)/libpdf-mupdf.dylib $   (brew --prefix zathura)/lib/zathura/libpdf-mupdf.dylib

• OCRmyPDF

  • GitHub
  • Adds OCR text layers to PDFs.

  brew install ocrmypdf

• tesseract OCR

  • Optical character recognition engine.

  brew install tesseract

• qpdf

  • GitHub
  • PDF transformation and inspection tool.

  brew install qpdf

• img2pdf

  • Convert images to PDF without quality loss.

  brew install img2pdf

---

Browsers

• Zen Browser

  • Lightweight, distraction-free browser.

  brew install --cask zen-browser

---

Unused / Archived Programs

• VSCodium

  • Docs; GitHub
  • a community-driven, freely-licensed binary distribution of Microsoft’s editor VS Code without Microsoft branding, telemetry, and licensing.

  brew install --cask vscodium

  • Microsoft Marketplace Setup:

    • flathub/com.vscodium.codium#90
    • VSCodium/vscodium#674

  • Note:

    • I stopped using VSCodium because it became to slow and often their were glitches in the UI

• MuPDF Tools (Archived)

  • Lightweight PDF and XPS viewer toolkit.

  brew install mupdf-tools

• Signal (Archived)

  • Secure private messaging app.

  brew install --cask signal