dotfiles

Portable interactive development configuration for macOS, Linux, WSL2, and Windows. The installers are preview-first, preserve existing files by default, and are verified by a local pipeline rather than GitHub Actions.

This repository owns shell, terminal, Git, tmux, PowerShell, and Neovim behavior. The private workstation-blueprint repository owns the larger machine package stack, security profiles, recovery runbooks, and the pinned revision of these public dotfiles.

Quick Start

macOS or Linux

Prerequisites: Git and Homebrew.

git clone https://github.com/AlisinaDevelo/dot-files.git "$HOME/Developer/dev/dotfiles"
cd "$HOME/Developer/dev/dotfiles"

# Inspect only. This is the default and changes nothing.
./install.sh

# Apply packages, pinned shell dependencies, and safe symlinks.
./install.sh --apply

./scripts/setup-repo.sh
./scripts/doctor.sh

Use ./install.sh --apply --links-only when packages are managed elsewhere. If a destination already exists, the installer preserves it and exits with status 2. After reviewing the path, --backup-existing moves it to a timestamped backup before linking.

Windows

Prerequisites: PowerShell 7, Scoop, winget, and Windows Developer Mode for unprivileged symlinks.

git clone https://github.com/AlisinaDevelo/dot-files.git "$HOME\Developer\dev\dotfiles"
Set-Location "$HOME\Developer\dev\dotfiles"

# Preview, then apply.
.\install.ps1
.\install.ps1 -Apply

The PowerShell installer never downloads and executes a package-manager bootstrap script. Install Scoop from its official instructions first, review the preview, and then apply the plan.

What Is Managed

Area	Configuration	Highlights
Shell	zsh/, powershell/	Powerlevel10k, Oh My Posh, history, completion, portable user-tool paths
Terminal	alacritty/, windows-terminal/	Cross-platform key bindings, Meslo Nerd Font, Catppuccin palette
Multiplexer	tmux/	Vim navigation, persistence, guarded TPM startup
Git	git/	Delta, rebase workflow, aliases, machine-local identity include
Editor	nvim/	LazyVim, 64 locked plugins, polyglot LSP/test/formatting support
AI	nvim/lua/plugins/ai.lua	Copilot completion; Avante with OpenCode, Kimi, Claude, OpenAI, Ollama, or Copilot
Verification	scripts/, .githooks/	Syntax, formatting, native parsers, installer tests, secret scanning, clean-clone test

Safety Model

1. Running either installer without --apply or -Apply is a read-only preview.
2. Existing files and directories are never replaced implicitly.
3. Explicit backup mode moves conflicts to timestamped paths before creating links.
4. Oh My Zsh, Powerlevel10k, and TPM are installed at immutable Git revisions.
5. Linux font downloads use immutable URLs and verified SHA-256 hashes.
6. Git identity, credentials, API keys, and host policy stay outside the public repository.
7. Neovim plugin revisions are committed in nvim/lazy-lock.json.

See Installation and Recovery, Migration, and Supply-Chain Policy for the full operating model.

Git Identity

The tracked Git config includes ~/.gitconfig.local. Configure identity once per machine:

git config --file "$HOME/.gitconfig.local" user.name "Your Name"
git config --file "$HOME/.gitconfig.local" user.email "you@example.com"
GIT_CONFIG_GLOBAL="$HOME/.gitconfig.local" gh auth setup-git

This prevents a public dotfiles repository from carrying personal email addresses or architecture-specific credential-helper paths.

Neovim and AI

The editor keeps one inline completion engine, Copilot, and one unified assistant surface, Avante. Avante chooses a provider in this order:

1. AVANTE_PROVIDER
2. OpenCode ACP when opencode is available
3. Kimi ACP when kimi is available
4. Claude when ANTHROPIC_API_KEY is set
5. OpenAI when OPENAI_API_KEY is set
6. Copilot fallback

Tool calls always require approval. Provider and model overrides are documented in Neovim and AI.

The selected LazyVim extras cover C/C++, CMake, containers, .NET, Git, Go, Java, JSON, Markdown, Python, Rust, SQL, Terraform, TOML, TypeScript, YAML, testing, formatting, and refactoring. The lockfile makes that graph reproducible across machines.

Local Quality Gate

Enable repository hooks once:

./scripts/setup-repo.sh

Run the same full gate at any time:

./scripts/local-pipeline.sh

It checks the working tree, exercises installer preview/apply/conflict/backup behavior in temporary homes, scans for secrets, and repeats validation from a clean local clone.

The pre-commit hook checks staged whitespace and likely secrets; the pre-push hook runs the full pipeline.

Common Operations

# Inspect active links, authentication, and command availability.
./scripts/doctor.sh

# Preview updates after pulling.
git pull --ff-only
./install.sh

# Apply only configuration links.
./install.sh --apply --links-only

# Apply and safely migrate existing destinations.
./install.sh --apply --links-only --backup-existing

For the full workstation, use the private blueprint. It pins this repository by commit and layers machine profiles such as builder, AI, defender, and isolated security lab on top.

Layout

.
|-- .githooks/             local pre-commit and pre-push gates
|-- alacritty/             portable terminal configuration
|-- docs/                  installation, migration, editor, and security guides
|-- git/                   public Git behavior and local-config example
|-- manifests/             immutable third-party source revisions and hashes
|-- nvim/                  LazyVim configuration and plugin lockfile
|-- powershell/            Windows shell profile
|-- scripts/               doctor, tests, validation, and local pipeline
|-- tmux/                  terminal multiplexer configuration
|-- windows-terminal/      Windows Terminal settings
|-- zsh/                   macOS/Linux/WSL shell configuration
|-- Brewfile               cross-platform Homebrew formulae
|-- Brewfile.macos         macOS casks and fonts
|-- install.ps1            preview-first Windows installer
`-- install.sh             preview-first macOS/Linux installer

License

MIT