Reproducible, in the Repository

Everything so far has been done to your machine. This chapter moves it into the repository, where it belongs — and it is the difference between a good personal setup and a good team.

The problem

Your machine is now excellent, and entirely undocumented. The PHP version this project needs lives in Grove's state; the services it needs live in your memory; the dev processes live in your habits.

Which produces the oldest problem in software: the new colleague's first two days. A README written once, drifted since, and a sequence of questions nobody enjoys on either side. And the quieter version of the same problem — you, on a new laptop, or you in eight months on a project you have not opened since.

Why the README does not work

A README is prose describing state, and the two drift apart immediately, in one direction: the setup changes and the document does not. Nothing breaks when the README goes stale, so nothing tells you it has — the only detector is a new person failing to follow it, which happens rarely and produces embarrassment rather than a fix.

Setup instructions in prose are also not checkable. “Install PHP 8.3” cannot be verified by anything; it can only be read and obeyed or misread and not.

One file, committed

grove up --write     # scaffold a starter grove.toml
grove up             # link + pin PHP/Node + start services + optional dev

# grove.toml
name = "freddy"
php = "8.5"
services = ["mysql", "redis"]
dev = true

Commit it. Now the environment is described in the place that cannot drift from the code, because it is versioned with the code: the commit that requires PHP 8.5 is the commit that says so.

A teammate clones the repository and runs one command:

git clone git@github.com:you/freddy.git
cd freddy
grove up

Bringing up freddy…
  ✓ link
  ✓ https on
  ✓ php 8.5
  ✓ mysql
  ✓ redis
  ✓ dev
✓ freddy is up → https://freddy.test

Linked, secured, pinned, services running, dev processes started. From clone to working in one command, on a machine that has never seen this project.

What this actually fixes

• Onboarding stops being a ritual. The first day is spent reading code rather than installing things.
• “Works on my machine” gets narrower. The runtime and the services are the same by construction, so when behaviour differs the cause is somewhere more interesting.
• Old projects come back to life. The client project you last touched in March opens without archaeology, because the file remembers what you do not.
• Upgrades become reviewable. Moving to PHP 8.5 is a one-line diff in a pull request, discussed and merged like any other change, rather than a message in Slack asking everyone to please switch.

When one command is still too many

Grove can also produce a bundle: a reproducible snapshot of an environment. The distinction is worth holding on to — grove.toml describes what to build, a bundle captures what was built. The first is what you commit and live with; the second is for handing an exact environment to someone, or to yourself later, without rebuilding it from its description.

What you learned

• A README is prose describing state, and nothing breaks when it goes stale — so nothing tells you.
• grove.toml is versioned with the code, so the commit that needs PHP 8.5 is the commit that says so.
• One command from clone to running, on a machine that has never seen the project.
• Upgrades become a reviewable one-line diff instead of a message asking everyone to switch.
• grove.toml describes what to build; a bundle captures what was built.
• Commit it even alone. In a year you are a new team member on your own project.