Finish my work on CG 1.

[lilypond.git] / Documentation / devel / git-starting.itexi

@c -*- coding: us-ascii; mode: texinfo; -*-
@node Starting with git
@chapter Starting with git

@menu
* Getting the source code::     
* Updating the source code::    
* Sharing your changes::        
* Other interesting Git commands::  
* Git on Windows::              
@end menu


@node Getting the source code
@section Getting the source code

@menu
* Git introduction::            
* Main source code::            
* Website source code::         
* Documentation translations source code::  
* Other branches::              
* Other locations for git::     
* Git user configuration::      
@end menu

@node Git introduction
@subsection Git introduction

The source code is kept in a git respository.  This allows us to
track changes to files, and for multiple people to work on the
same set of files (generally) without any problems.

@warning{These instructions assume that you are using the
command-line version of git 1.5 or higher.  Windows users should
skip to @ref{Git on Windows}.}


@node Main source code
@subsection Main source code

To get the main source code and documentation,

FIXME: test this!!!

@example
mkdir lilypond; cd lilypond
git init-db
git remote add -f -t master -m master origin git://git.sv.gnu.org/lilypond.git/
git checkout -b master origin/master
@end example


@node Website source code
@subsection Website source code

To get the website (including translations),

FIXME: test this!!!

@example
mkdir lilypod-web ; cd lilypond-web
git init-db
git remote add -f -t web -m web origin git://git.sv.gnu.org/lilypond.git/
git checkout -b web origin/web
@end example


@node Documentation translations source code
@subsection Documentation translations source code

To translate the documentation (@emph{not} the website),

FIXME: change!!!

@example
mkdir lilypond-translate; cd lilypond-translate
git init-db
git remote add -f -t web -m web origin git://git.sv.gnu.org/lilypond.git/
git checkout -b web origin/web
@end example


@node Other branches
@subsection Other branches

Most contributors will never need to touch the other branches.  If
you wish to do so, you will need more familiarity with git.

@itemize

