svn-to-git-migration

name

svn-to-git-migration

description

Migrate a Subversion (SVN) repository to a standalone Git repository by running the migration directly using inline PowerShell (on Windows) or bash (on macOS/Linux). The agent executes all commands itself — detection, each migration phase, and verification — using the powershell tool with inline code (never pointing to a .ps1 file, which is blocked by Group Policy). Use this skill whenever the user mentions SVN migration, converting SVN to Git, "we're moving away from SVN", "git svn is missing", "git-svn not found on Windows", or wants to import SVN history into a Git repo. Also use when someone asks how to preserve SVN history in Git, convert branches/tags from SVN, or set up a Git mirror of an SVN repo.

SVN → Git Migration

Agent instructions — read this before every action:

You ORCHESTRATE the migration. Every phase runs as a background subagent via the task tool — you never run powershell phase snippets yourself. Your context is for orchestration only.

Windows execution model (critical — applies inside every subagent):

• powershell -File script.ps1 → ALWAYS BLOCKED by Group Policy. Never use this.
• powershell -Command "..." → Never blocked. Always use this.
• Inline technique: read lib/core.pslib as text, wrap in [scriptblock]::Create(), dot-source it — no -File, no ExecutionPolicy issue.

For every Windows phase: Tell a task subagent the runbook path (e.g. phases/phase-0.md) and the placeholder values. The subagent reads the file, fills in values, and executes the snippet. The orchestrator never opens a runbook file.

macOS / Linux: Use bash scripts/migrate.sh run <url> ... — no policy constraint. Run it via the bash tool (or delegate to a subagent).

State between phases: Each phase saves its output to $target\.svn2git\*.json. The next phase reads it. This is how cross-phase state (sha-index, refs, config) survives across separate powershell -Command invocations.

git-svn is no longer bundled with Git for Windows (and macOS Homebrew dropped it too). This skill recreates the full git svn clone behaviour using only the svn CLI and standard git plumbing commands (hash-object, write-tree, commit-tree, update-ref, update-index). No Perl, no native extensions required.

Platform support:

• Windows — agent runs each phase inline via powershell -Command; state persisted as JSON between phases
• macOS / Linux — agent runs migrate.sh run directly via bash

⚠️ macOS users: The system bash is version 3.2 and will not work. Install bash ≥ 4 first: brew install bash. The script checks at startup and aborts with instructions if the version is too old.

---

Prerequisites

Verify these before starting:

svn --version          # any modern version (TortoiseSVN, SlikSVN, Homebrew, distro pkg)
git --version          # 2.x or later
python3 --version      # 3.x — used for XML parsing in the bash script

macOS only:

bash --version         # must be 4.0 or later
# If not: brew install bash

Files (relative to the skill directory):

• macOS / Linux: scripts/migrate.sh
• Windows: lib/core.pslib — function library loaded inline by the phase runbooks (never run directly)

---

Step 1 — Detect

Agent: Delegate detect to a task subagent — pass the skill directory path and the current working directory. The subagent reads phases/detect.md, runs the detection commands, and returns the structured result: SVN URL, layout, authors, head revision.

Once the subagent returns, immediately present the interview questions from Step 2 to the user in a single message — do not wait for a follow-up prompt. Include in that message:

• A summary of what detect found (URL, layout, author count, head revision)
• All interview questions that are not already answered by the detect output
• A pre-filled suggestion for each question where detect gave enough information

Only ask the user for the URL if the subagent reports it could not be auto-detected.

---

Step 2 — Interview: migration options

Work through these decisions in order based on what the svn info / svn log output showed.

a. Repository layout

What layout does your SVN repository use?

Layout	Description	Flag to use
Standard	Has trunk/, branches/, tags/ at the top level	--stdlayout
Custom paths	Different names (e.g. main/, rb/, rel/)	-T <trunk> -b <branches> -t <tags>
Single path	No branches or tags — just one linear history	(no flag)

The detect output will suggest the likely layout. You can always override it.

b. Author mapping

Do you want real names and email addresses in git commits?

SVN commits store only a username (e.g. jsmith). Without a mapping, each commit author defaults to jsmith@<repo-uuid> — fine for private repositories, but not ideal for public ones.

To provide a mapping, create an authors.txt file (see assets/authors.template.txt):

jsmith = Jane Smith <[e-mail]>
bwilliams = Bob Williams <[e-mail]>
(no author) = Unknown Committer <[e-mail]>

The detect output lists every SVN author that appears in the log — use that list to build your file. Ask me to generate a stub authors.txt from that list if you'd like.

⚠️ If the detect output shows AUTHOR_SCAN_COMPLETE: false, the full log scan timed out. Some older committers may be missing from the list. You can get the complete set by running locally:

