DevOps, CI/CD & Containers
From Subversion to Git: Concepts, Migration and Team Habits
Intermediate11 min readUpdated
Moving a project off Subversion is two jobs at once: converting the history faithfully, and retraining a team whose mental model assumes a single central server. This guide compares the two models honestly, translates the vocabulary command by command, walks through a full git svn conversion with branch, tag and author mapping, and sets out a cutover plan that does not lose work.
What you will learn
- Contrast the centralised and distributed models and explain what each optimises for
- Translate Subversion commands, layout conventions and properties into their Git equivalents
- Convert a repository with git svn, including an authors file and non-standard layouts
- Turn imported SVN branch and tag directories into real Git branches and annotated tags
- Plan a cutover, verify the result and change the habits the team carries over
Subversion still runs a great deal of production code, and the projects that use it are rarely the small ones. A migration therefore lands on teams with a decade of revisions, a directory layout that drifted from the conventions, build scripts that parse revision numbers, and developers who have never worked without a central server to arbitrate. The mechanics of converting the history are the easy half; the harder half is that Git asks people to think differently about what a commit is and when it becomes visible to others.
This guide covers both halves. It starts with the conceptual difference, because most migration friction traces back to it, then translates the vocabulary, then works through a real conversion with git svn including the parts that trip people up — the authors file, non-standard layouts, and turning imported directories into genuine branches and tags. It closes with the cutover and the habits worth changing on day one.
What actually differs between the two models
Subversion has one repository. It lives on a server, it holds the complete history, and it assigns every commit a sequential revision number that increases across the whole repository. Your working copy is a checkout of one path at one revision, and it contains no history at all. Committing means contacting the server; if the server is unreachable, or you lack write access, you cannot commit.
Git gives every developer a complete repository. Cloning copies the whole object database, so history, branches and tags are all local. Committing writes to your own repository and involves nobody else. Sharing is a separate, explicit act — push — and receiving is another one, fetch. Because a commit is identified by the hash of its content and all of its ancestry, there is no global counter to increment and therefore no need for a coordinator.
That single structural change produces most of the practical differences:
- Branching is cheap. In Subversion a branch is a server-side copy of a directory; in Git it is a file containing a commit hash. Teams that branched once per release start branching once per change.
- History is a graph, not a line. Subversion's revision numbers imply a total order. Git commits have parents, merges have two, and "what came first" is only meaningful along a path in the graph.
- Most operations are offline and instant.
log,diff,blame,checkoutandcommitread local data. On a large repository the difference is dramatic. - Partial checkouts are not the norm. Subversion lets you check out one subdirectory. Git clones everything, which is why enormous monorepos with binaries need extra thought (sparse checkout, partial clone, Git LFS).
- History can be rewritten. Amend, rebase and squash have no Subversion equivalent. They are powerful before sharing and disruptive afterwards, which is a new rule for the team to learn.
Neither model is universally better. Subversion's central authority makes access control per directory straightforward and gives you locking for unmergeable files. Git trades those away for speed, offline work and a branching model that made modern code review and continuous integration practical.
Translating the vocabulary
Most of the day-to-day mapping is mechanical once you accept that one SVN command usually becomes two Git commands, because the local and remote steps are separate.
| Subversion | Git | Note |
|---|---|---|
svn checkout URL | git clone URL | Clone brings the entire history, not one revision. |
svn update | git fetch then git merge (or git pull) | Fetch never touches your files. |
svn commit | git commit then git push | The commit is local until pushed. |
svn status | git status | Git also shows what is staged. |
svn diff | git diff / git diff --staged | Two diffs because Git has an index. |
svn add / svn rm | git add / git rm | git add also stages modifications. |
svn revert FILE | git restore FILE | Discards uncommitted edits. |
svn merge -c 4711 | git cherry-pick <hash> | Applies one change elsewhere. |
svn copy ^/trunk ^/branches/x | git switch -c x | No server round trip. |
svn switch ^/branches/x | git switch x | Switching is a local file operation. |
svn log -v | git log --stat | Add --graph to see merges. |
svn blame | git blame | Same idea, runs locally. |
svn:ignore property | .gitignore file | A tracked file, not metadata. |
svn:externals | submodule, subtree or a package dependency | No automatic conversion. |
svn lock | Git LFS file locking, or nothing | Git has no core locking. |
revision number r4711 | commit hash a1b2c3d | Use git describe for readable names. |
Two conventions deserve a note. Subversion's trunk, branches and tags directories are pure convention — the server sees ordinary directories, which is why a copy is a branch. Git has first-class branch and tag refs, so after conversion those directories disappear and become refs. And Subversion tags are mutable directories that people sometimes commit into; Git tags are meant to be permanent pointers, so a "tag" that received commits after creation must be converted to a branch instead.
Choosing a conversion route
Three tools cover almost every case.
git svn ships with Git, needs no extra installation, and does a faithful revision-by-revision import. It is the right default for a single repository up to a few tens of thousands of revisions, and it can also act as a two-way bridge during a transition period.
svn2git is a thin wrapper around git svn that automates the branch and tag conversion described below. Convenient, but understand what it does — you will still need to inspect the result. A separate C++ tool of the same name, developed for large open-source migrations, reads a Subversion dump file directly and is far faster on very large repositories, at the cost of a rule file you must write.
reposurgeon is the heavy option: it loads the history into an editable form so you can rewrite authors, fix messages, drop paths or split repositories. Reach for it when the history is genuinely messy.
Building the authors file
Subversion records a username; Git records a name and an email address on every commit. Without a mapping, every historical commit is attributed to jdoe <jdoe@localhost>, which breaks git shortlog, blame filtering and any tooling that links commits to accounts. Build the mapping before you start.
# Every distinct committer in the repository's history
svn log --quiet https://svn.example.com/shop \
| awk '/^r[0-9]+ \| /{print $3}' \
| sort -u > authors-raw.txt
Turn that list into authors.txt, one line per user:
jdoe = Jane Doe <[email protected]>
amartin = Alex Martin <[email protected]>
build = Build Service <[email protected]>
(no author) = Unknown <[email protected]>
Include the (no author) line: revisions created by the repository administrator or by early imports often have no author, and git svn aborts when it meets a username missing from the file. Ask people to check their own line — an address that does not match their Git identity means their historical commits and their new ones will look like two different people.
Running the conversion
For a repository that follows the standard layout:
git svn clone https://svn.example.com/shop \
--stdlayout \
--authors-file=authors.txt \
--no-metadata \
--prefix=svn/ \
shop-git
--stdlayout is shorthand for --trunk=trunk --branches=branches --tags=tags. --no-metadata omits the git-svn-id: line that would otherwise be appended to every commit message; leave it out if you intend to keep committing back to Subversion through the bridge, because the bridge needs that line. --prefix=svn/ groups the imported refs under refs/remotes/svn/, which makes the clean-up step below unambiguous.
Non-standard layouts are common. Specify the paths explicitly, and repeat the option when branches live in several places:
git svn clone https://svn.example.com/legacy \
--trunk=main/src \
--branches=branches --branches=feature-branches \
--tags=releases \
--authors-file=authors.txt \
--ignore-paths='^(vendor/binaries|docs/generated)/' \
legacy-git
--ignore-paths takes a regular expression and is the easiest way to leave generated artefacts, third-party binaries or an accidentally committed database dump out of the new history. To import only recent history, add -r 40000:HEAD; you get a fast conversion whose first commit is a snapshot, with the old server kept read-only for anything older.
If the import stops — a network failure, a missing author — fix the cause and resume with git svn fetch inside the partially converted repository. It continues from the last converted revision rather than starting again.
Converting imported refs into branches and tags
After the clone, git branch -a shows entries such as remotes/svn/trunk, remotes/svn/release-2.4 and remotes/svn/tags/v2.4.0. These are remote-tracking refs, not real branches, and pushing them to a new server does nothing useful. Convert them:
cd shop-git
# SVN tag directories become annotated Git tags
git for-each-ref --format='%(refname:short) %(objectname)' refs/remotes/svn/tags \
| while read -r ref sha; do
name="${ref#svn/tags/}"
git tag -a "$name" -m "Imported from Subversion tag $name" "$sha"
git branch -r -d "$ref"
done
# The remaining SVN branches become local branches
git for-each-ref --format='%(refname:short) %(objectname)' refs/remotes/svn \
| while read -r ref sha; do
name="${ref#svn/}"
[ "$name" = trunk ] && continue
git branch "$name" "$sha"
git branch -r -d "$ref"
done
git branch -m master main # if trunk was checked out as master
Before pushing, do the housekeeping the old repository never allowed. Convert Subversion's ignore properties into a real file, and add the entries that were previously handled by the server:
git svn show-ignore >> .gitignore
git add .gitignore && git commit -m "Add .gitignore from svn:ignore properties"
Then look for the fat. git count-objects -vH reports the repository size, and this pipeline lists the largest blobs ever committed:
git rev-list --objects --all \
| git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' \
| awk '$1=="blob" {print $3, $4}' | sort -nr | head -20
If the top of that list is release archives or vendor jars, remove them with git filter-repo --path <dir> --invert-paths before the first push. Rewriting history afterwards means every clone is invalid.
Verifying and cutting over
Never trust a conversion you have not checked. Three inexpensive verifications catch nearly everything:
Compare the tips
Export the head of trunk from Subversion and the head ofmainfrom Git into two directories and rundiff -r, ignoring.svnand.git. The only differences should be files you deliberately excluded.Compare the counts
svn log --quiet | grep -c '^r'againstgit rev-list --count --all. They will not match exactly — merges and excluded paths change the shape — but an order-of-magnitude gap means the layout options were wrong.Build every tag
Check out two or three release tags and run the build. A release you cannot rebuild from the new repository is a migration that failed quietly.
For the cutover itself, freeze writes rather than trying to run both systems in parallel indefinitely. Announce a date, make the Subversion repository read-only with a pre-commit hook, run a final git svn fetch to pick up the last revisions, redo the branch and tag conversion, then push:
git remote add origin [email protected]:acme/shop.git
git push --all origin
git push --tags origin
A short bridge period is reasonable if a few people cannot switch immediately. With the metadata kept (--no-metadata omitted), git svn rebase pulls new SVN revisions into the Git clone and git svn dcommit replays local Git commits back as SVN revisions. Treat it as a two-week concession, not an architecture: the bridge only works from a repository whose history has not been rewritten, and dual-writing invites divergence.
Update everything downstream in the same window. Build jobs that referenced ${SVN_REVISION} need a new version scheme — git describe --tags or the short hash. Issue-tracker links to r4711 break. Release scripts that did svn copy to make a tag now do git tag -a and git push origin <tag>. The delivery pipeline guide covers versioning strategies that work with hashes rather than counters.
What the team has to unlearn
Three habits cause almost all the early confusion, and naming them in advance saves a fortnight of support questions.
"Commit" no longer means "share". Developers used to Subversion either hoard changes for days because committing was public, or commit and wonder why nobody sees their work. Say it explicitly: commit early and often locally, push when the work is coherent.
"Update" no longer rewrites your files behind your back. git fetch is safe and can be run constantly; the merge or rebase is the step that touches the working tree.
Branches are for changes, not for releases. The instinct carried over from Subversion is that a branch is a heavyweight event requiring approval. Pick one model and write it down — the branching workflows guide compares the realistic options, and trunk-based development is usually the smallest change from a Subversion team's habits.
Support the transition practically: a one-page command translation on the wall and a nominated person who answers Git questions for the first month. Make sure everyone reads the Git fundamentals material on undoing changes, because "how do I get my file back" is the question that will otherwise arrive daily.
Pitfalls worth anticipating
- Missing authors abort the import hours in. Generate the list first and include
(no author). - Tags that were committed into. They convert to tags pointing at the last state, silently losing the intermediate revisions. Check with
svn log ^/tagsfor tag paths with more than one revision and convert those to branches. - Empty directories vanish. Git tracks files, not directories. If the build needs an empty directory, add a
.gitkeepfile. - Line endings and file properties.
svn:eol-stylebecomes a.gitattributesentry (* text=auto), andsvn:executablemaps to the file mode. Set.gitattributesin the first commit after conversion rather than discovering the problem on a Windows machine later. - Nobody owns the old server. Decide who keeps the read-only Subversion instance running, for how long, and where its backups live. "We will decommission it next quarter" tends to mean it disappears with no announcement.
Key takeaways
- Subversion centralises history on a server and numbers revisions globally; Git gives every developer the full history, which is why branching, logging and committing are local and instant.
- Most commands map one to two: an SVN commit becomes a Git commit plus a push, and an SVN update becomes a fetch plus a merge.
- Build the authors file before converting, include
(no author), and mirror the repository locally if the server is slow. git svn clone --stdlayouthandles ordinary repositories; explicit--trunk,--branches,--tagsand--ignore-pathshandle the rest, and the import can be resumed withgit svn fetch.- Imported refs are not real branches: convert tag directories to annotated tags, branch directories to branches, add a
.gitignoreand.gitattributes, and strip large binaries before the first push. - Verify by diffing the tips, comparing commit counts and rebuilding released tags; then freeze Subversion, push once, and keep the bridge period short.
- Budget as much attention for the habit change — commit is not share, fetch is safe, branches are cheap — as for the conversion itself.
Sources and further reading
Frequently asked questions
- Can we keep the whole Subversion history, or should we start fresh?
- Both are defensible. A full conversion preserves blame, bisect and archaeology, which matters for long-lived business code, but it takes longer and drags in every large binary ever committed. Starting from an empty repository with a single import commit is fast and clean, and works when the old server stays online read-only for archaeology. Decide by asking how often anyone actually reads history older than two years.
- How long does a git svn conversion take?
- It walks the Subversion history one revision at a time over the network, so expect roughly one to several revisions per second. A repository with 50,000 revisions can easily run overnight. Run it on a machine close to the SVN server, use a local mirror created with svnsync if you can, and never assume it will finish during a maintenance window you scheduled for an afternoon.
- What happens to svn:externals?
- Nothing automatic — git svn ignores them. Externals pointing at another project usually become a package dependency resolved by Maven, npm or your language's package manager, which is almost always the better answer. If you genuinely need a nested checkout, a Git submodule or a subtree merge reproduces the behaviour, but review each external individually rather than converting them mechanically.
- Do we still need file locking after moving to Git?
- Git has no equivalent of svn lock, because its merge model assumes text that can be combined. Teams that locked binary assets — design files, spreadsheets, generated documents — should move those files to Git LFS, which supports a file locking workflow, or keep them in a system built for binary assets. Locking source code was usually a habit worth losing rather than a requirement to reproduce.