From d09d1c262f2f235e9561066ec0f5c67d5d86cace Mon Sep 17 00:00:00 2001
From: Ismo Vuorinen <ismo@ivuorinen.net>
Date: Tue, 24 Feb 2026 21:49:12 +0200
Subject: [PATCH] docs: rewrite README with install, usage, and dev sections
 (#47)

The previous README was minimal (17 lines). Expand it with requirements,
installation (Composer + PHAR), usage with example output, development
commands, and a CI status badge.
---
 README.md | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 86 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index ec65ab6..aca3e92 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,95 @@
-# Branch usage checker
+# Branch Usage Checker
 
-[![Packagist Version][pkg-shield]][packagist] [![License][license]][packagist]
+[![Packagist Version][pkg-shield]][packagist]
+[![License][license-shield]][packagist]
+[![CI][ci-shield]][ci]
 
-## Check when your package branches have last been used
+A CLI tool that cross-references GitHub branches with Packagist download
+statistics to identify branches safe to delete. Configure a lookback window
+(default 9 months), review a statistics table of per-branch downloads, and
+get a suggestion list of zero-download branches you can clean up.
 
-Use this command line tool to cross-check project public GitHub Branches and
-Packagist branch download statistics to determine are branches safe to delete.
+## Requirements
+
+- PHP 8.4+
+
+## Installation
+
+### Composer (global)
+
+```bash
+composer global require ivuorinen/branch-usage-checker
+```
+
+### PHAR
+
+Download the latest `branch-usage-checker` PHAR from
+[GitHub Releases][releases], then:
+
+```bash
+chmod +x branch-usage-checker
+./branch-usage-checker check <vendor/package>
+```
+
+## Usage
+
+```text
+branch-usage-checker check <vendor/package> [months]
+```
+
+| Argument         | Description            | Default |
+|------------------|------------------------|---------|
+| `vendor/package` | Packagist package name |         |
+| `months`         | Months to look back    | `9`     |
+
+### Example
+
+```text
+$ branch-usage-checker check ivuorinen/branch-usage-checker 6
+
+ Branch usage statistics for ivuorinen/branch-usage-checker
+ ┌────────────────────┬────────┬────────┬────────┬────────┬────────┬────────┐
+ │ Branch             │ 2025-7 │ 2025-8 │ 2025-9 │ 2025-… │ 2025-… │ 2025-… │
+ ├────────────────────┼────────┼────────┼────────┼────────┼────────┼────────┤
+ │ dev-master         │     42 │     38 │     51 │     47 │     55 │     60 │
+ │ dev-feat/dto       │      0 │      0 │      0 │      0 │      0 │      0 │
+ │ dev-fix/timeouts   │      3 │      1 │      0 │      0 │      0 │      0 │
+ └────────────────────┴────────┴────────┴────────┴────────┴────────┴────────┘
+
+ Suggestions — branches with zero downloads (safe to delete)
+ ┌────────────────────┐
+ │ Branch             │
+ ├────────────────────┤
+ │ dev-feat/dto       │
+ └────────────────────┘
+```
+
+## Development
+
+```bash
+git clone https://github.com/ivuorinen/branch-usage-checker.git
+cd branch-usage-checker
+composer install
+```
+
+| Command           | Description                      |
+|-------------------|----------------------------------|
+| `composer test`   | Run tests (Pest)                 |
+| `composer lint`   | Check code style (PHPCS, PSR-12) |
+| `composer format` | Auto-fix code style (PHPCBF)     |
+| `composer build`  | Build PHAR to `builds/`          |
+
+Pre-commit hooks ([CaptainHook][captainhook]) are installed automatically and
+will run PHPCBF + PHPCS on staged PHP files.
 
 ## License
 
-Branch usage checker is an open-source software licensed under the MIT license.
+MIT — see [LICENSE](LICENSE) for details.
 
 [packagist]: https://packagist.org/packages/ivuorinen/branch-usage-checker
 [pkg-shield]: https://img.shields.io/packagist/v/ivuorinen/branch-usage-checker
-[license]: https://img.shields.io/packagist/l/ivuorinen/branch-usage-checker.svg
+[license-shield]: https://img.shields.io/packagist/l/ivuorinen/branch-usage-checker.svg
+[ci-shield]: https://img.shields.io/github/actions/workflow/status/ivuorinen/branch-usage-checker/test-and-build.yml?branch=master&label=CI
+[ci]: https://github.com/ivuorinen/branch-usage-checker/actions/workflows/test-and-build.yml
+[releases]: https://github.com/ivuorinen/branch-usage-checker/releases
+[captainhook]: https://github.com/captainhookphp/captainhook