Open-source MuseScore plugins

Usage guide

Practical steps for this open-source MuseScore 4 plugin suite: Git-backed scores, where files live, happy-path editing, and how to recover when your score and GitHub diverge—including the measure-level LCS diff workflow over score XML. Source and issues on GitHub.

← Back to project overview

What this workflow assumes

• Scores in the repo are stored as .mscz only (not raw .mscx in Git).
• Plugins sit in the MuseScore Plugins folder next to the Scores folder.
• Your Git working tree is the Scores directory (that folder contains .git).

.../MuseScore4/Plugins   ← plugin .qml files live here
.../MuseScore4/Scores    ← git repo; commit .mscz here

Plugins you use

• Commit to GitHub — stage, commit, push the open score; first run can set up the repo.
• Pull from GitHub — fetch and merge; on failure, prepares a “copy” score for diffing.
• MuseScore Diff — builds a visual diff score (measure-level alignment via LCS) and lets you reconcile in MuseScore.

Daily flow (you’re the only one changing the score)

1. Open Scores/<Name>.mscz in MuseScore.
2. Edit and save in MuseScore.
3. Run Plugins → Commit to GitHub. It stages <Name>.mscz, commits, and pushes when the remote is not ahead.

When the remote might have new commits

Before committing, use pull so you don’t trample remote work.

1. Open Scores/<Name>.mscz.
2. Run Plugins → Pull from GitHub.
   • If pull succeeds: you’re up to date — keep editing, then Commit to GitHub.
   • If pull can’t merge: the plugin aborts the merge, extracts the remote’s .mscz into a - Copy tree, and tells you to run MuseScore Diff.

MuseScore Diff (reconcile local vs remote)

For a score named Name, the important paths are:

• Your file in the repo: Scores/Name.mscz
• Extracted local XML (when needed): Scores/Name.mscx
• Remote copy for comparison: Scores/Name - Copy/Name - Copy.mscx
• Generated diff score: Scores/Name_diff.mscx
• Marker / log after a completed review: Scores/Name_diff.log.txt

On run, the diff flow ensures local XML exists (unzips from .mscz if needed), checks the - Copy file exists, then generates the diff score and opens it. After you edit in the diff score, use the review UI’s Save to Main to write the reconciled result back into Name.mscz and leave Name_diff.log.txt as the marker that you’re done diffing.

Commit after a diff

When Name_diff.log.txt exists, Commit to GitHub takes the “I've finished the merge review” path: it can force-push Name.mscz and then removes the marker file so it isn’t reused by mistake.

If there is no diff marker and the remote is ahead, the commit plugin may extract the remote score and prompt you to run MuseScore Diff first instead of pushing blindly.

First-time setup (Commit to GitHub)

On first use you may be asked for a GitHub repo URL. The plugin clones to a temp directory and moves only the .git directory into Scores so your working tree stays in the scores folder.

Temporary files you can ignore or delete

Generated helpers under Plugins/ (timestamped .bat, PowerShell, etc.) are meant to be ephemeral. The README in the repo lists names like musescore-git-push-*.bat, musescore-diff.ps1, and similar — safe to remove if you’re tidying up.

Troubleshooting quick list

• Commit refuses: Ensure the open file is Scores/<Name>.mscz, not a standalone .mscx — save as .mscz in the Scores repo path.
• Pull says run Diff: Open the - Copy path exists, then run MuseScore Diff and complete Save to Main before committing again.
• .git missing: Run through Commit’s first-time setup or initialize Scores as a repo first.

Full README on GitHub →