3.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 repository
for LilyPond files. Editors hold a local copy 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 (called a ‘commit’) are given a unique 40-digit
hexadecimal reference number called the ‘Committish’ or ‘SHA1
ID’ which identifies the commit 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 as a complete file or as a ‘diff’ or ‘patch’
(which send just the differences from the master repository).

3.5.2 Installing git

Note that most users will not need to install SSH. That is not
required until you have been granted direct push permissions to
the master git repository.

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.

3.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, but if you intend using
Git for other projects a directory name like lilypond-git
might be better. You will need to have space for around
100Mbytes.

Start the Git bash shell by clicking on the desk-top icon
installed with Git and 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 -ft 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. It is
usual to call it ‘master’ and we shall do that here.

To do this, type

git checkout -b master origin/master

This creates a second branch called ‘master’. You will see two
warnings (ignore these), and a message advising you that your
local branch ‘master’ has been set up to track the remote
branch. You now have two branches, a local branch called
‘master’, and a tracking branch called ‘origin/master’, which
is a shortened form of ‘remotes/origin/master’.

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 [path]/Git/Documentation/.

The Git bash shell is terminated by typing exit or by
clicking on the usual Windows close-window widget.

3.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 top panel on the left contains the names of files which you
are in the process of editing (Unstaged Changes), and the lower
panel on the left contains the names of files you have finished
editing and have staged ready for committing (Staged Changes). At
present, 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 on the current branch.

The 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.

3.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.

Note that Windows users must leave the default setting for line
endings unchanged. All files in a git repository must have lines
terminated by just a LF, as this is required for Merge to work,
but Windows files are terminated by CRLF by default. The git
default setting causes the line endings of files in a Windows git
repository to be flipped automatically between LF and CRLF as
required. This enables files to be edited by any Windows editor
without causing problems in the git repository.

3.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 ‘master’ and one
tracking branch called ‘origin/master’. The latter is your
local copy of the ‘remotes/origin/master’ branch in the master
LilyPond repository. The local ‘master’ 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.

3.5.7 Updating files from ‘remote/origin/master’

Before starting the editing of a file, ensure your local
repository contains the latest version of the files in the remote
repository 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, but you must never edit
any files while this branch is checked out. Check out your local
‘master’ branch again.

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

Merge -> Local Merge

and if necessary select the local ‘master’ branch.

Note that a merge cannot be completed if you have made any local
changes which have not yet been committed.

This merge will update all the files in the ‘master’ 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).

3.5.8 Editing files

First ensure your ‘master’ 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 editing any time.

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

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
‘master’ 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 right.
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.

3.5.9 Sending changes to ‘remotes/origin/master’

If you do not have write access to ‘remotes/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 origin

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 the commit message.

3.5.10 Resolving merge conflicts

As soon as you have committed a changed file your local
master branch has diverged from origin/master, and
will remain diverged until your changes have been committed in
remotes/origin/master and Fetched back into your
origin/master branch. Similarly, if a new commit has been
made to remotes/origin/master by someone else and Fetched,
your local master 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 yourself and others.

If the diagram at top left of the resulting window does not show
your master tag on the same node as the
remotes/origin/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
remotes/origin/master and Fetched, or if files modified and
committed by others have been Fetched since you last Merged
origin/master into your local master 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
remotes/origin/master for you has added some changes of his
own before committing your changes to
remotes/origin/master, or if someone else has changed the
same file since you last fetched the file from
remotes/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]