Personal, opinionated dotfiles for macOS, Debian/Ubuntu, and Windows. The Unix path configures Bash or Zsh through install.sh; the Windows path configures PowerShell through install.ps1 and uses WinGet for packages.
Review the dry-run and the relevant platform files before applying the configuration to a new machine. The installers can update shell profiles, global Git defaults, package manifests, and platform-specific settings.
- Platform support
- Quick start
- What this repository manages
- Installer modes
- Local and private configuration
- Safety and recovery
- Common commands
- Verification and tests
- Repository layout
- Detailed guides
- License
| Platform | Status | Entry point | Package manager | Validation |
|---|---|---|---|---|
| macOS | Supported | install.sh | Homebrew Bundle | Bash 3.2 compatibility, shell checks, and macOS defaults/Dock dry-runs |
| Debian/Ubuntu | Supported | install.sh | APT | Bash and Zsh lifecycle tests on Ubuntu 24.04 |
| Windows | Preview | install.ps1 | WinGet | PowerShell parsing plus dry-run, sync, and Git restore smoke tests |
Other Linux distributions are not covered by the installer. The shell files can still be adapted manually, but package installation and platform setup assume Debian or Ubuntu.
The Windows path is marked as preview because it does not yet provide a complete uninstall workflow and CI does not perform a real installation of every WinGet package.
Open a regular PowerShell window. WinGet may request elevation for individual packages when required.
Install Git, which is not included in a standard Windows installation:
winget install --id Git.Git --exact --source winget --accept-package-agreements --accept-source-agreements
Close and reopen PowerShell after the installation, then verify the command is available:
git --versionClone the repository and enter it:
git clone https://github.com/alsd4git/dotfiles.git "$HOME\.dotfiles"Set-Location"$HOME\.dotfiles"
Allow locally stored PowerShell scripts and profiles for the current user:
Set-ExecutionPolicy-ExecutionPolicy RemoteSigned -Scope CurrentUser
Preview the changes, then run the interactive installer:
.\install.ps1 -DryRun .\install.ps1Open a new PowerShell or Windows Terminal session to load the installed profile.
See the Windows guide for WinGet recovery, package selection, changed files, local overlays, backup behavior, and known limitations.
Check that Git is available:
git --versionOn a new Mac, install the Xcode Command Line Tools first if that command is unavailable:
xcode-select --installAfter the tools finish installing:
git clone https://github.com/alsd4git/dotfiles.git ~/.dotfiles
cd~/.dotfiles
./install.sh --dry-run
./install.shThe executable bit for install.sh is tracked by Git, so a normal clone does not require chmod +x.
The Command Line Tools are enough for Git and the initial clone. The current optional macOS package/defaults path also checks xcodebuild -version, so install full Xcode before approving that phase. A configuration-only run with --skip-tools does not enter the Xcode/Homebrew path.
See the macOS guide before applying the Homebrew manifest, system defaults, or saved Dock layout.
Install Git before cloning the repository:
sudo apt update
sudo apt install -y git
git clone https://github.com/alsd4git/dotfiles.git ~/.dotfiles
cd~/.dotfiles
./install.sh --dry-run
./install.shRun the initial APT commands as root instead when sudo is not installed. The package phase inside the current installer invokes sudo; use ./install.sh --skip-tools and manage packages separately when sudo is intentionally unavailable.
See the Debian/Ubuntu guide for package groups, shell setup, optional toolchains, update behavior, and troubleshooting.
- Shell configuration: shared aliases, functions, history settings, prompt initialization, Nano configuration, and Bash/Zsh startup entries.
- PowerShell configuration: profiles for Windows PowerShell and PowerShell 7, aliases and helper functions, local profile overlays, Windows Terminal settings, and selected application configuration.
- Git configuration: a shared global ignore file and a conservative set of global defaults without replacing the complete user
.gitconfig. - Packages:
macos/Brewfile, Debian/Ubuntu package groups, and separate Windows core, optional, and private manifests. - Platform settings: an optional macOS defaults baseline, an optional saved Dock layout, Windows Terminal settings, and TrafficMonitor configuration.
- Recovery state: timestamped backups and snapshots of the Git settings managed by the installers.
Package manifests are the source of truth for the current inventory. The README intentionally does not duplicate every package name.
| Command | Behavior |
|---|---|
./install.sh | Interactive setup with managed dotfiles, Git defaults, and optional components |
./install.sh --dry-run | Preview managed file and Git actions without modifying the machine; the package/tool phase is skipped |
./install.sh --minimal | Install only the core dotfiles; skip Git defaults, package installation, and remote bootstrap operations |
./install.sh --skip-tools | Apply dotfiles and Git defaults without installing packages or optional tools |
./install.sh --sync | Reconcile managed dotfiles and Git defaults without installing tools or adding optional startup commands |
./install.sh --all --yes | Select all optional components and answer yes to their prompts |
./install.sh --copy | Copy managed files instead of symlinking them, with backups for conflicts |
./install.sh --clean-backups | Offer to remove only backups recorded by this installer |
./install.sh --uninstall | Remove managed links/startup entries and restore unchanged Git settings captured before installation |
Run ./install.sh --help for the complete option list. macOS-specific options such as --trust-brew-taps and --brew-upgrade are documented in the macOS guide.
| Command | Behavior |
|---|---|
.\install.ps1 | Apply managed configuration and ask separately about core, optional, and private packages |
.\install.ps1 -DryRun | Preview file, Git, and package operations without changing the machine |
.\install.ps1 -Minimal | Apply managed configuration but skip package installation |
.\install.ps1 -Sync | Reconcile profiles, copied configuration, and Git defaults without installing packages |
.\install.ps1 -Force or -y | Answer yes to all package prompts; this includes optional and non-empty private manifests |
.\install.ps1 -CleanBackups | Inspect the currently supported Windows backup-cleanup scope and ask before deletion |
.\install.ps1 -RestoreGitDefaults | Restore managed Git values when they have not changed since installation |
For a non-destructive preview of the complete Windows package selection, use:
.\install.ps1 -DryRun -ForceDo not use -Force for a conservative first installation: it selects all available package manifests rather than merely overwriting files.
Keep machine-specific or sensitive configuration outside the tracked public files.
Create ~/.private_aliases. The shared aliases file loads it automatically when present.
The PowerShell profile loads these locations last:
~\.config\dotfiles\windows\profile.d\*.ps1, in filename order~\.private_profile.ps1
Use windows/profile.local.example.ps1 as a starting point. The overlay directory can also be replaced with the DOTFILES_WINDOWS_PROFILE_DIR environment variable.
For local-only package entries, edit the scaffold created at:
~\.config\dotfiles\windows\packages.private.psd1
The public template is windows/packages.private.example.psd1.
- Run the appropriate dry-run before the first installation and after material configuration changes. Review package manifests separately because the Unix dry-run skips the package/tool phase.
- Existing conflicting files are moved to timestamped paths such as
.bak.<timestamp>before replacement. - The Unix installer records the backups it creates and limits
--clean-backupsto that manifest. - The Windows installer currently creates backups but does not maintain an equivalent recursive backup manifest. Its cleanup command has a narrower scope; see the Windows recovery notes.
- Both installers snapshot the Git values they manage. Restore logic leaves a setting untouched when it was changed after installation.
install.sh --uninstallremoves only shell-startup lines recorded when the installer added them. Installations made before this ownership record was introduced leave unrecorded startup lines untouched. Windows currently has-RestoreGitDefaults, not a complete uninstall.- macOS defaults, the saved Dock layout, Windows Terminal settings, and TrafficMonitor configuration are opinionated. Review their source files before applying them.
The shared command names use shell-native implementations so they remain familiar across Bash, Zsh, and PowerShell.
| Command | Platform | Purpose |
|---|---|---|
a / aa | All configured shells | Inspect or list configured aliases and command shortcuts |
l, la, ll, lt | All configured shells | Directory listings, using eza when available |
rld | Bash, Zsh, PowerShell | Reload the active shell configuration without starting a nested shell |
gl / gp | All configured shells | Pull with rebase/autostash or push the current branch |
gsu | All configured shells | Set the upstream to origin/<current-branch> |
gla / glaf | All configured shells | Show the latest commit summary or full patch |
npmupg | Bash, Zsh, PowerShell | Show outdated global npm packages and run npm update -g |
brewup | macOS | Update, upgrade, and clean Homebrew packages |
wingup | Windows | Show and apply WinGet upgrades |
rld detects the active interpreter rather than relying on the login-shell value in $SHELL. It re-sources ~/.bashrc in Bash, ${ZDOTDIR:-$HOME}/.zshrc in Zsh, and the current-user all-hosts profile in PowerShell. It does not reload login-only files such as .bash_profile or .zprofile. The older Unix command rldz remains as a compatibility alias to rld.
npmupg requires npm. On Unix it now reports a clear error when Node.js is unavailable instead of executing two failing commands.
After a Unix installation, verify the managed configuration:
type rld npmupg
git config --global --get core.excludesfile
./scripts/health-check.sh --strict
./scripts/tool-health-check.shWhen the optional tool phase was approved, also verify its commands:
command -v git nano fzf zoxide uv swiftly ghAfter a Windows installation, open a new PowerShell session and run:
Get-Command git, winget, aa, l, gl, rld, npmupg, wingup -ErrorAction SilentlyContinue
git config --global --get core.excludesfileRepository checks include:
./tests/test-installer-functions.sh
./tests/docker-ubuntu-smoke.shpwsh -File .\tests\windows-smoke.ps1GitHub Actions runs ShellCheck, shfmt, Unix installer tests, Ubuntu lifecycle tests, macOS defaults/Dock dry-runs, and Windows PowerShell smoke tests.
.
├── .github/ GitHub Actions workflow
├── archive/ Historical installers, not part of the supported workflow
├── docs/ Platform-specific setup and troubleshooting guides
├── general/ Shared aliases, functions, history, and prompt setup
├── git/ Git aliases, functions, defaults, and global ignore
├── lib/ Unix installer modules and package policy
├── macos/ Brewfile, defaults, and saved Dock layout
├── nano/ Nano configuration
├── scripts/ Health checks and tool inventory
├── tests/ Installer, lifecycle, and PowerShell smoke tests
├── windows/ PowerShell profile, manifests, Terminal, and app configuration
├── install.sh macOS and Debian/Ubuntu installer
└── install.ps1 Windows installer
MIT. See LICENSE.