1.5 Git on Windows

1.5.1 Background to nomenclature

Git is a system for tracking the changes made to source files by a distributed set of editors. It is designed to work without a master repository, but we have chosen to have a master respository for LilyPond files. Editors hold local copies of the master repository together with any changes they have made locally. Local changes are held in a local ‘branch’, of which there may be several, but these instructions assume you are using just one. The files visible in the local repository always correspond to those on the currently ‘checked out’ local branch.

Files are edited on a local branch, and in that state the changes are said to be ‘unstaged’. When editing is complete, the changes are moved to being ‘staged for commit’, and finally the changes are ‘committed’ to the local branch. Once committed, the changes are given a unique reference number called the ‘Committish’ which identifies them to Git. Such committed changes can be sent to the master repository by ‘pushing’ them (if you have write permission) or by sending them by email to someone who has, either complete or as a ‘diff’ or ‘patch’ (which send just the differences from master).

1.5.2 Installing git

Obtain Git from http://code.google.com/p/msysgit/downloads/list. (Note, not msysGit, which is for Git developers) and install.

Start Git by clicking on the desktop icon. This will bring up a command line bash shell. This may be unfamiliar to Windows users. If so, follow these instructions carefully. Commands are entered at a $ prompt and are terminated by keying a newline.

1.5.3 Initialising Git

Decide where you wish to place your local Git repository, creating the folders in Windows as necessary. Here we call the folder to contain the repository [path]/Git. You will need to have space for around 150Mbytes.

In the git bash shell type

cd [path]/Git

to position the shell at your new Git repository.

Note: if [path] contains folders with names containing spaces use

cd "[path]/Git"

Then type

git init

to initialize your Git repository.

Then type (all on one line; the shell will wrap automatically)

git remote add -f -t master origin git://git.sv.gnu.org/lilypond.git

to download the lilypond master files.

Note: Be patient! Even on a broadband connection this can take 10 minutes or more. Wait for lots of [new tag] messages and the $ prompt.

We now need to generate a local copy of the downloaded files in a new local branch. Your local branch needs to have a name, here we call it ‘lily-local’ - you may wish to make up your own.

Then, finally, type

git checkout -b lily-local origin/master

to create the lily-local branch containing the local copies of the master files. You will be advised your local branch has been set up to track the remote branch.

Return to Windows Explorer and look in your Git repository. You should see lots of folders. For example, the LilyPond documentation can be found in Git/Documentation/user.

Terminate the Git bash shell by typing exit.

1.5.4 Git GUI

Almost all subsequent work will use the Git Graphical User Interface, which avoids having to type command line commands. To start Git GUI first start the Git bash shell by clicking on the desktop icon, and type

cd [path]/Git
git gui

The Git GUI will open in a new window. It contains four panels and 7 pull-down menus. At this stage do not use any of the commands under Branch, Commit, Merge or Remote. These will be explained later.

The two panels on the left contain the names of files which you are in the process of editing (Unstaged Changes), and files you have finished editing and have staged ready for committing (Staged Changes). At this stage these panels will be empty as you have not yet made any changes to any file. After a file has been edited and saved the top panel on the right will display the differences between the edited file selected in one of the panels on the left and the last version committed.

The final panel at bottom right is used to enter a descriptive message about the change before committing it.

The Git GUI is terminated by entering CNTL-Q while it is the active window or by clicking on the usual Windows close-window widget.

1.5.5 Personalising your local git repository

Open the Git GUI, click on

Edit -> Options

and enter your name and email address in the left-hand (Git Repository) panel. Leave everything else unchanged and save it.

1.5.6 Checking out a branch

At this stage you have two branches in your local repository, both identical. To see them click on

Branch -> Checkout

You should have one local branch called lily-local and one tracking branch called origin/master. The latter is your local copy of the remote/origin/master branch in the master LilyPond repository. The lily-local branch is where you will make your local changes.

When a particular branch is selected, i.e., checked out, the files visible in your repository are changed to reflect the state of the files on that branch.

