3.2 Git cheat sheet (LilyPond Contributor’s Guide)

### 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, see 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 this 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 into `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 switch`.1

    git switch master
    git switch cg-add-branches
    git switch 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.

You might want to use `git add -p` instead of `git add`; this allows you to add changes incrementally in an interactive way.

To revert changes to a file that have not been committed yet, use `git restore`:2

    git restore filename

You might want to use `git reset -p` instead of `git restore`; this allows you to revert changes incrementally in an interactive way.

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

    git reset --hard HEAD

If the commit to edit is not the top one, you need to perform an interactive rebase with `git rebase -i $(git merge-base master HEAD)`. The full functionality of `git rebase -i` is not covered here; please try it and follow Git’s instructions or read any tutorial on the Web.

#### 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 Request3 from your branch.

In response to review comments, you may need to amend your changes. Do not close your merge request and open a new one; instead, amend your commits, which can be done with `git commit --amend` or `git rebase -i` as explained above. Note that Git will by default refuse a push when you have amended your commits. This is because this kind of push is a destructive operation: once it is done, the old commits are no longer available on the remote branch. Git prevents this as a safety measure against deleting commits added by someone else without you realizing it. Do not follow Git’s advice to do `git pull` (which would try to integrate the remote changes into the local ones); instead, just force it with

    git push --force-with-lease

Also note that due to the way GitLab compares successive revisions of a merge request, it is preferable if you do not mix catching up with `master` and changing your commits. In other words, use `git rebase -i $(git merge-base master HEAD)` rather than `git rebase -i master`. Alternatively, first rebase on `master` and push, then do the interactive rebase and push again.

#### 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 switch 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.

#### Footnotes

##### (1)

If you are using an outdated version of Git (older than 2.23), you need to use `git checkout` instead.

##### (2)

If you are using an outdated version of Git (older than 2.23), you need to use `git checkout` instead.

##### (3)

You may probably know this already under the name Pull Request, as it is called on the GitHub platform. It’s not exactly the same, though.

#### LilyPond Contributor’s Guide v2.26.0 (stable-branch).

- 1 Introduction to contributing
  - 1.1 Help us
  - 1.2 Overview of work flow
  - 1.3 Summary for experienced developers
  - 1.4 Mentors
- 2 Quick start
  - 2.1 LilyDev
    - Installing LilyDev in VirtualBox
    - Configuring LilyDev in VirtualBox
  - 2.2 Compiling with LilyDev
  - 2.3 Now start work!
- 3 Working with source code
  - 3.1 Setting up
    - 3.1.1 Installing Git
    - 3.1.2 Creating a GitLab account and setting up SSH
    - 3.1.3 Cloning and forking the repository
    - 3.1.4 Configuring Git
  - 3.2 Git cheat sheet
  - 3.3 Lifecycle of a merge request
    - 3.3.1 Uploading a patch for review
    - 3.3.2 Automated testing
    - 3.3.3 Patch countdown
    - 3.3.4 Merging to master
    - 3.3.5 Abandoned patches
  - 3.4 Writing good commit messages
  - 3.5 Commit access
  - 3.6 Further Git documentation resources
  - 3.7 Repository directory structure
- 4 Compiling
  - 4.1 Overview of compiling
  - 4.2 Requirements
    - 4.2.1 Requirements for running LilyPond
    - 4.2.2 Requirements for compiling LilyPond
      - Fedora
      - Linux Mint
      - OpenSUSE
      - Ubuntu
      - Other
    - 4.2.3 Requirements for building documentation
  - 4.3 Getting the source code
  - 4.4 Configuring `make`
    - 4.4.1 Build modes
    - 4.4.2 Running `autogen.sh`
    - 4.4.3 Running `configure`
      - Configuration options
      - Checking build dependencies
      - Configuring target directories
  - 4.5 Compiling LilyPond
    - 4.5.1 Using `make`
    - 4.5.2 Saving time with the `-j` option
    - 4.5.3 Useful `make` variables
  - 4.6 Post-compilation options
    - 4.6.1 Installing LilyPond from a local build
    - 4.6.2 Generating documentation
      - Documentation editor’s edit/compile cycle
      - Building documentation
      - Building a single document
      - Saving time with `CPU_COUNT`
      - Installing documentation
      - Building documentation without compiling
    - 4.6.3 Testing LilyPond binary
  - 4.7 Problems
  - 4.8 Concurrent stable and development versions
    - 4.8.1 Replacing the notation fonts in development versions
  - 4.9 Build system
