Dotfiles Guide

Dotfiles Guide

Overview

Reference guide for where to place files and how to extend this dotfiles repository.

Quick Reference

Directory Structure

dotfiles/
├── install.sh        # Bootstrap for Linux / macOS / WSL2
├── install.ps1       # Bootstrap for Windows (PowerShell 7)
├── config/           # Configuration files (copied to ~)
│   ├── shell/
│   │   ├── common/   # Shared aliases & functions
│   │   ├── bash/     # Bash-specific (.bashrc)
│   │   ├── zsh/      # Zsh-specific (.zshrc)
│   │   └── powershell/  # PowerShell profile + oh-my-posh theme
│   ├── git/          # Git config files
│   └── <app>/        # Other app configs
│
├── scripts/          # Installation scripts
│   ├── common/       # Cross-platform (configs, uv, nvm, ai-agents)
│   ├── linux/        # Linux-only scripts (also run on WSL2)
│   ├── macos/        # macOS scripts
│   └── windows/      # Windows scripts (setup-powershell.ps1)
│
├── packages/         # Package lists (one per line)
│   ├── linux/
│   │   ├── apt.txt
│   │   ├── snap.txt
│   │   └── flatpak.txt
│   ├── macos/
│   │   └── brew.txt
│   └── windows/
│       └── winget.txt
│
└── lib/              # Shared shell functions
    └── utils.sh

Adding Packages

APT Packages (packages/linux/apt.txt)

# Comments start with #
git
curl
vim

# Use [full] tag for packages only on dev machines
docker.io [full]
nodejs [full]

Packages tagged [full] are skipped when running make server (minimal mode).

Snap Packages (packages/linux/snap.txt)

# Format: package-name [flags]
code --classic
slack

Flatpak Packages (packages/linux/flatpak.txt)

# Use full application ID
com.spotify.Client
org.gimp.GIMP

Homebrew Packages (packages/macos/brew.txt)

# Comments start with #
git
curl
wget

# Use [full] tag for packages only on dev machines
node [full]

Installing Development Tools

Python (uv)

make uv

Installs uv - fast Python package manager. After installation, use uv to manage Python versions and packages.

Node.js (nvm)

make nvm

Installs nvm and the latest LTS Node.js. After installation, use nvm to manage Node.js versions.

AI CLI Tools

make ai-agents

Installs AI coding assistants (requires npm, run make nvm first):

• GitHub Copilot CLI (@github/copilot)
• OpenAI Codex (@openai/codex)
• Google Gemini CLI (@google/gemini-cli)
• Claude Code (via curl installer)

Adding Shell Configuration

Shared (all shells)

Add to config/shell/common/aliases.sh or functions.sh:

# aliases.sh
alias ll='ls -la'

# functions.sh
mkcd() {
    mkdir -p "$1" && cd "$1"
}

Shell-Specific

• Bash only: Edit config/shell/bash/.bashrc
• Zsh only: Edit config/shell/zsh/.zshrc

Adding New Application Config

1. Create directory: config/<app-name>/
2. Add config files (use dot prefix if needed)
3. Update scripts/common/configs.sh to copy config files
4. Optionally add Makefile target

Example for tmux:

mkdir -p config/tmux
# Add config/tmux/.tmux.conf

Adding New Module (Makefile Target)

1. Add target to Makefile:

.PHONY: tmux
tmux:
    @bash scripts/common/configs.sh --module tmux

1. Update scripts/common/configs.sh to handle the module

Machine-Specific Config

For settings that shouldn't be in git:

• ~/.bashrc.local - Bash machine-specific
• ~/.zshrc.local - Zsh machine-specific

These are sourced automatically but not tracked in git.

Common Workflows

"I want to install package X on all my Linux machines"

1. Add to packages/linux/apt.txt (or snap.txt/flatpak.txt)
2. Commit and push
3. On other machines: git pull && make packages

"I want a new alias available everywhere"

1. Add to config/shell/common/aliases.sh
2. Commit and push
3. On other machines: git pull && source ~/.bashrc (or ~/.zshrc)

"I want to add vim/neovim config"

1. Create config/vim/
2. Add .vimrc or init.vim
3. Update configs script
4. Add make vim target to Makefile
5. Update README.md (可用指令、目錄結構)

Important Reminder

新增功能或模組後，務必更新 README.md：

• 新增 make target → 更新「可用指令」section
• 新增目錄或檔案 → 更新「目錄結構」section
• 新增套件管理器 → 更新「自訂設定」section
• 新增 OS 支援 → 更新「支援的作業系統」section