3.2 Git cheat sheet

The intent of this section is to get you working on LilyPond quickly. If you want to learn about Git, go read Further Git documentation resources.

Also, these instructions are designed to eliminate the most common problems we have found in using Git. If you already know Git and have a different way of working, great! Feel free to ignore these advice.


Pulling recent changes

As LilyPond’s source code is continously improved, it is wise to integrate recent changes into your local copy whenever you start a working session. On the master branch (this term is explained below), run:

git pull

Viewing the history

Each change is contained in a commit with an explanatory message. To list commits starting from the latest:

git log

Press <Enter> to see more or <Q> to exit.

Start work: make a new branch

The Git workflow is based on branches, which can be viewed as different copies of the source code with concurrent changes that are eventually merged. You start a contribution by creating a branch, freezing the initial state of the source code you will base your work onto. Ultimately, your branch will be merged in master. This latter special branch centralizes all features developed simultaneously and is the source for unstable releases.

Note: Remember, never directly commit to master.

Let’s pretend you want to add a section to the Contributor’s Guide about using branches. To create a new branch for this:

git branch cg-add-branches

Switching branches

Switching branches is somehow like “loading a file”, although in this case it is really “loading a directory and subdirectories full of files”. The command to use is git checkout.

git checkout master
git checkout cg-add-branches
git checkout origin/release/unstable

Branches that begin with origin/ are part of the remote repository, rather than your local repository, so when you check them out you get a temporary local branch. Therefore, do not commit to these either. Always work in a local branch.


Listing branches

To list local branches:

git branch

If you want remote branches too:

git branch -a

In the output, the current branch is prefixed with a star.


Staging and committing files

Now edit files. To show a summary of your edits:

git status

For every file that you modified or added, first preview your changes:

git diff file

If everything looks right:

git add file

Then commit your changes:

git commit

A text editor window appears for you to write a commit message. See Writing good commit messages.


Amending and reverting changes

To add some more changes to the latest commit, stage them using git add, then run:

git commit --amend

This also works for rephrasing the commit message.

To revert changes to a file that has not been committed yet:

git checkout filename

To get back to the last commit, discarding all changes:

git reset --hard HEAD

Uploading your branch for review

To upload the current branch on the remote repository:

git push -u fork cg-add-branches

This sets the remote branch so subsequent pushes are simpler:

git push

The next section covers how to create a merge request from your branch.


Deleting branches

After the merge request has passed testing and was merged to master, or after a failed experiment, you can delete your local branch.

git checkout master
git branch -d cg-add-branches

As a safety measure, this will fail if the commits of cg-add-branches are not present in master. This can be because you used GitLab to rebase your branch, which modifies the commit data and changes the hash. If you are sure that the branch is not needed anymore, replace the -d on the final line with a -D instead.

Over time, remote branches of accepted merge requests may accumulate in your local repository. If you want to delete these and get back to the state of the official repository, run

git fetch -p origin

(short for --prune) once in a while.


LilyPond — Contributor’s Guide v2.23.3 (development-branch).