musescore-git-plugins

Git helpers for MuseScore 4 scores, built as MuseScore plugins. All workflows are designed around a single invariant:

• Scores in the repo are stored as .mscz only.

The plugins live in the MuseScore Plugins folder next to the Scores folder, and assume your git working tree is the Scores directory:

• .../MuseScore4/Plugins
• .../MuseScore4/Scores ← git repo with .git here

How to use

• Daily flow (no remote changes):

  1. Open Scores/<Name>.mscz in MuseScore.
  2. Edit and save in MuseScore.
  3. Run Commit to GitHub to stage, commit, and push <Name>.mscz.

• When remote has changes for the same score:

  1. Open Scores/<Name>.mscz.
  2. Run Pull from GitHub:
     • If pull succeeds: you are up to date, continue editing, then Commit to GitHub.
     • If pull cannot merge: it extracts the remote version to Scores/<Name> - Copy/<Name> - Copy.mscx and tells you to run MuseScore Diff.
  3. Run MuseScore Diff:
     • It compares your local score to the - Copy version and opens a diff score.
     • Edit the diff score until you are happy.
     • Click Save to Main in the review dialog to write the result back into Scores/<Name>.mscz.
  4. Run Commit to GitHub:
     • It sees Scores/<Name>_diff.log.txt, force-pushes <Name>.mscz, and clears the marker.

Commit to GitHub

Menu: Plugins → Commit to GitHub

Behavior:

• Only runs when a score is open and saved as Scores/<Name>.mscz.
• Refuses to run on .mscx scores and tells you to use “Save As…” .mscz instead.
• First-time setup:
  • Asks for a GitHub repo URL.
  • Clones the repo into a temp folder and moves only the .git directory into Scores.
• On each run:
  • Generates a per-run temporary musescore-git-push-<timestamp>.bat in Plugins/.
  • That script:
    • cd’s into Scores.
    • git fetch origin.
    • If Scores/<Name>_diff.log.txt exists:
      • Stages only <Name>.mscz.
      • Commits with message Commit from MuseScore plugin: <Name>.
      • Runs git push --force.
      • Deletes Scores/<Name>_diff.log.txt (marker has been consumed).
    • Otherwise:
      • Checks whether the remote is ahead for <Name>.mscz.
      • If up to date, stages <Name>.mscz, commits, and does a normal git push.
      • If remote is ahead and there is no diff marker, calls into a small PowerShell helper that:
        • Uses git worktree to check out the remote tree.
        • Extracts the remote .mscz’s embedded .mscx into Scores/<Name> - Copy/<Name> - Copy.mscx.
        • Shows a Windows message instructing you to run “MuseScore Diff” before committing.
  • The .bat is designed to be temporary and self-deletes after it runs.

Pull from GitHub

Menu: Plugins → Pull from GitHub

Behavior:

• Only runs when a score is open and saved as Scores/<Name>.mscz.
• Validates that Scores/.git exists (otherwise asks you to run Commit first-time setup).
• Generates a per-run temporary musescore-git-pull-<timestamp>.bat in Plugins/ that:
  • cd’s into Scores.
  • Runs git fetch origin.
  • Tries git pull --no-edit.
    • On success: shows a “Pull completed successfully” message.
    • On failure (e.g. unmergeable changes):
      • Aborts any merge (git merge --abort) to keep the tree clean.
      • Uses git worktree and PowerShell to:
        • Check out the remote tree at @{upstream}.
        • Extract remote <Name>.mscz’s embedded .mscx into Scores/<Name> - Copy/<Name> - Copy.mscx.
      • Shows a Windows message telling you to run “MuseScore Diff” to resolve differences.
  • The pull .bat also self-deletes after it runs.

MuseScore Diff

Menu: Plugins → MuseScore Diff

Purpose:

• Given a current score and a remote copy at Scores/<Name> - Copy/<Name> - Copy.mscx, produces a visual diff, lets you edit, and then writes the result back into Scores/<Name>.mscz.

Key paths for a score Name:

• Local working copy in repo: Scores/Name.mscz.
• Extracted original for diff: Scores/Name.mscx (unzipped from the .mscz when needed).
• Remote copy for diff: Scores/Name - Copy/Name - Copy.mscx.
• Diff output: Scores/Name_diff.mscx.
• Diff log / marker: Scores/Name_diff.log.txt.

On run:

• Resolves Plugins and Scores paths.
• Ensures either Scores/Name.mscx or Scores/Name.mscz exists.
  • If only .mscz exists, unzips the embedded .mscx into Scores/Name.mscx.
• Verifies that Scores/Name - Copy/Name - Copy.mscx exists (created by Commit/Pull when the remote is ahead).
• Generates a PowerShell script that:
  • Loads original and copy as XML.
  • Computes a measure-level diff and writes Scores/Name_diff.mscx.
  • Opens the diff score in MuseScore.
  • Logs details and errors into Scores/Name_diff.log.txt.

Review and Save to Main:

• A second PowerShell script shows a Windows Forms dialog with a “Save to Main” button.
• When you click “Save to Main”:
  • It sends Ctrl+S to MuseScore so your edits in the diff score are saved.
  • Loads Scores/Name_diff.mscx, strips color markers and diff-only staff text.
  • Saves a cleaned temporary .mscx.
  • If Scores/Name.mscz exists:
    • Loads System.IO.Compression / System.IO.Compression.FileSystem.
    • Opens the .mscz zip in update mode and replaces the embedded .mscx entry with the cleaned diff.
    • Logs the update and last-write timestamps to Scores/Name_diff.log.txt.
  • Otherwise (no .mscz), overwrites Scores/Name.mscx as a fallback.
  • Cleans up temporary artifacts:
    • Scores/Name_diff.mscx.
    • The cleaned .mscx temp file.
    • Scores/Name.mscx (the extracted original).
    • Scores/Name - Copy/Name - Copy.mscx and the Scores/Name - Copy folder.
    • score_style.mss and viewsettings.json under both original and copy directories, if present.
  • Leaves Scores/Name_diff.log.txt in place as the “diff completed” marker.

Diff marker and force-push

• Scores/Name_diff.log.txt plays two roles:
  • Human-readable debug log for diff and review steps.
  • Machine-readable marker telling Commit to GitHub that you have already diffed and reconciled the score.
• When this file exists and you run Commit to GitHub for Name:
  • The commit script skips remote-ahead extraction and goes directly to the force-push path for <Name>.mscz.
  • After the force push, the script deletes Scores/Name_diff.log.txt so the marker is consumed.

Temporary files

The following files are generated on demand and are safe to delete at any time (they are all intended to be temporary and generally self-delete):

• In Plugins/:
  • musescore-git-push-<timestamp>.bat
  • musescore-git-setup-<timestamp>.ps1 / .bat
  • musescore-git-pull-<timestamp>.bat
  • musescore-diff.ps1
  • musescore-diff-review.ps1
  • musescore-diff.bat
  • musescore-diff-launch.vbs