Upgrade Guide

Reepolee projects begin as copies of the open-source repository. When a newer version contains changes you want, use Reesync to compare a fresh checkout with your project and selectively copy the files you choose. Reepolee is pre-1.0, so inspect every proposed change and make any project-specific adjustments it needs.

Before you start

Commit or otherwise back up your current project first. Reesync writes only the files you explicitly select, but it overwrites those selected files in place.

Install Reesync once if it is not already on your PATH:

macOS / Linux
curl -fsSL https://raw.githubusercontent.com/reepolee/reesync/main/install.sh | bash
Windows
irm https://raw.githubusercontent.com/reepolee/reesync/main/install.ps1 | iex

Verify the install:

reesync --version

Manual-install options are in the Reesync installation guide.

Compare a newer version

Clone the current Reepolee source outside your project. Then run Reesync from the root of your project:

git clone https://github.com/reepolee/reepolee.git /tmp/reepolee-new

cd ~/code/my-application
reesync /tmp/reepolee-new

The fresh checkout is read-only from Reesync's point of view. Your current project is the only directory it writes to.

Choose the changes to adopt

Reesync presents only files that differ:

  1. New and modified starter files are pre-selected.
  2. Use arrow keys to browse and Space to select or clear a file or folder.
  3. Press i to add a project-owned file to .reesyncignore; it stays visible but is pre-cleared on future runs.
  4. Press Enter only after reviewing the selection. Reesync copies the selected files and shows progress.

Files that exist only in your project are shown as deleted in the comparison, but Reesync never deletes them. Hidden files, including .env, .gitignore, and .reesyncignore, are not compared or copied.

The Reesync command-line reference has the complete key bindings and ignore-pattern rules.

Review project-owned files carefully

The starter ships a .reesyncignore with common project-owned paths. Keep it specific to your project. In a Reepolee application, review these changes deliberately before selecting them:

  • routes/routes.ts and generated route folders, which may contain your application routes and customisations.
  • config/supported_locales.ts, package.json, and .env-adjacent setup.
  • SQL files and translation data, which need to match your application data.
  • Any component, layout, or static asset you have changed for your own UI.

Reesync makes the copy decision file by file; it does not interpret schemas, merge source code, or change your database.

Upgrading to 26.07.75

This release introduces a required row-display contract for generator metadata. Before running bun reeman crud, schema, or refresh-crud against an existing database, add a string generated display column to every application table. Add an optional generated option_display only where selectors need more context than the canonical label.

Update every v_<table> view too: it must expose a string display, and any joined FK needs a <relationship>_display alias, such as developer_display for developer_id. Then regenerate the affected CRUD routes. Each generator command reads a fresh in-memory schema snapshot, so there is no DDL-cache rescan step. Review the generated grids and selectors before adopting them: raw FK IDs are replaced by the resolved display columns.

Take the accompanying config/db_structure.ts update if you customise it. It reserves display and option_display from default grids while retaining canonical display as a sort choice.

Verify after syncing

Review the resulting diff, then run the normal project checks appropriate to the files you adopted. A typical Reepolee pass is:

bun install
bun run css:build
bun test

Start the app locally and test the routes, forms, translations, and database paths affected by the selected files. The Release Notes describe what each release includes; use them to decide which changes to review.