README
¶
pawnmigrate
pawnmigrate updates Pawn projects without hiding what it plans to change.
It covers project upgrades and source migrations. This includes moving an existing sampctl project to PawnKit and replacing one Pawn library with another. A library migration may update dependencies, includes, calls, callbacks, tags, and configuration as one reviewed plan.
Install
Download a binary from the release page, or install it with Go:
go install github.com/pawnkit/pawnmigrate/cmd/pawnmigrate@latest
Check the installed version with pawnmigrate --version.
Start with a diff:
pawnmigrate --project . --output diff
If the diff looks right, apply it from a clean Git worktree:
pawnmigrate --project . --apply
Files are checked again before they are written. If a write fails, pawnmigrate tries to restore earlier files. Pawn source is formatted after migration.
To see which rules apply without building a plan:
pawnmigrate --project . --status
The default run includes only migrations marked safe. Pass --allow-unsafe to
include changes that need review, then inspect the diff before applying them.
Use --only to run specific migrations:
pawnmigrate --project . --only project.manifest-schema-v1,source.openmp-include --output diff
JSON output is available for tools and CI with --output json. --allow-dirty bypasses the clean-worktree check, but it also makes recovery harder.
Exit code 0 means the command completed, 2 reports invalid input or a
migration failure, and 3 reports an output or internal failure.
See migration compatibility for the rules currently shipped.
Scope
pawnmigrate is not limited to the sampctl transition. Built-in rules may
cover API upgrades, command processors, hook systems, container libraries, or
other common Pawn dependencies.
Library migrations are usually review-required. Similar libraries rarely have a one-to-one API, so a rule must report behavior it cannot preserve and leave ambiguous code unchanged. Each supported direction has its own migration ID; for example, a YCMD-to-ACMD migration is separate from ACMD-to-YCMD.
The migration engine plans and applies edits. It does not resolve packages,
invent API facts, or guess program meaning. Those remain the responsibility of
pawn-project, pawn-api, and pawn-analysis.
Contributing
Migration ideas work best as a small before-and-after example. See CONTRIBUTING.md for safety and review expectations.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package catalog contains built-in migrations.
|
Package catalog contains built-in migrations. |
|
cmd
|
|
|
pawnmigrate
command
|
|
|
Package migrate plans and applies versioned Pawn migrations.
|
Package migrate plans and applies versioned Pawn migrations. |
|
Package report renders migration plans.
|
Package report renders migration plans. |
|
Package safety checks workspace mutation prerequisites.
|
Package safety checks workspace mutation prerequisites. |