/ README.md
README.md
1 <!-- markdownlint-disable MD041 --> 2 3 # dotfiles 4 5 ## 💻 What's in here? 6 7 | Name | Description | 8 | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | 9 | [nvim](./nvim/README.md) | LazyVim Configs | 10 | [wezterm](./wezterm/README.md) | Wezterm configs | 11 | [hammerspoon](./hammerspoon/README.md) | Hammerspoon configs, custom shortcuts/keybindings, and personal Spoons | 12 | [tmux](./tmux/README.md) | Tmux configs and plugins | 13 | [yazi](./yazi/README.md) | Yazi configs | 14 | [etc](./etc/config) | Shell profile, rcfiles, aliases, exports and functions and config files in general | 15 | [scripts](./scritps/) | Misc scripts for every-day stuff | 16 | [tasks](./tasks/) | Taskfiles to automate install and configuration steps; see [tasks/README.md](./tasks/README.md) for devbox (macOS + Linux) vs macos-only installs | 17 18 ## 🔨 How to Install? 19 20 Install steps and setup configuration are automated with [Taskfile runner](https://github.com/go-task/task/). 21 22 This is the only requirement that needs to be manually installed, all the 23 remaining dependencies are controlled and customized from the main [Taskfile.yml](./Taskfile.yml). 24 25 ### Optional: Devbox (cross-platform + reproducible tools) 26 27 [Devbox](https://www.jetify.com/devbox/docs/) provides the same CLI tools on **macOS and Linux**, so dotfiles tooling works on both without Homebrew on Linux. It also keeps tools isolated and reproducible. After installing Devbox once: 28 29 ```bash 30 task devbox:install-cli # one-time: install Devbox CLI 31 task devbox:install # install deps from devbox.json 32 task devbox:shell # enter shell with tools on PATH (or: devbox shell) 33 ``` 34 35 Inside the devbox shell you can run `task precommit` or `devbox run precommit`. The `.devbox/` directory is gitignored. 36 37 Run `task` to view the complete list of tasks currently available: 38 39 ```bash 40 task: Available tasks for this project: 41 * changelog: Generates CHANGELOG 42 * hooks: Setup git hooks locally 43 * jsonfmt: Format JSON with jq (sort keys, validate) 44 * list: Lists available commands 45 * markdownlint: Lint Markdown with markdownlint-cli (.markdownlint.yaml) 46 * precommit: Verifies and fix requirements for new commits 47 * yamlfmt: Format YAML files with yamlfmt (install with: go install github.com/google/yamlfmt/cmd/yamlfmt@latest) 48 * agents:generate: Regenerate platform agent files from .agents/ source 49 * agents:plan:rename: Rename .agents/plans and .cursor/plans files to YYYY-MM-DD_username_slug.plan.md (--dry-run to preview) 50 * changelog:rewrite-history: Rewrite all commit messages to conventional format (DESTRUCTIVE; backup first, then force-push) 51 * common:install:core:all: Setup shell, core settings and tools (cross-platform) 52 * common:install:core:fzf: Install FuzzyFinder 53 * common:install:core:lua: Install Lua from source (for Neovim etc.) 54 * common:install:core:nvim: Install Neovim nightly (macOS or Linux) 55 * common:install:core:nvim:darwin: Install Neovim nightly on macOS 56 * common:install:core:nvim:linux: Install Neovim nightly on Linux 57 * common:install:core:profile: Setup shell profile settings (cross-platform) 58 * devbox:install: Install devbox dependencies (run once after clone or when devbox.json changes) 59 * devbox:install-cli: Install Devbox CLI (required before devbox:install; uses official install script) 60 * devbox:shell: Enter devbox shell with all dev tools on PATH 61 * linux:install:all: Install base packages and core setup on Linux (apt + common core) 62 * linux:install:apt:all: Install base OS packages (Debian/Ubuntu) 63 * macos:install:all: Install all MacOS required tools 64 * macos:install:brew:all: Brew install all packages 65 * macos:install:brew:all:custom: Brew install recipes with custom steps 66 * macos:install:brew:all:custom:colima: Brew install Colima 67 * macos:install:brew:all:deps: Install Brew itself along with some important libs and repos 68 * macos:install:brew:all:fonts: Install Nerd-Fonts 69 * macos:install:brew:all:regular: Brew install regular recipes 70 * macos:install:core:all: Setup shell, core settings and tools 71 * macos:install:core:fzf: Install FuzzyFinder 72 * macos:install:core:nvim: Install Neovim nightly (macOS or Linux) 73 * macos:install:core:nvim:darwin: Install Neovim nightly on macOS 74 * macos:install:core:nvim:linux: Install Neovim nightly on Linux 75 * macos:install:core:profile: Setup shell profile settings 76 * macos:install:core:rosetta: Install Rosetta2 77 * macos:install:docker:all: Install Docker and container related tooling 78 * macos:install:docker:buildx: Install Docker Buildx 79 * macos:install:docker:rancher: Install Rancher Desktop 80 * macos:install:go:all: Install Go and all required modules/utils 81 * macos:install:go:all:deps: Download and Install Go installer 82 * macos:install:go:all:modules: Install required go modules 83 * macos:install:hammerspoon:all: Install Hammerspoon plugins 84 * macos:install:hammerspoon:all:spoons: Install Spoons 85 * macos:install:java:all: Install all Java requirements and tools 86 * macos:install:java:all:bfg: Install BFG Repo-Cleaner 87 * macos:install:java:all:maven: Install Maven 88 * macos:install:java:all:sdkman: Install SDKMan and Java Latest LTS 89 * macos:install:k8s:all: Setup Kubernetes related tooling 90 * macos:install:k8s:k3d: Install K3d 91 * macos:install:k8s:kubebuilder: Installs Kubebuilder 92 * macos:install:k8s:kustomize: Install Kustomize 93 * macos:install:k8s:operator-sdk: Install Operator-SDK 94 * macos:install:k8s:tilt: Install Tilt 95 * macos:install:rust:all: Install Rust and all required crates 96 * macos:install:rust:all:crates: Install required cargo packages 97 * macos:install:rust:all:deps: Install rustc and cargo 98 * nvim:deps: Install optional Neovim deps (tree-sitter-cli; use nvim:luarocks-build for rocks if using LuaRocks plugin) 99 * nvim:luarocks-build: Run LuaRocks.nvim build once (compiles local LuaRocks; then setup() installs rocks) 100 * nvim:reset: Backup ~/.local/share/nvim, ~/.local/state/nvim, ~/.cache/nvim with timestamped suffix (e.g. nvim.bak-YYYYMMDD-HHMMSS). 101 * test:lua: Run Lua Gherkin features (byfeature-style output with colors) and Busted specs 102 * version:next: Calculate next semver from conventional commits since last v* tag (feat→minor, fix→patch, breaking→major) 103 ``` 104 105 ## 🚀 Releases 106 107 Releases are created by pushing a **tag**: 108 109 ```bash 110 git tag v1.0.0 111 git push origin v1.0.0 112 ``` 113 114 Use **semver** (`vMAJOR.MINOR.PATCH`). The next version is computed from conventional commits since the last `v*` tag: 115 116 - **Major**: commit subject contains `!` (e.g. `feat!:`) or body contains `BREAKING CHANGE`. 117 - **Minor**: at least one `feat` commit. 118 - **Patch**: at least one `fix`, `docs`, `chore`, `ci`, etc., or any other commit (defaults to patch when there are commits). 119 120 To see the suggested next version before tagging, run from the repo root: 121 122 ```bash 123 task version:next 124 ``` 125 126 Then create and push the tag (e.g. `v0.0.1`): 127 128 ```bash 129 V=$(scripts/calc-next-version.sh) 130 git tag "$V" 131 git push origin "$V" 132 ``` 133 134 The release workflow runs `scripts/calc-next-version.sh` (needs only **git** and **bash**; no `jq`) to validate that the pushed tag matches the version calculated from conventional commits. It then: 135 136 1. Generates release notes (commits since the previous tag) with `git-cliff`. 137 2. Creates a GitHub Release with that body. 138 3. Regenerates the full `CHANGELOG.md` and commits it to the default branch. 139 140 All release steps use **devbox** in CI so the same tooling (`git-cliff`, `task`, etc.) is available; the version script itself does not require `jq` or any devbox packages. 141 142 If the release workflow does not run when you push a tag, ensure workflow files are on the default branch and Actions are enabled (Settings → Actions).