- 5 Documentation work
  - 5.1 Introduction to documentation work
  - 5.2 `\version` in documentation files
  - 5.3 Documentation suggestions
  - 5.4 Texinfo introduction and usage policy
    - 5.4.1 Texinfo introduction
    - 5.4.2 Documentation files
    - 5.4.3 Sectioning commands
    - 5.4.4 Menus
    - 5.4.5 LilyPond formatting
    - 5.4.6 Text formatting
    - 5.4.7 Syntax survey
      - Comments
      - Cross-references
      - External links
      - Fixed-width font
      - Indexing
      - Lists
      - Special characters
      - Miscellany
    - 5.4.8 Other text concerns
  - 5.5 Documentation policy
    - 5.5.1 Books
    - 5.5.2 Section organization
    - 5.5.3 Checking cross-references
    - 5.5.4 General writing
    - 5.5.5 Technical writing style
  - 5.6 Tips for writing documentation
    - 5.6.1 Working on subsections
    - 5.6.2 Searching
  - 5.7 Scripts to ease documentation work
    - 5.7.1 Building only one section of the documentation
    - 5.7.2 Updating documentation with `convert-ly`
  - 5.8 Documentation strings in the Internals Reference
  - 5.9 Translating the documentation
    - 5.9.1 Getting started with documentation translation
      - Translation requirements
      - Which documentation can be translated
      - Starting translation in a new language
    - 5.9.2 Documentation translation details
      - Files to be translated
      - Translating the website and other Texinfo documentation
      - Adding a Texinfo manual
    - 5.9.3 Documentation translation maintenance
      - Check state of translation
      - Updating documentation translation
      - Updating translation committishes
      - Maintaining without updating translations
    - 5.9.4 Technical background
- 6 Website work
  - 6.1 Introduction to website work
  - 6.2 Uploading website
  - 6.3 Debugging website and docs locally
  - 6.4 Translating the website
- 7 LilyPond Wiki work
  - 7.1 Introduction to the LilyPond Wiki
  - 7.2 Adding and editing snippets
  - 7.3 Snippet administration
  - 7.4 The `makelsr.pl` script
  - 7.5 LilyPond Wiki to Git
- 8 Issues
  - 8.1 Introduction to issues
  - 8.2 Triaging bugs
  - 8.3 Issue classification
  - 8.4 Adding issues to the tracker
- 9 Regression tests
  - 9.1 Introduction to regression tests
  - 9.2 Precompiled regression tests
  - 9.3 Compiling regression tests
  - 9.4 Regtest comparison
  - 9.5 Pixel-based regtest comparison
  - 9.6 Finding the cause of a regression
  - 9.7 MusicXML tests
- 10 Programming work
  - 10.1 Overview of LilyPond architecture
  - 10.2 LilyPond programming languages
  - 10.3 Programming without compiling
  - 10.4 Finding functions
  - 10.5 Code style
    - 10.5.1 Languages
    - 10.5.2 Filenames
    - 10.5.3 Code formatting
    - 10.5.4 Naming Conventions
    - 10.5.5 Broken code
    - 10.5.6 Code comments
    - 10.5.7 Handling errors
    - 10.5.8 Localization
  - 10.6 Warnings, Errors, Progress and Debug Output
  - 10.7 Debugging LilyPond
    - 10.7.1 Debugging overview
    - 10.7.2 Debugging C++ code
    - 10.7.3 Debugging Scheme code
    - 10.7.4 Debugging scoring algorithms
    - 10.7.5 Debugging skylines
  - 10.8 Tracing object relationships
  - 10.9 Tracing processing time
  - 10.10 Adding or modifying features
    - 10.10.1 Write the code
    - 10.10.2 Write regression tests
    - 10.10.3 Write convert-ly rule
    - 10.10.4 Automatically update documentation
    - 10.10.5 Manually update documentation
    - 10.10.6 Edit changes.tely
    - 10.10.7 Verify successful build
    - 10.10.8 Verify regression tests
    - 10.10.9 Post patch for comments
    - 10.10.10 Push patch
    - 10.10.11 Closing the issues
  - 10.11 Iterator tutorial
  - 10.12 Engraver tutorial
    - 10.12.1 Useful methods for information processing
    - 10.12.2 Translation process
    - 10.12.3 Listening to music events
    - 10.12.4 Acknowledging grobs
    - 10.12.5 Engraver declaration/documentation
  - 10.13 Callback tutorial
  - 10.14 Understanding pure properties
    - 10.14.1 Purity in LilyPond
    - 10.14.2 Writing a pure function
    - 10.14.3 How purity is defined and stored
    - 10.14.4 Where purity is used
    - 10.14.5 Case studies
    - 10.14.6 Debugging tips
  - 10.15 LilyPond scoping
  - 10.16 Regular expressions
  - 10.17 Scheme->C interface
    - 10.17.1 Comparison
    - 10.17.2 Conversion
  - 10.18 Garbage collection for dummies
  - 10.19 LilyPond miscellany
    - 10.19.1 Spacing algorithms
    - 10.19.2 Info from Han-Wen email
    - 10.19.3 Music functions and Guile debugging
    - 10.19.4 Articulations on EventChord
- 11 Release work
  - 11.1 Development phases
  - 11.2 Release checklist
  - 11.3 Major release checklist
- 12 Modifying the Emmentaler font
  - 12.1 Overview of the Emmentaler font
  - 12.2 Font creation tools
  - 12.3 Adding a new font section
  - 12.4 Adding a new glyph
  - 12.5 Building the changed font
  - 12.6 METAFONT formatting rules
- 13 Administrative policies
  - 13.1 LilyPond is GNU Software
  - 13.2 Environment variables
  - 13.3 Performing yearly copyright update (“grand-replace”)
- Appendix A GNU Free Documentation License