Linux Workstation Dotfiles

Reproducible Linux workstation configuration for an Ubuntu-based development environment: shell, terminal, editor, package manifest, VS Code extensions, and health checks.

Overview

This repository provides a reusable Linux workstation setup with repeatable shell configuration, terminal tooling, editor settings, package manifests, VS Code extensions, and validation scripts.

It is designed for safe local setup: existing target files are moved into ~/.dotfiles-backup/YYYYmmdd-HHMMSS/ before new links or copies are created.

Quick Start

Preview changes without modifying files:

./scripts/install.sh --dry-run

Apply dotfiles:

./scripts/install.sh

Run the health check:

./scripts/doctor.sh

Install Modes

Mode	Command
Preview only	./scripts/install.sh --dry-run
Link dotfiles	./scripts/install.sh
Copy instead of symlink	./scripts/install.sh --copy
Install apt packages	./scripts/install.sh --packages
Add VS Code extensions	./scripts/install.sh --vscode
Finish with health check	./scripts/install.sh --doctor

What Gets Managed

home/.zshrc                         -> ~/.zshrc
home/.oh-my-zsh/custom/*.zsh        -> ~/.oh-my-zsh/custom/
config/kitty/kitty.conf             -> ~/.config/kitty/kitty.conf
config/starship.toml                -> ~/.config/starship.toml
vscode/settings.json                -> ~/.config/Code/User/settings.json
config/nvim/                        -> ~/.config/nvim/

Tooling Profile

Area	Tools
Shell	zsh, Oh My Zsh, Starship
Terminal	Kitty, tmux
Editor	Neovim / LazyVim, VS Code
Search/navigation	ripgrep, fd, fzf, zoxide
CLI utilities	jq, yq, bat, btop, duf, ncdu
Runtime base	Node.js, npm, Python

External/vendor tools such as Docker, GitHub CLI, VS Code, fnm, uv, atuin, and lazygit may need their own installers or package repositories.

VS Code

vscode/settings.json contains portable user settings, while vscode/extensions.txt defines a small general-purpose extension baseline.

The shared settings avoid user identities, absolute home paths, personal dictionaries, and settings that depend on unmanaged extensions. Framework-specific extensions are intentionally left to each project's recommendations.

Health Check

Health checks are defined in scripts/doctor.sh:

./scripts/doctor.sh

CI validates shell syntax, ShellCheck, shfmt, JSON/JSONC, VS Code portability, TOML, and the Ubuntu package manifest.

Repository Layout

config/                 # files linked into ~/.config
home/                   # files linked into $HOME
packages/ubuntu-apt.txt # apt package manifest
scripts/                # installer and doctor scripts
vscode/                  # portable VS Code settings and extensions

Key paths:

• config/ contains files linked into ~/.config.
• home/ contains files linked into $HOME.
• packages/ubuntu-apt.txt contains the Ubuntu apt package manifest.
• scripts/install.sh applies the dotfiles.
• scripts/doctor.sh validates the local environment.
• vscode/ contains portable VS Code settings and the extension manifest.

Automation

• .github/workflows/check.yml validates shell scripts, formatting, JSON, TOML, package manifests, and repository health.
• .github/workflows/codeql.yml runs GitHub CodeQL analysis.
• scripts/doctor.sh provides the local workstation health check.

Boundaries

This repository intentionally excludes secrets, SSH keys, browser profiles, caches, .env files, cloud credentials, and machine-specific runtime state.

License

Licensed under the MIT License.