🏛️ dotfiles-Arch

The Arch OS-native layer — rolling-release, pacman + AUR, over the shared Core.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Languages
   • Tools
2. Getting Started
3. What's In This Layer
4. Contributing
5. License
6. Contact

About The Project

dotfiles-Arch is the OS-native layer for Arch Linux — one node in a cross-platform dotfiles system. The shared Core (zsh, tmux, Neovim, git, starship, mise) is authored once in dotfiles-core and vendored under core/ as a pinned, filtered copy, so a clone is self-contained. This repo adds only what is genuinely Arch: pacman, the AUR, multilib, and mirror management — leaning on Arch's deep official repos so there are no curl | sh fallbacks.

Arch is stamped from the dotfiles-Fedora template per the porting matrix. The full docs live on the documentation site.

The system is three layers, each building on the one below:

Layer	Lives in	Owns
Core	dotfiles-core → vendored into every OS repo's core/	zsh, tmux, nvim, git, starship — identical everywhere
OS-native	dotfiles-{MacBook,Windows,Fedora,Arch,Debian,openSUSE,Alpine,Gentoo} (this repo among them)	package manager, clipboard, paths
Role	dotfiles-Offense, dotfiles-Defense	offensive / defensive tooling

Languages

No new languages — this layer is shell and package config over Core's language stack.

Tools

• 
• 
• 
• 
• 

(back to top)

Getting Started

Prerequisites

An Arch box and Git. On a fresh or minimal install you first need stage-0 groundwork — a sudo-capable user, git, and a UTF-8 locale — before bootstrap.sh can run; archinstall and ArchWSL already give you that. The walkthrough is on the hub:

→ Arch stage-0 setup

Installation

git clone https://github.com/dotgibson/dotfiles-Arch ~/dotfiles-Arch
cd ~/dotfiles-Arch
./bootstrap.sh
exec zsh

core/ is a vendored copy and is already present in a clone — there is no submodule step. bootstrap.sh is idempotent: it does a full pacman -Syu, installs the package list, and symlinks Core + the Arch layer into place. Flags: --dry-run (preview everything, change nothing), --links-only (re-link without touching pacman), --no-flatpak, --only/--skip (wire a subset of module groups). Run ./bootstrap.sh --help for the full list.

Local checks live in the root Makefile, which speaks the fleet-wide make vocabulary (dotfiles-core#691): make lint runs the same gate as CI, make test runs the test/ suite, make dry-run previews a full bootstrap, make packages-check verifies every package name still resolves, make check runs all three, and make secrets runs gitleaks. make on its own lists them. make bootstrap-dry still works as an alias for dry-run.

(back to top)

What's In This Layer

Only what changes with the OS. The heavy lifting — the shell modules, editor, and prompt — comes from vendored Core; this repo owns the Arch specifics:

• bootstrap.sh — pacman provision + Core/OS symlink wiring (idempotent)
• install/packages.txt — the pacman package list (modern CLI stack)
• os/arch.zsh — clipboard + package-manager aliases → ~/.config/zsh/80-os.zsh
• Makefile — local entry points: lint, check, dry-run, test, package + secret checks
• test/ — the repo's test suite (make test; run in CI by packages.yml)
• SETUP.md — the from-scratch author walkthrough (mirrored on the hub)
• core/ — vendored from dotfiles-core (read-only here; edit upstream)

The things that actually bite on Arch — the rolling-release rule (never pacman -Sy <pkg> without -u), the un-automated AUR (paru), opt-in multilib, and the absent transaction undo — are written up on the hub, alongside the per-distro porting matrix:

→ dotfiles-Arch on the documentation hub

(back to top)

Contributing

This is an OS-native layer, so the contribution rule is a boundary rule:

1. Never hand-edit core/. It is a vendored copy of dotfiles-core and is overwritten on the next sync. Fix shared config upstream in dotfiles-core, run make audit there, then make sync fans it out here.
2. Keep changes genuinely Arch. If it would be identical on every distro, it belongs in Core; if it changes with the operator, it belongs in a role repo.
3. Green the lint gate. This repo's CI runs shellcheck + bash -n / zsh -n on the repo-owned shell (the vendored core/ is excluded — it is gated upstream).

Bugs and ideas: open an issue.

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Garrett Allen - @gerrrrt - garrettallen2@gmail.com - LinkedIn

Project Link: dotgibson

(back to top)