brunch 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f77dd24e00604eea2485dff005164094eb6f6e8633d81e96616df5bf25420ef2
-  data.tar.gz: 578505da516fbd81dfdd6c54e397ac0d4861e25e7af5b482a6e4f8fcf2aa4043
+  metadata.gz: 318ff646dd610a9647612d8ea0fcc446e5122215f4517d665fc639b5bfca740d
+  data.tar.gz: e4aeddec12c82d9b0d33caddf6a366840e3db8badd45fec4114f57bd034c3d86
 SHA512:
-  metadata.gz: c80c84a7078a91a71c69517d68d9b5093d13c6e97b8662e5ec98aecf2b2d2b07daaa49713da6046c51ca16c41c63cc58b50c2e6c286f1c5ede0ed0c3f2ce5ab2
-  data.tar.gz: 759c3e32ad7957cdec4b3babe27ad211262ce4f177b0ce6a2f4a0f9d3db26ed81ed332c930e2690e7cc3f9195f7528a5fa80b5ddf8cd4aa7063c32f9e0c18648
+  metadata.gz: d334e9cc379f39f4866626e8801adbdc9cbe8aace2d0249b8b4a6a81020b34ec35eca8b8dcf742622e06545d58086966ed087784b077460bdc7e56e5ec150f1c
+  data.tar.gz: b34f7f1baf8dbbf6a56669ccc310846eab6aa23d891fa05e4adbe541e1ab1ccea954bfdb46c087fba7a47e3601f45f967efb1de8ff93d7678cb361abaec6eb1c

data/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.8.1 - 2026-09-29
+
+- Reorganize the README into a step-by-step guide for branches, parallel
+  worktrees, managers, and everyday commands.
+
 ## 0.8.0 - 2026-09-29
 
 - Use one worktree-based lifecycle for both branch switches and parallel

data/README.md

@@ -2,51 +2,46 @@
 
 ![Brunch — container per branch and worktree](brunch.webp)
 
-Brunch runs isolated development environments for Git worktrees. The main
-checkout is a worktree too: switching branches there reuses its port, while
-additional worktrees run in parallel on different host ports. Docker Compose
-is the default manager; Podman
-Compose, local processes, and project commands are also supported.
+Brunch runs isolated development environments for Git branches and worktrees.
 
-Each branch environment has a distinct Compose project name, network, and
-named volumes. The active environment runs from its live worktree directory,
-including uncommitted changes when the manager rebuilds or reloads the app.
+Each branch gets its own environment. With Compose, that means a separate project, network, containers, and named volumes. Branches checked out in the same worktree share its host port, while additional worktrees get different ports and can run in parallel.
+
+Docker Compose is the default manager. Podman Compose, local processes, and custom project commands are also supported.
 
 ## Requirements
 