svn log --xml -q <svn-url> | Select-String '<author>' | ForEach-Object { ($_ -replace '.*<author>(.*)</author>.*','$1').Trim() } | Sort-Object -Unique

Any SVN username not in authors.txt will default to username@<repo-uuid> and will be listed as "Unmapped SVN authors" in the Phase 8 summary.

Pass the file with: --authors-file authors.txt

c. Metadata trailer

Keep git-svn-id in each commit message?

Each commit will end with a line like:

git-svn-id: https://svn.example.com/repos/myproject/trunk@42 a1b2c3d4-e5f6-...

• Default (recommended): keep it — preserves SVN revision traceability. You can always strip it later with git filter-repo.
• To omit: add --no-metadata

d. Path filtering

Are there directories you want to exclude — generated code, large binaries, IDE files?

Use --ignore-paths <regex> with a regex matched against ref-root-relative paths.

Example — exclude a generated directory and all .class files:

--ignore-paths "(^generated/|\.class$)"

⚠️ Migrating from git-svn? git-svn matched --ignore-paths against repo-root-relative paths (e.g. /trunk/generated/). This skill matches against ref-root-relative paths (e.g. generated/). Adjust your patterns accordingly. See references/git-svn-mapping.md for the full mapping.

Use --include-paths <regex> to do the inverse (whitelist).

e. Tag handling

Clean tags (directories that were never modified after the SVN copy) automatically become annotated git tags. Dirty tags (modified after creation) automatically become branches named tags/<tagname>, with a warning printed in the summary.

Override with --tags-as-branches to turn all SVN tags into branches regardless of cleanliness.

f. Default branch name

What should the trunk become in git?

Choice	Flag
main (default)	(omit flag)
master	--default-branch master
trunk	--default-branch trunk

g. svn:ignore → .gitignore conversion

The skill reads svn:ignore properties from the SVN repository and writes .gitignore files into the git repository, then creates a final commit on each ref. Recommended: keep the default (enabled).

Variable to set in Phase 0: $noCreateIgnore

User wants	Set $noCreateIgnore to
Create .gitignore files (default)	$false
Skip .gitignore creation	$true

⚠️ The variable is negated — $false = enabled, $true = disabled. Do not confuse with a $createIgnore flag.

h. Target directory

Where should the git repository be created?

Default: ./repo-name (derived from the SVN URL). Override with --target <path>.

i. Revision range

Migrate all revisions (default), or a specific range?

• All revisions: (omit flag) — equivalent to --revision 1:HEAD
• Specific range: --revision N:M
• Single revision: --revision N

For very large repositories (> 5 000 revisions), consider migrating in chunks and re-running with a later range. See references/troubleshooting.md for guidance.

---

Step 3 — Run the phases

Agent: For each phase, launch a task subagent with the runbook path and placeholder values — do not open the runbook file yourself. The subagent reads it, fills in placeholders, and runs the snippet.

Windows runs the migration as individual phases — this works regardless of ExecutionPolicy, gives visibility into progress, and allows resuming if interrupted. macOS/Linux uses a single run command (no ExecutionPolicy constraint there).

---

macOS / Linux

One command does everything:

bash scripts/migrate.sh run https://svn.example.com/repos/myproject \
  --stdlayout \
  --authors-file authors.txt \
  --default-branch main \
  --target ./myproject-git

Tell me your answers to the interview questions and I'll produce the exact command.

---

Windows — Phase-by-phase (always use this)

For each phase, launch a task subagent with the runbook path and the three placeholder values. Phases 1–8 all use the same runbook (phases/run-phase.md) — only $phase changes.

Phase	Runbook file	Name	What it does
—	phases/detect.md	Detect	Gather SVN repo info before the interview
0	phases/phase-0.md	Preflight + config	SVN reachability, writes config.json, copies lib/core.pslib to state dir
1 ⟳	phases/run-phase.md — $phase='1'	Git init	Creates the git repository — parallel with 2 & 3
2 ⟳	phases/run-phase.md — $phase='2'	Author map	Validates the authors file — parallel with 1 & 3
3 ⟳	phases/run-phase.md — $phase='3'	Resolve refs	Enumerates SVN branches/tags, writes refs.json — parallel with 1 & 2
4	phases/run-phase.md — $phase='4'	Convert trunk	Replays trunk revisions as git commits (long-running)
5	phases/run-phase.md — $phase='5'	Convert branches	Replays branch revisions (may be long)
6	phases/run-phase.md — $phase='6'	Convert tags	Creates annotated git tags or dirty-tag branches
7	phases/run-phase.md — $phase='7'	Post-processing	svn:ignore → .gitignore, set HEAD, run git gc
8	phases/run-phase.md — $phase='8'	Summary	Prints the migration report

⟳ = phases 1, 2, 3 can run in parallel — launch all three simultaneously, wait for all three before Phase 4.

