Git Workflow

The development of MuseScore uses GitHub to host the code and manage the collaboration of developers. GitHub is based on git, a popular SCM, initially designed and developed by Linus Torvalds for Linux kernel development.

If you're a developer who wants to work on the MuseScore source code and submit your changes to be merged into the main code, here's how. Thanks to Diaspora for their developer guide, which inspired this one.

Git references

Suggested workflow

If you don't have an account on GitHub, create one for free first. Also make sure you set up git on your computer. It's recommended to use SSH to access your own git fork.

This workflow is a command line workflow. If you prefer using a UI, GitHub also provides a UI tool for Mac and Windows, they can automate some of the following operations.

Summary

  1. Fork on GitHub (click Fork button)
  2. Clone to computer, use SSH URL ($ git clone git@github.com:you/MuseScore.git)
  3. Don't forget to cd into your repo: ($ cd MuseScore/)
  4. Set up remote upstream ($ git remote add upstream git://github.com/musescore/MuseScore.git)
  5. Set up the post-checkout hook (from build/git/hooks/, (see the README there)
  6. Create a branch for new issue ($ git checkout -b 404-new-feature)
  7. Develop on issue branch. [Time passes, the main MuseScore repository accumulates new commits]
  8. Commit changes to your local issue branch. ($ git add . ; git commit -m 'commit message')
  9. Fetch upstream ($ git fetch upstream)
  10. Update local master ($ git checkout master; git merge upstream/master)
  11. Rebase issue branch ($ git checkout 404-new-feature; git rebase master)
  12. Repeat steps 6-10 until dev is complete
  13. Push branch to GitHub ($ git push origin 404-new-feature)
  14. Start your browser, go to your Github repo, switch to "404-new-feature" branch and press the [Pull Request] button

After having made a Pull Request don't pull/merge anymore, it'll mess up the commit history. If you (have to) rebase, use 'push --force' ($ git push --force) to send it up to your GitHub repository, this will update the PR too. Be careful not to do this while the core team is working on merging in your PR.

Fork MuseScore repo to your own account

This will create a copy of MuseScore repository to your own account. To fork, press the fork button in the top right corner on MuseScore GitHub page.

Clone your GitHub fork to your computer

Run a clone command against your GitHub fork. It will look something like this, except that it will use your GitHub account name, instead of "you":

$ git clone git@github.com:you/MuseScore.git
$ cd MuseScore

This command downloads your copy of MuseScore to a git repository on your development machine. Change directory into the new MuseScore directory.
Set up the post-checkout hook (from build/git/hooks/, for details see the README there).

$ cp -p build/git/hooks/post-checkout .git/hooks/

To build MuseScore, you will need to install dependencies, and run the build process. Check the instructions for your platform in the developer handbook.

Note that the git clone command is using SSH in this case. You need to have SSH set up on your machine. A git:// URL would not work for your local fork, you will not be able to push on it. Alternatively you can use the HTTPS URL.

If you already cloned MuseScore main repository with

git clone git://github.com/musescore/MuseScore.git

You can change the remote url of the origin to your fork with

git remote set-url origin git@github.com:you/MuseScore.git

Choose something to work on

If you don't have a feature in mind, check out the issue tracker, or come ask in IRC (#musescore on freenode.net).

Create a Topical Development Branch

Before you start working on a new feature or bug fix, create a new branch in your local repository that's dedicated to that change. Name it by issue number (if applicable) and description. For example, if you're working on issue #78359, a slur layout problem, create a new branch called 78359-slurlayout, like this:

$ git checkout -b 78359-slurlayout

Write some code!

We are able to offer much help here :). If you can, provide some tests. See the mtest directory.
When you have got something working, commit the changes to your branch on your local Git repo. Firstly add the files you want to commit, and then commit. Don't forget to put a meaningful message. Use git status and git diff to see which files can be added and committed.

$ git status
$ git status <filename>
$ git add <filenames>
$ git commit -m 'fix #78359: Some kind of descriptive message' 

If your commit message starts with fix #xxxxx, with xxxx the issue number in the issue tracker, the issue will be marked as fixed automatically when your commit is pushed in the main repository

Keep your repo up to date with the main repo

In order to get the latest updates from the main repository, do a one-time setup to establish it as a remote by entering:

$ git remote add upstream git://github.com/musescore/MuseScore.git

The main repo will be now known as upstream. Your fork is known as origin. The origin remote is automatically created after cloning your GitHub fork to your computer.

To verify that you have two remotes, you can type:

$ git remote

Rebase your branch on the latest upstream

To keep your development branch up to date, rebase your changes on top of the current state of the upstream master.

# get the changes from upstream
$ git fetch upstream
# switch to your local master branch
$ git checkout master
$ git rebase upstream/master
# switch to your topical branch
$ git checkout 78359-slurlayout
#make sure all is committed as necessary in branch before rebasing
$ git rebase master

Rebase will put all your commits in the branch on hold, get the last changes, and apply your commits on top of it. You might need to resolve conflicts if you changed a file that has been changed in the main repo. To do so, edit the files, then git add them, and git commit.

Send your changes to MuseScore

When you are ready to send your modified code to MuseScore, push your branch in your origin remote.

$ git push origin 78359-slurlayout

Then do a pull request to MuseScore on GitHub. Go to your GitHub page, select the branch on the left, and press the Pull Request button at the top. Choose your branch, add a comment and submit your pull request. One of the developers with push rights on the main repo will merge your request ASAP. Important: If you haven't signed the MuseScore CLA yet, do this first as it's a requirement for your pull request to be accepted.
After having made a Pull Request don't pull/merge anymore, it'll mess up the commit history. If you (have to) rebase, use 'push --force' ($ git push --force) to send it up to your GitHub repository, this will update the PR too. Be careful not to do this while the core team is working on merging in your PR.

Advice & tips

Don't use git commit -a

$ git commit -a

This will perform git add for all unstaged files and commit. You probably don't want to do that. It's better to use git status and add files invidually before committing.

Delete a branch

To delete a local branch:

#will first check if the branch has been merged
$ git branch -d bugfix
#will delete the branch authoritatively
$ git branch -D bugfix

To delete a remote branch:

$ git push origin :newfeature

Create and apply a patch

It's better to contribute with a pull request than a patch but if you need to make a patch for any reason here is how.
You have created a local branch with the following command, made some changes and commit locally one or more times.

$ git checkout -b 404-new-feature

To create a patch against the master branch, run

git format-patch master --stdout >  404-new-feature.patch

To apply the resulting patch,

#get stats about the patch without applying it
$ git apply --stat 404-new-feature.patch
#check if the patch can be applied without problem
$ git apply --check 404-new-feature.patch
#apply the patch
$ git am --signoff < 404-new-feature.patch