git2svn: Git-to-SVN Synchronization CLI

A lightweight, zero-dependency Python 3 CLI utility to bridge local Git development workspaces with a Subversion (SVN) repository. It provides two symmetrical, intuitive commands to either stage changes for manual review (stage) or sequentially commit them into SVN history (replay).

What git2svn Is (and What It Is Not)

✅ What git2svn is designed for:

• Complementing an existing svn2git mirror: You have an automated or incremental SVN-to-Git mirror (e.g. via all-fast-export, subgit, or an internal sync job) pulling SVN revisions into a tracking branch (such as origin/svn-mirror/trunk or mirror/trunk). git2svn serves as the reverse gateway, letting you replay your local feature branches cleanly back into SVN.
• Local Git freedom with an SVN backend: Work locally with Git branches, stashes, and interactive rebases, then ship clean changesets to SVN with zero manual copy-pasting.
• Safe, staged inspection (stage): Reviewing complex diffs or running pre-commit checks in TortoiseSVN before changes touch the SVN server.
• Sequential commit porting (replay): Porting multi-commit PRs into SVN with original commit messages and conflict pause-and-resume control.

❌ What git2svn is NOT designed for:

• It is NOT an autonomous full-mirror / bidirectional replication tool: git2svn does not automatically track arbitrary Git tags, merge trees, or multi-branch mappings across repositories. Git history should be strictly linear before replaying to SVN.
• It is NOT intended for Git-as-master workflows: If Git is your authoritative source of truth and you merely want to mirror everything into a passive SVN replica without human interaction, use a dedicated continuous migration daemon like SubGit.

Key Highlights

• Zero External Dependencies: Built purely on Python 3 standard library and standard git/svn CLI tools.
• Smart CRLF/LF Normalization: Automatically reconciles line endings post-patch, preventing Subversion E135000: Inconsistent line ending style commit failures.
• Clean Intent Model:
  • stage: Never commits. Staged in SVN (svn add, svn rm) for inspection in TortoiseSVN or CLI before manual commit.
  • replay: Always commits. Sequentially ports Git commits into SVN with original author messages and a stateful conflict recovery lifecycle.
• Flexible Reference Syntax: Accepts single commits (abc1234), range notation (main..feature), or two positional arguments (main feature).
• Binary & Snapshot Support: Direct object DB extraction (--copy) for binary assets and whole-tree alignment (--snapshot).

Quick Start

Installation

Install via pipx (recommended) or pip:

# Using pipx (isolated global CLI command):
pipx install git2svn

# Or via standard pip:
pip install git2svn

Alternatively, run directly from source without installing:

git clone https://github.com/simon123h/git2svn.git
cd git2svn
python3 -m git2svn --help

Workflow & Basic Commands

git2svn is designed so you bootstrap once with setup, after which all synchronization commands run cleanly without needing --svn-dir or --svn-url:

# 1. Bootstrap once in your Git repository (URL or local path)
#    This automatically checks out a managed SVN copy into .git/git2svn/svn_wc,
#    detects mirror tracking branches, installs a pre-push guard against accidental pushes,
#    and configures convenient git aliases.
git2svn setup https://svn.example.com/repo/trunk
# (or with an existing local checkout: git2svn setup /path/to/svn)

# 2. Check synchronization health and pending commits
git2svn status

# 3. Stage a single commit or squash an entire branch (uncommitted for review)
git2svn stage a1b2c3d4
git2svn stage main..feature/login --diff

# 4. Preview uncommitted staged changes in SVN
git2svn diff
git2svn diff --stat

# 5. Replay an entire feature branch commit-by-commit into SVN history
git2svn replay main..feature/login

# 6. Resume replay after resolving conflicts
git2svn replay --continue

# 7. Discard staged changes, remove conflict artifacts, or purge managed workspace
git2svn clean
git2svn clean --purge

# 8. Run pre-flight environment & configuration diagnostics (or auto-remediation)
git2svn doctor          # or: git2svn doctor --fix

# 9. Enable shell tab-completion (bash, zsh, fish)
eval "$(git2svn completion bash)"   # or: git2svn completion --install

# 10. Or use the built-in Git aliases created during setup:
git svn-push     # Replay trunk commits to SVN and fetch mirror
git svn-pull     # Pull fresh SVN mirror commits & rebase local trunk
git svn-status   # Run git2svn status

(Note: Advanced users or CI/CD scripts can still pass --svn-dir <path> or --svn-url <url> to override the configured workspace on any command).

Architecture at a Glance

flowchart LR
    subgraph Local["Developer Workstation"]
        direction LR
        Git[("Git Workspace<br/>(feature branch)")]

        Tool["git2svn Engine<br/>• Diff & Patch<br/>• EOL Normalizer<br/>• Conflict Recovery"]

        SVN[("SVN Working Copy<br/>(trunk / branch)")]
    end

    Remote[("Remote SVN Server<br/>(Central Repository)")]

    Git -->|"Reads commits & diffs"| Tool

    Tool -->|"stage: patch & stage (uncommitted)"| SVN
    Tool -->|"replay: patch & commit each revision"| SVN

    SVN -->|"Manual commit (after stage review)"| Remote
    SVN -->|"Atomic svn commit (during replay)"| Remote

Documentation

Comprehensive documentation-as-code is maintained in the docs/ folder:

• User Guide: Complete CLI options, command reference, the Git Integration Branch Workflow, and troubleshooting FAQ.
• Architecture Documentation: Architectural design, package building blocks, runtime sequence diagrams, cross-cutting concepts, and Architecture Decision Records (ADRs).
• Requirements Specification: Detailed stakeholders, functional requirements, and quality goals.
• Contributing Guidelines: Development setup, coding conventions, Conventional Commits, and test instructions.

Contributing & Development

Contributions, bug reports, and pull requests are welcome! Please see CONTRIBUTING.md for local environment setup, pre-commit hook configuration, Conventional Commits guidelines, and test instructions.

License

Distributed under the Apache-2.0 License.