If a phase fails, fix the problem and re-run that phase — earlier phases don't need to be repeated. The SHA index and state are preserved in $target\.svn2git\.

---

Step 4 — Execute

Agent — orchestration model (critical):

Every phase runs as a background subagent via the task tool (agent_type: "task", mode: "background"). You are the orchestrator — you read runbooks, fill in placeholders, launch subagents, read results, and report progress to the user. You never run powershell tool calls yourself for phase execution.

Why: Keeps your context small. Phase output (potentially hundreds of lines of SVN progress) goes into subagent context, not yours. You only see the summary returned by the subagent.

How to launch a phase as a subagent:

1. Phase 0: task(prompt="Read phases/phase-0.md in skill dir <skillDir>. Fill in all interview values. Run the PowerShell snippet.")
2. Phases 1–8: task(prompt="Read phases/run-phase.md in skill dir <skillDir>. Set $skillDir='<skillDir>', $stateDir='<stateDir>', $phase='<N>'. Run the PowerShell snippet.")

Only 3 substitutions for phases 1–8: $skillDir (constant), $stateDir (from Phase 0), $phase (the number). No assembling 30-line templates.

Model selection for phase subagents: Phases 1–8 are mechanical — the subagent reads a runbook and runs a fixed PowerShell snippet. Heavy reasoning is not needed. Always use the lightest model available in the user's setup:

• Claude Haiku if available (claude-haiku-4.5)
• GPT-4.1 mini / GPT-4o mini as an alternative
• Fall back to the user's default only if no lightweight model is configured

Pass model: "claude-haiku-4.5" (or equivalent) on every task() call for phases 1–8. Phase 0 and the Detect step may use the default model as they require light reasoning to fill placeholders.

The subagent reads the runbook, fills placeholders, and executes — the orchestrator never reads runbook content itself.

Runbook access: The subagent reads its own runbook — the orchestrator only passes the skill directory path and the placeholder values gathered from the interview. The orchestrator never reads runbook content.

Always pass absolute paths: Subagents run in an unknown working directory. Always resolve $target and $authorsFile to absolute paths before passing them — use the CWD reported by the detect subagent as the base for any relative path the user provided.

Execution order:

Step	What	How
Detect	Auto-detect SVN repo	Subagent reads phases/detect.md — returns URL, layout, authors, head revision
Phase 0	Preflight + config	Subagent reads phases/phase-0.md — 15+ placeholder values from interview. Capture CANONICAL_STATEDIT= and CANONICAL_TARGET= from its output — these are $stateDir and $target for all subsequent phases.
Phases 1 + 2 + 3	Git init, Author map, Resolve refs	3 subagents in parallel — each reads phases/run-phase.md with $phase='1', '2', '3'. Only 3 substitutions: $skillDir, $stateDir, $phase. Use lightest available model.
Phase 4	Convert trunk	Subagent reads phases/run-phase.md with $phase='4'. Before launching, tell the user: "Phase 4 is starting — this replays every trunk revision and can take minutes to hours." Use lightest available model. (long-running)
Phase 5	Convert branches	Subagent reads phases/run-phase.md with $phase='5'. Warn if repo has many branches. Use lightest available model.
Phase 6	Convert tags	Subagent reads phases/run-phase.md with $phase='6'. Use lightest available model.
Phase 7	Post-processing	Subagent reads phases/run-phase.md with $phase='7'. Use lightest available model.
Phase 8	Summary	Subagent reads phases/run-phase.md with $phase='8'. Use lightest available model.

• After each subagent completes, report a one-line status to the user: ✅ Phase N complete — <key result>
• If a subagent fails, read the ## On error table in the runbook, fix the problem, and re-launch that phase's subagent only — earlier phases don't need to repeat (state is preserved in $target\.svn2git\)
• A state guard at the start of phases 4–6 will tell you exactly which prior phase to re-run if state files are missing

The most common issues are covered in references/troubleshooting.md.

---

Step 5 — Verify

After the migration completes, check the result:

# Check recent commit messages and SVN revision traceability
git log --oneline | head -20

# Check all branches were created
git branch -a

# Check tags
git tag

# Inspect the latest commit in full
git show HEAD

If anything looks wrong (missing branches, garbled commit messages, missing history), share the output here.

---

Step 6 — Next steps

Push to a remote:

git remote add origin <remote-url>
git push --all origin
git push --tags origin

Optional — strip git-svn-id trailers (irreversible; requires git filter-repo):

git filter-repo --message-callback 'return re.sub(rb"\ngit-svn-id:.*", b"", message)'

---

Reference files

• references/algorithm.md — technical algorithm spec (for debugging/understanding the scripts)
• references/git-svn-mapping.md — mapping from original git-svn CLI switches to this skill's options
• references/troubleshooting.md — auth issues, encoding, large repos, edge cases