Refactor

stategraph refactor is a session-based workflow that tracks HCL changes across successive plans and emits Terraform moved blocks when you're done. Use it when you're renaming resources, restructuring modules, or moving things between files and you want Stategraph to keep the state mapping in sync without hand-writing every moved block.

When to use refactor mode

Use stategraph refactor when you're making structural HCL changes like:

  • Renaming a resource (aws_instance.web → aws_instance.frontend)
  • Moving a resource into or out of a module
  • Renaming a module
  • Restructuring files without changing the actual infrastructure

Refactor mode detects these changes at each step and maps old addresses to new ones. When you complete the session, it writes the mappings to a moved blocks file that Terraform picks up automatically.

Workflow

A refactor session has four phases: start, one or more step calls as you make edits, then complete or abort.

# 1. Start a session from your root module
stategraph refactor start

# 2. Make HCL edits, then run step to detect changes
stategraph refactor step

# 3. Continue editing and stepping until you're done
stategraph refactor step

# 4. Complete the session to write moved blocks
stategraph refactor complete

If you want to throw the session away:

stategraph refactor abort

Session state lives in the .stategraph directory alongside your root module.

Commands

stategraph refactor start

Starts a refactoring session. Snapshots the current HCL and state so later step calls have something to diff against. Run this from the root of your Terraform module.

stategraph refactor start

stategraph refactor step [OLD=NEW ...]

Detects what changed since the last start or step and maps removed addresses to added addresses. Prints each detected mapping as OLD -> NEW.

If the automatic detection can't figure out where something moved (for example, when a resource was renamed and simultaneously had its attributes changed), step exits non-zero and lists the unmatched added and removed addresses. Pass explicit mappings to resolve them:

stategraph refactor step aws_instance.web=aws_instance.frontend

You can pass multiple mappings, one per argument. Run step as many times as you need during a refactor.

stategraph refactor complete

Finalizes the session and writes the accumulated mappings to a moved blocks file in your module (printed at the end of the command). Terraform and OpenTofu automatically apply moved blocks on the next plan, so your state follows the refactor without manual terraform state mv calls.

stategraph refactor complete

stategraph refactor abort

Discards the current session and removes its state. Use this if you decide to back out of the refactor, or if the session got into a bad state and you want to start over.

stategraph refactor abort

Notes

  • Refactor mode is scoped to the module you ran start in. Run it from the same directory you run stategraph tf plan in.
  • The session is persisted in .stategraph/ — don't commit that directory mid-refactor.
  • Refactor mode currently handles HCL-visible moves. Changes that happen entirely inside provider behavior (e.g., an upstream provider renaming an attribute) aren't refactor-mode territory.

Next Steps