/ 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 * changelog:rewrite-history: Rewrite all commit messages to conventional format (DESTRUCTIVE; backup first, then force-push) 49 * common:install:core:all: Setup shell, core settings and tools (cross-platform) 50 * common:install:core:fzf: Install FuzzyFinder 51 * common:install:core:lua: Install Lua from source (for Neovim etc.) 52 * common:install:core:nvim: Install Neovim nightly (macOS or Linux) 53 * common:install:core:nvim:darwin: Install Neovim nightly on macOS 54 * common:install:core:nvim:linux: Install Neovim nightly on Linux 55 * common:install:core:profile: Setup shell profile settings (cross-platform) 56 * devbox:install: Install devbox dependencies (run once after clone or when devbox.json changes) 57 * devbox:install-cli: Install Devbox CLI (required before devbox:install; uses official install script) 58 * devbox:shell: Enter devbox shell with all dev tools on PATH 59 * linux:install:all: Install base packages and core setup on Linux (apt + common core) 60 * linux:install:apt:all: Install base OS packages (Debian/Ubuntu) 61 * macos:install:all: Install all MacOS required tools 62 * macos:install:brew:all: Brew install all packages 63 * macos:install:brew:all:custom: Brew install recipes with custom steps 64 * macos:install:brew:all:custom:colima: Brew install Colima 65 * macos:install:brew:all:deps: Install Brew itself along with some important libs and repos 66 * macos:install:brew:all:fonts: Install Nerd-Fonts 67 * macos:install:brew:all:regular: Brew install regular recipes 68 * macos:install:core:all: Setup shell, core settings and tools 69 * macos:install:core:fzf: Install FuzzyFinder 70 * macos:install:core:nvim: Install Neovim nightly (macOS or Linux) 71 * macos:install:core:nvim:darwin: Install Neovim nightly on macOS 72 * macos:install:core:nvim:linux: Install Neovim nightly on Linux 73 * macos:install:core:profile: Setup shell profile settings 74 * macos:install:core:rosetta: Install Rosetta2 75 * macos:install:docker:all: Install Docker and container related tooling 76 * macos:install:docker:buildx: Install Docker Buildx 77 * macos:install:docker:rancher: Install Rancher Desktop 78 * macos:install:go:all: Install Go and all required modules/utils 79 * macos:install:go:all:deps: Download and Install Go installer 80 * macos:install:go:all:modules: Install required go modules 81 * macos:install:hammerspoon:all: Install Hammerspoon plugins 82 * macos:install:hammerspoon:all:spoons: Install Spoons 83 * macos:install:java:all: Install all Java requirements and tools 84 * macos:install:java:all:bfg: Install BFG Repo-Cleaner 85 * macos:install:java:all:maven: Install Maven 86 * macos:install:java:all:sdkman: Install SDKMan and Java Latest LTS 87 * macos:install:k8s:all: Setup Kubernetes related tooling 88 * macos:install:k8s:k3d: Install K3d 89 * macos:install:k8s:kubebuilder: Installs Kubebuilder 90 * macos:install:k8s:kustomize: Install Kustomize 91 * macos:install:k8s:operator-sdk: Install Operator-SDK 92 * macos:install:k8s:tilt: Install Tilt 93 * macos:install:rust:all: Install Rust and all required crates 94 * macos:install:rust:all:crates: Install required cargo packages 95 * macos:install:rust:all:deps: Install rustc and cargo 96 * nvim:deps: Install optional Neovim deps (tree-sitter-cli; use nvim:luarocks-build for rocks if using LuaRocks plugin) 97 * nvim:luarocks-build: Run LuaRocks.nvim build once (compiles local LuaRocks; then setup() installs rocks) 98 * nvim:reset: Backup ~/.local/share/nvim, ~/.local/state/nvim, ~/.cache/nvim with timestamped suffix (e.g. nvim.bak-YYYYMMDD-HHMMSS). 99 * test:lua: Run Lua Gherkin features (byfeature-style output with colors) and Busted specs 100 * version:next: Calculate next semver from conventional commits since last v* tag (feat→minor, fix→patch, breaking→major) 101 ``` 102 103 ## 🚀 Releases 104 105 Releases are created by pushing a **tag**: 106 107 ```bash 108 git tag v1.0.0 109 git push origin v1.0.0 110 ``` 111 112 Use **semver** (`vMAJOR.MINOR.PATCH`). The next version is computed from conventional commits since the last `v*` tag: 113 114 - **Major**: commit subject contains `!` (e.g. `feat!:`) or body contains `BREAKING CHANGE`. 115 - **Minor**: at least one `feat` commit. 116 - **Patch**: at least one `fix`, `docs`, `chore`, `ci`, etc., or any other commit (defaults to patch when there are commits). 117 118 To see the suggested next version before tagging, run from the repo root: 119 120 ```bash 121 task version:next 122 ``` 123 124 Then create and push the tag (e.g. `v0.0.1`): 125 126 ```bash 127 V=$(scripts/calc-next-version.sh) 128 git tag "$V" 129 git push origin "$V" 130 ``` 131 132 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: 133 134 1. Generates release notes (commits since the previous tag) with `git-cliff`. 135 2. Creates a GitHub Release with that body. 136 3. Regenerates the full `CHANGELOG.md` and commits it to the default branch. 137 138 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. 139 140 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).