1.5.7 Updating files from remote/origin/master

Before starting the editing of a file, ensure your local branches contain the latest version in remote/origin/master by first clicking

Remote -> Fetch from -> origin

in the Git GUI.

This will place the latest version of every file, including all the changes made by others, into the ‘origin/master’ branch of the tracking branches in your git repository. You can see these files by checking out this branch. This will not affect any files you have modified in your local branch.

You then need to merge these fetched files into your local branch by clicking on

Merge -> Local Merge

and if necessary select the local branch into which the merge is to be made.

Note that a merge cannot be completed if there are any local uncommitted changes on the lily-local branch.

This will update all the files in that branch to reflect the current state of the origin/master branch. If any of the changes conflict with changes you have made yourself recently you will be notified of the conflict (see below).

1.5.8 Editing files

First ensure your lily-local branch is checked out, then simply edit the files in your local Git repository with your favourite editor and save them back there. If any file contains non-ASCII characters ensure you save it in UTF-8 format. Git will detect any changes whenever you restart Git GUI and the file names will then be listed in the Unstaged Changes panel. Or you can click the Rescan button to refresh the panel contents at any time. You may break off and resume at editing any time.

The changes you have made may be displayed in diff form in the top right-hand panel by clicking on the name in Git GUI.

When your editing is complete, move the files from being Unstaged to Staged by clicking the document symbol to the left of each name. If you change your mind it can be moved back by clicking on the ticked box to the left of the name.

Finally the changes you have made may be committed to your lily-local branch by entering a brief message in the Commit Message box and clicking the Commit button.

If you wish to amend your changes after a commit has been made, the original version and the changes you made in that commit may be recovered by selecting

Commit -> Amend Last Commit

or by checking the Amend Last Commit radio button at bottom left. This will return the changes to the Staged state, so further editing made be carried out within that commit. This must only be done before the changes have been Pushed or sent to your mentor for Pushing - after that it is too late and corrections have to be made as a separate commit.

1.5.9 Sending changes to remote/origin/master

If you do not have write access to remote/origin/master you will need to send your changes by email to someone who does.

First you need to create a diff or patch file containing your changes. To create this, the file must first be committed. Then terminate the Git GUI. In the git bash shell first cd to your Git repository with

cd [path]/Git

if necessary, then produce the patch with

git-format-patch -n

where n an integer, normally 1. This will create a patch file for all the locally committed files which differ from origin/master. The patch file can be found in [path]/Git and will have a name formed from n and the commit message.

1.5.10 Resolving merge conflicts

As soon as you have committed a changed file your local branch has diverged from origin/master, and will remain diverged until your changes have been committed in remote/origin/master and Fetched back into your origin/master. Similarly, if a new commit has been made to remote/origin/master by someone else and Fetched, your lily-local branch is divergent. You can detect a divergent branch by clicking on

Repository -> Visualise all branch history

This opens up a very useful new window called ‘gitk’. Use this to browse all the commits made by others.

If the diagram at top left of the resulting window does not show your branch’s tag on the same node as the remote/origins/master tag your branch has diverged from origin/master. This is quite normal if files you have modified yourself have not yet been Pushed to remote/origin/master and Fetched, or if files modified and committed by others have been Fetched since you last Merged origin/master into your lily-local branch.

If a file being merged from origin/master differs from one you have modified in a way that cannot be resolved automatically by git, Merge will report a Conflict which you must resolve by editing the file to create the version you wish to keep.

This could happen if the person updating remote/origin/master for you has added some changes of his own before committing your changes to remote/origin/master, or if someone else has changed the same file since you last fetched the file from remote/origin/master.

Open the file in your editor and look for sections which are delimited with ...

[to be completed when I next have a merge conflict to be sure I give the right instructions -td]

1.5.11 Other actions

The instructions above describe the simplest way of using git on Windows. Other git facilities which may usefully supplement these include

Once familiarity with using git on Windows has been gained the standard git manuals can be used to learn about these.

Contributor’s Guide