gendiff

gendiff: upgrade Elixir generators from real diffs

Elixir code generators (phx.new, phx.gen.auth, nerves.new, scenic.new, …) scaffold an app once, then evolve across versions. Upgrading means reconciling an app that was generated by an old version with what a new version would emit. Doing that from memory is unreliable — flags change, files move, defaults flip.

https://elixirstream.dev builds a fresh app at each version+flag combination and diffs them for you. The /gendiff/api endpoints return an LLM-friendly Markdown index plus per-file patches, so you can fetch only what the task needs instead of blowing your context on hundreds of KB of diff.

Do not guess at generator changes when you can fetch the exact diff. Use these endpoints, read the changelog first, then pull the specific files you're touching.

The workflow

1. Determine the parameters from the user's actual project — don't invent them:

   • from / to: the old and new versions (e.g. the current {:phoenix, "~> 1.7.14"} in mix.exs and the target). Ask if the target is unstated.
   • project / command: which generator (see the table below). Default is phx_new / phx.new.
   • from_flags / to_flags: the generator flags the app was scaffolded with. Infer them from the repo — e.g. --binary-id if schemas use binary IDs, --database=sqlite3, --no-mailer, --adapter=bandit. Matching the real flags makes the diff reflect this app, not a stock one. Pass the same set to both from_flags and to_flags unless the user is intentionally changing a flag.

2. Fetch the index (start here, always):

   GET https://elixirstream.dev/gendiff/api?from=1.7.14&to=1.8.0&project=phx_new&command=phx.new&from_flags=--binary-id,--no-mailer&to_flags=--binary-id,--no-mailer
   

   Returns text/markdown: a how-to preamble, generator metadata, a changelog link, a summary (files/lines changed), and a list of changed files each with its own patch URL. Read the whole index — it's small.

3. Read the changelog before any file diff (only phx_new has one). The index links it, or fetch it directly:

   GET https://elixirstream.dev/gendiff/api/changelog?from=1.7.14&to=1.8.0&project=phx_new&command=phx.new
   

   The changelog explains intent — new features, deprecations, breaking changes — that raw diffs won't convey. This is the single most important step for a correct upgrade.

4. Fetch only the per-file patches you need, using the URLs from the index:

   GET https://elixirstream.dev/gendiff/api/file?from=1.7.14&to=1.8.0&project=phx_new&command=phx.new&from_flags=--binary-id,--no-mailer&to_flags=--binary-id,--no-mailer&file=config/config.exs
   

   Returns text/plain: the standalone unified diff for that one file. Pull the files relevant to the user's task (e.g. mix.exs, config/*, lib/*_web/*), not all of them. The index flags framework-vendored assets (e.g. assets/vendor/) as usually safe to skip.

5. Apply the changes to the real app — adapt, don't paste. The diff is a clean, newly-scaffolded app; a real app has customizations a fresh one doesn't:

   • Adapt each change to the target app; never copy-paste wholesale.
   • Do not delete code merely because it's absent in the diff — it may have been added deliberately.
   • The diff assumes those exact flags; different flags produce different output.

Parameters

Param	Required	Notes
from	yes	Source version, e.g. 1.7.14
to	yes	Target version, e.g. 1.8.0
project	no (default phx_new)	See table below
command	no (default phx.new)	Must belong to project
from_flags	no	Comma-separated generator flags for the source build
to_flags	no	Comma-separated generator flags for the target build

Query-param keys are case-insensitive. Flags are comma-separated (no spaces): from_flags=--binary-id,--database=sqlite3,--no-mailer.

Supported project → command

project	command	Changelog?
phx_new	phx.new, phx.gen.auth	✅ (phx.new only)
phx_gen_auth	phx.gen.auth	—
nerves_bootstrap	nerves.new	—
scenic_new	scenic.new, scenic.new.nerves, scenic.new.example	—
surface	surface.init	—
credo	credo.gen.config	—
rails	rails new	—
webpacker	rails webpacker:install	—

Common phx.new flags: --binary-id, --database=postgres|mysql|sqlite3|mssql, --adapter=bandit|cowboy, --no-mailer, --no-ecto, --no-html, --no-live, --no-dashboard, --no-assets, --no-gettext, --no-tailwind, --umbrella, --no-agents. Not every flag exists on every version; an unknown flag may be ignored or error.

Endpoint reference

• GET /gendiff/api → Markdown index (start here).
• GET /gendiff/api/changelog → text/markdown upstream changelog for the range.
• GET /gendiff/api/file?...&file=PATH → text/plain unified diff for one file.

Error responses come back as Markdown/plain text with a non-200 status: 400 (invalid params — the body lists which), 404 (no changelog / file not in diff), 502 (build failed), 504 (build timed out — retry shortly). On a build/timeout error, wait and retry; the first request for a new version pair triggers a build.

Example

User: "Help me upgrade my Phoenix app from 1.7.14 to 1.8.0."

1. Inspect the repo: mix.exs shows {:phoenix, "~> 1.7.14"}, schemas use binary_id, config uses Postgres, no mailer → flags --binary-id --no-mailer.
2. GET /gendiff/api?from=1.7.14&to=1.8.0&project=phx_new&command=phx.new&from_flags=--binary-id,--no-mailer&to_flags=--binary-id,--no-mailer
3. GET /gendiff/api/changelog?... — read it; note breaking changes.
4. For each file the upgrade touches, GET /gendiff/api/file?...&file=<path>.
5. Apply adapted changes to the real app; bump mix.exs; run mix deps.get and the test suite to verify.