@item @code{gub}:
This stores the Grand Unified Binary, our cross-platform building
tool.  For more info, see @uref{http://lilypond.org/gub}.  The git
location is:

@example
http://github.com/janneke/gub
@end example

@item @code{dev/XYZ}:
These branches are for individual developers.  They store code
which is not yet stable enough to be added to the @code{master}
branch.

@item @code{stable/XYZ}:
The branches are kept for archival reasons.

@end itemize


@node Other locations for git
@subsection Other locations for git

If you have difficulty connecting to most of the repositories
listed in earlier sections, try:

@example
git://git.sv.gnu.org/lilypond.git
http://git.sv.gnu.org/r/lilypond.git
ssh://git.sv.gnu.org/srv/git/lilypond.git
@end example


@node Git user configuration
@subsection Git user configuration

To configure git to automatically use your name and email address
for patches,

@example
git config --global user.name "MYNAME"
git config --global user.email myemail@@example.net
@end example


@node Updating the source code
@section Updating the source code

@menu
* Importance of updating::      
* Update command::              
* Resolving conflicts::         
* Technical notes::             
@end menu


@node Importance of updating
@subsection Importance of updating

In a large project like LilyPond, contributors sometimes edit the
same file at the same time.  As long as everybody updates their
version of the file with the most recent changes (@qq{pull}ing),
there are generally no problems with this multiple-person editing.
However, serious problems can arise if you do not pull before
attempting commit.


@node Update command
@subsection Updating command

Whenever you are asked to pull, it means you should update your
local copy of the repository with the changes made by others on
the remote @code{git.sv.gnu.org} repository:

@example
git pull origin
@end example


@node Resolving conflicts
@subsection Resolving conflicts

Occasionally an update may result in conflicts -- this happens
when you and somebody else hae modified the same part of the same
file and git cannot figure out how to merge the two versions
together.  When this happens, you must manually merge the two
versions.

@example
TODO
@end example


@node Technical notes
@subsection Technical notes

TODO: I'm not going to bother with this section. -gp

Let's explain a bit of Git vocabulary.  The @code{git pull origin}
command is just a shortcut for this command:

@example
git pull git://git.sv.gnu.org/lilypond.git/ MY-BRANCH:origin/MY-BRANCH
@end example

A commit is a set of changes made to the sources; it also includes
the committish of the parent commit, the name and e-mail of the
author (the person who wrote the changes), the name and e-mail of
the committer (the person who brings these changes into the git
repository), and a commit message.

A committish is the SHA1 checksum of a commit, a number made of 40
hexadecimal digits, which acts as the internal unique identifier
for this commit.  To refer to a particular revision, don't use
vague references like the (approximative) date, simply
copy'n'paste the committish.

A branch is a tree (in the mathematical or computer science sense)
of commits, and the topmost commit of this branch is called a
head.

The "git fetch" command above has created a branch called
@code{origin/web} in your local Git repository.  As this branch is
a copy of the remote branch web from git.sv.gnu.org LilyPond
repository, it is called a `remote branch', and is meant to track
the changes on the branch from git.sv.gnu.org: it will be updated
every time you run 'git pull' or 'git fetch' with this branch
reference as argument, e.g.  by using .git/remotes/web remote file
when running 'git fetch web'.

The 'git checkout' command above has created a branch named 'web'.  At
the beginning, this branch is identical to 'origin/web', but it will
differ as soon as you make changes, e.g. adding newly translated
pages.  Whenever you pull, you merge the changes from origin/web and
your web branch since the last pulling.  If you do not have push
(i.e. "write") access on git.sv.gnu.org, your web branch will always
differ from origin/web.  In this case, remember that other people
working like you on the remote web branch of
git://git.sv.gnu.org/lilypond.git/ know nothing about your own web
branch: this means that whenever you use a committish or make a patch,
others expect you to take the lastest commit of origin/web branch as a
reference.

This README tries to explain most of Git commands needed for
translating the web site.  However, you are invited to read
further documentation to make git more familiar to you; for
instance, take a look at @uref{http://git.or.cz/gitwiki/},
especially GitDocumentation and GitGlossary; a good alternative to
reading the wiki is reading the first two chapters of Git User's
Manual at
@uref{http://www.kernel.org/pub/software/scm/git/docs/user-manual.html}



@node Sharing your changes
@section Sharing your changes

@menu
* Producing a patch::           
* Committing directly::         
@end menu


@node Producing a patch
@subsection Producing a patch

Once you have finished editing your files, checked that your
changes meet the @ref{Code style} and/or @ref{Documentation
policy}, and checked that the entire thing compiles, you may

@example
git commit -a 
git-format-patch HEAD
@end example

Send an email to @email{lilypond-devel@@gnu.org} with the diff as
an attachment.


@node Committing directly
@subsection Committing directly

Most contributors do not have permission to commit directly.  If
you do, edit @file{.git/config} to contain

@example
FIXME?  Is anything needed, or did the previous commands set it
up?
@end example

You may then @code{git push}.


@node Other interesting Git commands
@section Other interesting Git commands

@menu
* Git log::                     
* Applying git patches::        
@end menu


@node Git log
@subsection Git log

The commands above don't only bring you the latest version of the
sources, but also the full history of revisions (revisons, also
called commits, are changes made to the sources), stored in the
.git directory.  You can browse this history with

@example
git log     # only shows the logs (author, committish and commit message)
git log -p  # also shows diffs
gitk        # shows history graphically
@end example


@node Applying git patches
@subsection Applying git patches

Well-formed git patches should be committed with

@example
git-am
@end example

Patches created without @code{git-format-patch} should be
committed with

@example
git-apply
@end example



@node Git on Windows
@section Git on Windows

@c Some of this may duplicate stuff in other sections
@c Clear this up later  -td

@subsection 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 @q{branch}, of which there may be
several.  The files in the local repository always correspond to
those on the currently @q{checked out} local branch.

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

@subsection Installing git

Obtain Git from
@uref{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 will be
unfamiliar to most Windows users, so follow these
instructions carefully.  Commands are entered at a $ prompt
and are terminated by keying a newline.

@subsection 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

@example
cd [path]/Git
@end example

to position the shell at your new Git repository.

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

@example
cd "[path]/Git"
@end example

Then type

@example
git init
@end example

to initialize your Git repository.

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

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

to download the lilypond master files.

@warning{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 @q{lily-local} - make up your own.
Then, finally, type

@example
git checkout -b lily-local origin/master
@end example

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 and look in your Git repository.  You
should see lots of folders.  The LilyPond documentation
can be found in Git/Documentation/user.

Terminate the Git bash shell with the exit command.

@subsection 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

@example
cd [path]/Git
git gui
@end example

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 your local branch is the same as the master branch.
After a file has been edited and saved the top panel on the right
will display the differences between the edited file selected
from one of the left panels and the one on master.  The
final panel at bottom right is used to enter a descriptive
message about the change before committing a file.

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.

@subsection Personalising your local git repository

Open the Git GUI, click on

@example
Edit -> Options
@end example

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

@subsection Checking out a branch

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

@example
Branch -> Checkout
@end example

You should have one local branch called lily-local and one
tracking branch called origin/master.

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

@subsection Updating files from master

Before starting the editing of a file ensure you have the
latest copy from master by first clicking

@example
Remote -> Fetch from -> origin
@end example

in the Git GUI.

This will place details of all the changes made by others
into the @q{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 any of your local branches.

To merge the changed files into your local branch click on

@example
Merge -> Local Merge
@end example

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

This will update all the files in that branch to reflect the
currect 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).

@subsection Editing files

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

If you wish to cancel your changes the original version
may be recovered at any time before a commit is made
by selecting Commit -> Revert changes.  This will even
recover a deleted file.

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

@subsection Sending changes to origin/master

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

@example
cd [path]/Git
@end example

if necessary, then produce the patch with

@example
git-format-patch -n
@end example

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

@subsection Resolving merge conflicts

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

@example
Repository -> Visualise all branch history
@end example

This opens up a very useful new window called @q{gitk}.

If the diagram at top left of the resulting window
does not show your branch on a single node at the
top your branch has diverged from master.  This is
quite normal if files you have modified yourself
have not yet been committed to master, or if files
have been modified and committed by others since
your last merge.

If a file being merged from 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 master
for you has added some changes of his own before
committing your changes to master, or if someone
else has updated the same parent file as you at
the same time.

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]