-- Ruby 3.1 or newer
-- Git 2.28 or newer
-- A supported environment manager: Docker Compose, Podman Compose, or project commands
-- [`git-hooks-ext`](https://github.com/ciembor/git-hooks-ext)
+- Ruby 3.1+
+- Git 2.28+
+- Docker Compose, Podman Compose, or another supported manager
+- [git-hooks-ext](https://github.com/ciembor/git-hooks-ext)
 
 ## Installation
 
-Install [`git-hooks-ext`](https://github.com/ciembor/git-hooks-ext) so that
-`ghe` is on your `PATH`, then install Brunch:
+Install [git-hooks-ext](https://github.com/ciembor/git-hooks-ext) so that `ghe` is available on your `PATH`, then install Brunch:
 
-```sh
+```bash
 gem install brunch
 ```
 
-Run `brunch install` inside each Git repository you want Brunch to manage.
-It installs the `git-hooks-ext` bridge and project-local hooks, and refuses
-to replace an existing hook owned by another tool.
+Inside each repository you want Brunch to manage:
+
+```bash
+brunch install
+```
+
+Brunch installs its hooks through `git-hooks-ext` and will not overwrite hooks owned by another tool.
 
-## Project configuration
+## Configuration
 
-Add `brunch.yml` to the project root. Docker Compose is the default, so the
-following remains sufficient for Compose projects:
+Add `brunch.yml` to the repository root.
+
+For Docker Compose:
 
 ```yaml
 compose_file: compose.yaml
 ```
 
-The referenced Compose file belongs to the application. Brunch does not impose
-a database or service stack: applications may define PostgreSQL, MySQL, Redis,
-Sidekiq, Elasticsearch, or any other services they need.
-Unknown `brunch.yml` fields are errors, so configuration typos are not ignored.
-
-Expose the application port with `BRUNCH_PORT`:
+Expose the application through `BRUNCH_PORT`:
 
 ```yaml
 services:
@@ -55,121 +50,134 @@ services:
       - "127.0.0.1:${BRUNCH_PORT}:3000"
 ```
 
-The first activated worktree prefers `127.0.0.1:3000`. Every worktree keeps
-its assigned host port while its branches take turns using it. Other worktrees
-receive a different free port; running containers can never bind the same host
-address and port. To prefer another starting port, set `preferred_port: 4000`.
-Brunch persists assignments privately in `.git/brunch/state.json`.
+The first activated worktree prefers port `3000`. Additional worktrees receive another free port.
 
-## Using Brunch
+To prefer a different starting port:
 
-First, commit `brunch.yml` and your Compose file (or the configuration for
-another manager). The repository needs at least one commit before Brunch can
-start an environment. Install the hooks once per repository, then activate
-the checked-out branch:
+```yaml
+preferred_port: 4000
+```
 
-```sh
+Port assignments are persisted per worktree in `.git/brunch/state.json`.
+
+## Getting started
+
+Commit `brunch.yml` and the application configuration first. The repository must contain at least one commit.
+
+Then run:
+
+```bash
 brunch install
 brunch doctor
 brunch activate
 brunch status
+```
+
+`brunch activate` starts the environment for the currently checked-out branch.
+
+To print only the current worktree's port:
+
+```bash
 brunch port
 ```
 
-Open `http://127.0.0.1:3000` if port 3000 is free, or use the port printed by
-`brunch activate` / `brunch port`. Brunch starts the application in the
-background. With Compose, the app must listen on the container port mapped in
-`compose.yaml`.
+Open the application on the printed port, for example:
 
-### Branches in one checkout
+```text
+http://127.0.0.1:3000
+```
+
+With Compose, the application must listen on the container port mapped in the Compose file.
+
+## Branch switching
 
-Once the hooks are installed, ordinary Git branch switches stop the old
-environment and start the new one automatically:
+Once the hooks are installed, normal Git branch switches automatically stop the previous branch environment and start the new one:
 
-```sh
+```bash
 git switch -c feature/login
-brunch status
 git switch main
 ```
 
-Both branches use this checkout's assigned host port. With Compose, they keep
-separate projects and volumes. To start the checked-out branch manually (for
-example, after `brunch stop`), run `brunch activate`. Run `brunch restart` to
-rebuild it after changing files that are copied into the image.
+Branches checked out in the same worktree reuse that worktree's host port.
 
-### Parallel worktrees
+With Compose, each branch keeps its own Compose project and named volumes, so persistent resources remain isolated between branches.
 
-There is no mode switch. Commit the same `brunch.yml` in your repository, then
-create additional worktrees. Run `brunch install` again after upgrading Brunch
-to install its worktree hooks.
+To manually start the environment after `brunch stop`:
 
-```sh
+```bash
+brunch activate
+```
+
+To rebuild and restart it:
+
+```bash
+brunch restart
+```
+
+Compose builds use files from the live worktree, including uncommitted changes.
+
+If you want source edits to appear in an already running container without rebuilding, configure a bind mount or another reload mechanism in your Compose setup.
+
+## Parallel worktrees
+
+Additional worktrees run independently on different host ports.
+
+Create them with `git-hooks-ext`:
+
+```bash
 ghe worktree add -b feature-a ../feature-a
 ghe worktree add -b feature-b ../feature-b
+```
+
+Then:
+
+```bash
 cd ../feature-a
-brunch port        # port for this worktree
-brunch ports       # ports for all worktrees
-```
-
-Each worktree runs independently on a different host port, so `feature-a` and
-`feature-b` can be used at the same time. Run `brunch status` or `brunch port`
-inside each worktree to find its address. Switching branches inside one
-worktree does not stop the others.
-
-`ghe worktree add`, `move`, and `remove` emit lifecycle events. Git's
-`post-checkout` hook handles branch changes inside any worktree, including the
-main checkout. If you use plain `git worktree add`, run `brunch activate` in the
-new worktree; after a plain move or removal, run `brunch cleanup` from a
-remaining worktree.
-
-The source directory is never deleted by Brunch. It keeps a separate control
-copy under `.git/brunch/controls` so it can shut down Compose or run a custom
-`remove` command after a worktree has been removed. Switching branches within
-one worktree keeps the old branch's environment stopped, with its own named
-volumes. Removing the worktree removes all of its Brunch environments. The
-`local_process` manager also writes its log to the control directory, keeping
-the worktree clean. Custom `remove` commands that depend on project files must
-be committed, because the control copy is based on the worktree's last commit.
-
-Docker builds read uncommitted files from the live worktree. To see edits in
-an already running container without rebuilding, configure a source bind
-mount or another reload mechanism in the project's Compose file.
-`brunch restart` rebuilds the current environment.
-
-Before upgrading from an older branch-only configuration, stop its running
-environment and clean up its legacy state. Brunch refuses to reinterpret an
-old non-empty branch state as worktree state, preventing orphaned containers.
-
-### Custom manager commands
-
-Use the `command` manager when the project is started by another tool. Brunch
-runs commands from the live worktree with these variables: `BRUNCH_REF`,
-`BRUNCH_PORT`, `BRUNCH_PROJECT`, and `BRUNCH_SNAPSHOT`. The last variable points
-to the live worktree for compatibility with manager adapters.
 
-```yaml
-manager: command
-commands:
-  create: bin/environment create
-  start: bin/environment start
-  stop: bin/environment stop
-  remove: bin/environment remove
+brunch port
+brunch ports
 ```
 
-`create` provisions manager-owned resources; it is optional for the `command`
-manager. `start` must return after
-it has launched the environment (for example, by delegating to a daemon or
-supervisor). `stop` is used when switching branches; `remove` is used when
-a worktree is deleted and should remove any manager-owned persistent
-resources. This makes the adapter suitable for Podman, Kubernetes wrappers,
-Foreman/Overmind wrappers, or a project-specific script.
+`brunch port` prints the current worktree's port.
 
-Optional `status`, `health`, and `logs` commands power the corresponding Brunch
-commands. A successful `health` command reports a healthy environment.
+`brunch ports` lists ports assigned to all worktrees.
+
+Switching branches inside one worktree does not affect environments running in other worktrees.
+
+If you create a worktree with plain Git:
+
+```bash
+git worktree add -b feature-c ../feature-c
+```
+
+activate Brunch manually inside it:
+
+```bash
+cd ../feature-c
+brunch activate
+```
+
+After moving or removing worktrees with plain Git, run:
+
+```bash
+brunch cleanup
+```
+
+Brunch never deletes the worktree source directory.
+
+## Managers
+
+### Docker Compose
+
+Docker Compose is the default manager:
+
+```yaml
+compose_file: compose.yaml
+```
 
 ### Podman Compose
 
-Podman Compose uses the same Compose file contract as Docker Compose:
+Podman Compose uses the same Compose file contract:
 
 ```yaml
 manager: podman_compose
@@ -178,66 +186,170 @@ compose_file: compose.yaml
 
 ### Local process
 
-Use `local_process` for a development command such as `bin/dev`.
-Brunch starts it in a dedicated process group, records its PID, stops that
-group on a branch switch, and saves its output under `.git/brunch/controls`.
+Use `local_process` for a development command such as `bin/dev`:
 
 ```yaml
 manager: local_process
 command: bin/dev
 ```
 
-## Lifecycle
+Brunch starts and stops the process together with the branch environment and stores its output under `.git/brunch/controls`.
+
+### Custom commands
+
+Use the `command` manager to integrate Brunch with project-specific tooling:
+
+```yaml
+manager: command
+commands:
+  create: bin/environment create
+  start: bin/environment start
+  stop: bin/environment stop
+  remove: bin/environment remove
+```
+
+Brunch runs these commands from the live worktree with:
+
+```text
+BRUNCH_REF
+BRUNCH_PORT
+BRUNCH_PROJECT
+BRUNCH_SNAPSHOT
+```
+
+`BRUNCH_SNAPSHOT` points to the live worktree for compatibility with manager adapters.
+
+`create` is optional.
+
+`start` must return after launching the environment.
+
+`stop` is called when switching away from the active branch.
+
+`remove` is called when the corresponding worktree environment is deleted and should remove manager-owned persistent resources.
+
+Optional commands:
+
+```yaml
+commands:
+  status: bin/environment status
+  health: bin/environment health
+  logs: bin/environment logs
+```
+
+These power the corresponding Brunch operations.
+
+## Worktree lifecycle
+
+A branch checkout stops the previous environment in that worktree and starts the new one on the same host port.
 
-- A branch checkout stops the previous environment in that worktree, then
-  creates and starts the new one on the same port.
-- Each worktree keeps its own current environment and port. Other worktrees
-  continue running during branch switches.
-- Checking out a remote branch into a new local tracking branch works through
-  the same `post-checkout` hook.
-- `brunch cleanup` removes environments belonging to deleted worktrees.
+Other worktrees continue running.
 
-Git 2.39 cannot reliably report a normal `git branch -d` operation to a hook.
-Stopped branch environments remain until their worktree is removed.
+Removing a worktree removes its Brunch environments. Brunch keeps the information needed to shut down manager resources under `.git/brunch/controls`, so cleanup can still run after the worktree itself is gone.
 
-## Operations
+If a custom `remove` command depends on project files, those files must be committed because cleanup after worktree removal uses the last committed state.
 
-```sh
-brunch status    # current worktree environment, manager status and port
-brunch ports     # worktree-to-port list; current worktree is marked in green
-brunch port      # only the current worktree's port, suitable for scripts
-brunch stop      # stop the active environment without deleting it
-brunch restart   # recreate and start the active environment
-brunch logs      # show the last 100 logs (or run commands.logs)
+`brunch cleanup` removes environments belonging to worktrees that no longer exist.
+
+Git does not expose every branch deletion workflow reliably to hooks, so stopped branch environments may remain until their worktree is removed.
+
+## Commands
+
+```bash
+brunch install
+```
+
+Install Brunch hooks for the repository.
+
+```bash
+brunch activate
+```
+
+Start the environment for the current branch.
+
+```bash
+brunch status
+```
+
+Show the current environment, manager status, and port.
+
+```bash
+brunch port
+```
+
+Print the current worktree's port.
+
+```bash
+brunch ports
+```
+
+List ports assigned to all worktrees.
+
+```bash
+brunch stop
+```
+
+Stop the active environment without removing it.
+
+```bash
+brunch restart
+```
+
+Recreate and start the active environment.
+
+```bash
+brunch logs
 brunch logs --follow
-brunch run -- bin/rails console  # runs on the host in the live worktree, not in a container
-brunch doctor    # verify Git, installed hooks, configuration, manager and ports
-brunch cleanup   # delete environments for removed worktrees
 ```
 
-Brunch coordinates commands with locks under `.git/brunch`, writes `state.json`
-atomically, and retries interrupted environment setup on the next activation.
+Show environment logs.
+
+```bash
+brunch run -- bin/rails console
+```
+
+Run a command on the host from the live worktree.
+
+```bash
+brunch doctor
+```
+
+Check Git, installed hooks, configuration, manager availability, and ports.
+
+```bash
+brunch cleanup
+```
+
+Remove environments belonging to deleted worktrees.
+
+## Upgrading from older configurations
+
+Before upgrading from an older branch-only configuration, stop its running environment and clean up its legacy state.
+
+Brunch will not reinterpret an existing non-empty branch-only state as worktree state.
 
 ## Development
 
-```sh
+```bash
 bundle install
 bin/install-pre-commit
 bundle exec rake quality
 gem build brunch.gemspec
 ```
 
-Container E2E tests use real temporary Git repositories, Compose containers,
-and HTTP requests. Run them with Docker or Podman:
+Run container integration tests with Docker Compose:
 
-```sh
+```bash
 BRUNCH_INTEGRATION_MANAGER=docker_compose bundle exec rake test
+```
+
+Or Podman Compose:
+
+```bash
 BRUNCH_INTEGRATION_MANAGER=podman_compose bundle exec rake test
 ```
 
-CI runs both managers on pushes and pull requests. Without the environment
-variable, container tests are skipped by the local quality check.
+Without `BRUNCH_INTEGRATION_MANAGER`, container integration tests are skipped by the local quality check.
+
+The pre-commit hook runs RuboCop with automatic corrections, Reek, and the full test suite. SimpleCov requires 100% line and branch coverage for `lib/**/*.rb`.
 
-The pre-commit hook runs RuboCop with automatic corrections, Reek, and the full
-test suite. SimpleCov requires 100% line and branch coverage of `lib/**/*.rb`. When
-RuboCop changes a file, review and stage the correction before committing.
+If RuboCop modifies a file, review and stage the changes before committing.

data/lib/brunch/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Brunch
-  VERSION = "0.8.0"
+  VERSION = "0.8.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brunch
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Maciej Ciemborowicz