2.3 git-cl

Git-cl is a ‘helper script’ that uploads patches to Google’s Rietveld Code Review Tool – used by the developers for patch review – and, at the same time, updates LilyPond’s issue tracker.


Installing git-cl

Note: LilyDev users can jump straight to the next section on updating git-cl as it will already be installed in your home directory.

  1. Download git-cl by running the command:
    git clone https://github.com/gperciva/git-cl.git
    

    or, if that command fails for any reason, try:

    git clone git://github.com/gperciva/git-cl.git
    
  2. Add the ‘git-cl/’ directory to your PATH or create a symbolic link to the git-cl and upload.py scripts in one of your PATH directories (e.g. ‘$HOME/bin’).

    In GNU/Linux you can add directories to PATH by adding this line to your ‘.bashrc’ file located in your home directory:

    PATH=~/directory_containing_git-cl:"${PATH}"
    

Updating git-cl

LilyDev users should make sure that they always have the latest version of git-cl installed. It is possible that changes have been made to git-cl that are not (yet) included in the version of LilyDev that you are using.

Using a terminal run the following commands:

cd ~/git-cl/
git pull

This will download and update you to the lastest version of git-cl.


Configuring git-cl

Because git-cl updates two separate websites (Google’s Rietveld Code Review Tool and LilyPond’s issue tracker) you must have a valid user account (login and password) for both sites.

Set up a login account for Rietveld Code Review Tool

For the Rietveld Code Review Tool you will need a Google account but this does not require ‘Google’ email address; i.e. any email address for your Google account can be used. Just select the option “I prefer to use my current email address” when you sign up with Google.

Note: In order for git-cl to work correctly with this Google account, your Google Account Settings must have the ‘Access for less secure apps’ set to ‘Allowed’ – this is normally the default setting.

Set up a login account for LilyPond’s Issue Tracker

Please register a user account at https://sourceforge.net/user/registration preferably using the same email address that you want to use LilyPond Developer mailing list login.

Once you have created this Sourceforge user account, send an email to the LilyPond Developer’s mailing list (lilypond-devel@gnu.org) asking for write access to the issue tracker along with your Sourceforce Username (not email address) and someone will then be able to set this up for you.

Authorizing git-cl for the LilyPond issue tracker

The git-cl command itself also needs to be ‘authorized’ so that it can access the LilyPond issue tracker.

  1. Once you have been given a valid login for the LilyPond issue tracker, go to the ‘Account settings’ and select the ‘OAuth’ tab.
  2. Locate the ‘Register New Application’ section and enter git-cl in the ‘Application Name:’ field.
  3. Click on the ‘Register new application’ button. You should now see ‘git-cl’ listed under the ‘My Applications’ section.
  4. Click on the ‘Generate Bearer Token’ button. You should now see ‘git-cl’ listed under the ‘Authorized Applications’ section along with a value for the ‘Bearer Token’ entry. This value is used, in the next steps, to allow git-cl to access and update the LilyPond issue tracker.

Installing ca-certificates

In order to have git-cl properly update issues on the SourceForge Allura issue tracker, you must have the package ca-certificates installed. You can check to see if the package is installed with

apt --installed list | grep ca-certificates

If ca-certificates is installed, you will get a result that shows the version that is installed. If it is not installed, there will be no version displayed.

Install ca-certificates with the following:

sudo apt-get install ca-certificates

Running git-cl for the first time

  1. Using a terminal, move to the top level of the $LILYPOND_GIT directory and then run git-cl with the config option:
    cd $LILYPOND_GIT
    git-cl config
    

    You will see a series of prompts. For most of them you can simply accept the default value by responding with a newline (i.e. by pressing return or enter).

  2. The prompt for the Rietveld server (the patch review tool), which defaults to codereview.appspot.com
    Rietveld server (host[:port]) [codereview.appspot.com]:
    
  3. The prompt for the Allura server (the issue tracker), which defaults to https://sourceforge.net/p/testlilyissues/issues/
    Allura server [https://sourceforge.net/p/testlilyissues/issues/]:
    
  4. When prompted for the Allura bearer token copy/paste the value generated in the previous steps for Authorising git-cl for the LilyPond issue tracker
     
    Allura bearer token (see https://sourceforge.net/auth/oauth/): fdbfca60801533465480
    

    Note: The above is a ‘fake’ bearer token used just for illustration. Do not use this value.

  5. Finally, the prompt for the CC list, which defaults to lilypond-devel@gnu.org, the LilyPond Developer’s email list.
    CC list ("x" to clear) [lilypond-devel@gnu.org]:
    

The git-cl script should now be correctly configured for use.


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