scratch-git

Git-enhanced diff engine for Scratch SB3 projects. Extracted and refactored from the original scratch-git project.

Overview

This crate provides a Rust library and CLI tool for comparing Scratch 3.0 (SB3) project files and managing version control for Scratch projects. It is designed to be consumed by other applications, such as the BlockCommit Gitea fork.

Features

• Pure Rust diff: No external dependencies for diffing (uses similar crate).
• SB3 Support: Directly reads and compares .sb3 (ZIP) files.
• Script Diffing: Compares Scratch block scripts and reports added/removed blocks.
• Asset Diffing: Detects added, removed, and modified costumes and sounds.
• Commit Message Generation: Generates commit messages in the style of Sprite1: +3 blocks, add costume1.png.
• Git Integration: Init, status, log, checkout, and auto-commit for Scratch projects.
• Library + CLI: Use as a Rust library or via the provided CLI.

Installation

git clone https://github.com/BlockCommit/scratch-git.git
cd scratch-git
cargo build --release --features=cli

The binary will be at target/release/scratch-git.

CLI Commands

Diff & Comparison

# Compare two SB3 files
scratch-git compare --old old.sb3 --new new.sb3 --format json
scratch-git compare --old old.sb3 --new new.sb3 --format text

# Extract project.json from an SB3 file
scratch-git extract path/to/project.sb3

# Diff two raw text strings
scratch-git diff-text "old content" "new content"

Project Management

# Initialize a new project (creates .scratch-project/ directory)
scratch-git init . --name "MyProject"

# Import an SB3 file into the current project
scratch-git import path/to/project.sb3

# Save changes with auto-commit
scratch-git save --message "Updated sprites"
scratch-git save --sb3 path/to/new.sb3 --message "Import v2"

# Show project info
scratch-git info .

Version Control

# Show project status
scratch-git status --format json
scratch-git status --format text

# Show commit log
scratch-git log --limit 10 --format json
scratch-git log --limit 5 --format text

# Checkout a previous version and export as SB3
scratch-git checkout <commit-hash> --output exported.sb3

Library Usage

Add to your Cargo.toml:

[dependencies]
scratch-git = { git = "https://github.com/BlockCommit/scratch-git" }

use scratch_git::{compare_sb3, Diff};

fn main() {
    // Compare two SB3 files
    let commits = compare_sb3("old.sb3", "new.sb3").unwrap();
    for commit in commits {
        println!("{}", commit);
    }

    // Or compare two project.json values directly
    let old_json: serde_json::Value = serde_json::from_str("{...}").unwrap();
    let new_json: serde_json::Value = serde_json::from_str("{...}").unwrap();
    let diff = Diff::new(&old_json);
    let commits = diff.commits(&Diff::new(&new_json)).unwrap();
}

Go Integration

The simplest way for Go to consume this is via CLI:

import "os/exec"

out, err := exec.Command("scratch-git", "compare", "--old", oldPath, "--new", newPath, "--format", "json").Output()
// parse JSON output

Architecture

• src/diff.rs — Core diff logic (assets, scripts, commits).
• src/parse_script.rs — Scratch block JSON to text.
• src/text_diff.rs — Pure Rust text diff via similar.
• src/zip.rs — SB3 (ZIP) reading.
• src/sb3.rs — Asset extraction helpers.
• src/repo.rs — Git command wrapper (init, add, commit, log, status, checkout).
• src/project.rs — Project lifecycle (init, open, import, export, auto-commit).
• src/output.rs — Structured JSON output helpers.

Testing

cargo test --features=cli

License

MIT