repowiserepowise is built so that upgrading is painless: upgrade the package, run
repowise update, and your existing index keeps working. A full reindex is
only ever recommended for a genuinely breaking change, never forced, and
repowise tells you exactly when and how.
The short version
uv tool upgrade repowise
cd your-repo
repowise update # picks up the new version against your existing indexpipx upgrade repowise
cd your-repo
repowise update # picks up the new version against your existing indexpip install -U repowise
cd your-repo
repowise update # picks up the new version against your existing indexThat's it. No reindex in the normal case.
What happens on upgrade
When you run repowise update (or repowise serve) after upgrading,
repowise:
Reads your store's format version and compares it to the running build. The on-disk store records which version wrote it, so repowise knows exactly what, if anything, an upgrade needs.
Applies any automatic, no-cost adjustments in place. New database columns are back-filled automatically. If your embedding model changed, vectors are re-embedded for you with no LLM calls. You don't run anything.
Keeps your parse cache warm. Ordinary releases do not invalidate cached work, so updates stay fast across releases.
Shows you what changed. A short "what's new" summary appears for the
versions you crossed, and repowise whats-new
prints the highlights and numbers any time. The dashboard's "update
available" banner names the next release's top highlights, and after a
minor upgrade the dashboard opens What's new once, with the release
summary, its numbers and every change (a patch shows a short note).
When a reindex is recommended
Rarely, a release changes the store format in a way an in-place migration can't cover. When that happens repowise keeps your existing index working and shows a clear notice with the exact command, for example:
Reindex recommended: repowise init --forceIt is a recommendation, not a requirement. Nothing is wiped until you choose to run it. You can keep using the current index and reindex when convenient.
What to do for each release
Nothing below needs a reindex. Each item says what to expect on the first update, or what to change in a script or config.
Upgrading to 0.58
| Topic | What to do |
|---|---|
| First update | Expect one longer update: health re-scores under the new scoring (HEALTH_ANALYZER_VERSION 41) and the parse cache refreshes once (PARSER_SCHEMA_VERSION 9, for Kotlin calls chained on calls). STORE_FORMAT_VERSION is unchanged, so no model is called and nothing needs re-indexing. repowise status names what the next update redoes. |
| Health marker ids | bumpy_road is repeated_nesting, and brain_method is listed without a deduction. Old ids keep working in .repowise/health-rules.json, findings and filters. |
get_health kpis | Read production_average for production code alone. non_code_files and average_health_code_only are not in the response. |
Scripted init | Read the exit code: 0 ready, 2 finished with gaps, 130 interrupted. --progress json gives a parseable event stream. --yes uses a logged-in Claude Code, Codex or OpenCode only with --provider. |
| Mode names | init, status, update and the editor files name an index Index only, Built from code or Written by <model>, each with its upgrade command. Flags, state.json and JSON values are unchanged, so scripts keep working. |
workspace add | The added repo's documentation is built from code by default. Pass --docs for a model. |
get_overview | Pass include=["scope"] for the whole index_scope, include=["tools"] for tool_surface, and include=["actions"] for the quarter's actions. git_health carries riskiest_files. |
| Dashboard links | Code Health's coverage, security, doc-drift and impact tabs open the Tests page, the Security page, Docs > Doc drift and Commits > Review a change. Old links redirect. |
Upgrading to 0.57
| Topic | What to do |
|---|---|
| Git history window | A new index reads the newest 5,000 commits. An existing index keeps the commit_limit its .repowise/config.yaml records, and update prints that value once. Set commit_limit: 5000 there to read the wider window. |
| Provider order | The CLI, repowise serve and the MCP server resolve provider, model and base URL in this order: the flag or dashboard choice, .repowise/config.yaml, the dashboard's global default, then REPOWISE_PROVIDER / REPOWISE_MODEL. A base URL in config.yaml takes precedence over OPENAI_BASE_URL and the other *_BASE_URL variables. If you set the model through environment variables, remove the value from config.yaml or change it there. |
| AI share fields | /commits/agent-trend returns per-label counts, coverage_pct and agent_pct_of_covered. The authorship filter accepts agent, human (human-attested) and unknown. get_context ownership carries one agent_share summary. Point scripts that read agent_pct or agent_authored_pct at these fields. |
get_answer diagnostics | Pass include=["diagnostics"] to read retrieval_quality. confidence is the one trust signal. |
| History markers | Ownership, churn and other history-only markers on production files are counted under history, outside the default defect lists. Scores, KPIs, get_risk and the work queue use them. |
| Change Records | The first update builds a Change Record for each first-parent commit in the history window, with no model call. |
Upgrading to 0.56
| Topic | What to do |
|---|---|
| First update | Expect one longer update: it reads the whole git history once, re-renders structural pages and reruns the security scan, with no model calls. Run repowise generate --stale to refresh prose pages it marks stale. |
search_codebase rows | Read path on each row. |
get_risk blocks | Pass include=["blast"] for pr_blast_radius and include=["owners"] for detailed owner metrics. |
repowise health | Bare repowise health reads the stored analysis. Pass --recompute to run it in process. |
Upgrading to 0.55
| Topic | What to do |
|---|---|
| First update | Expect one longer update: it re-scores and re-parses when the health analyzer or parser changed, even on an unchanged checkout. No model is called. |
| Unanalysed languages | Files in languages health cannot analyse read "not analysed" and stay out of averages and trends. |
get_health | Read fix_first for the lead work item. |
MCP _meta | Set REPOWISE_MCP_DEBUG_META=1 for diagnostics such as timing_ms, and REPOWISE_MCP_PRETTY_JSON=1 for indented JSON text. |
The full release notes are in the changelog.
Checking your version
- CLI:
repowise --version, orrepowise doctorfor an update check with the right upgrade command for your install method. - Dashboard: the version is shown in the sidebar footer, with a dot when a newer release is available.
See also
repowise whats-new: release notes since the version you last viewed.- The full release history lives on PyPI.
- Prefer not to manage upgrades at all? The hosted version always runs the latest engine.