1 @c -*- coding: us-ascii; mode: texinfo; -*-
2 @node Starting with git
3 @chapter Starting with git
6 * Getting the source code::
7 * Updating the source code::
8 * Sharing your changes::
9 * Other interesting Git commands::
14 @node Getting the source code
15 @section Getting the source code
20 * Website source code::
21 * Documentation translations source code::
23 * Other locations for git::
24 * Git user configuration::
27 @node Git introduction
28 @subsection Git introduction
30 The source code is kept in a git respository. This allows us to
31 track changes to files, and for multiple people to work on the
32 same set of files (generally) without any problems.
34 @warning{These instructions assume that you are using the
35 command-line version of git 1.5 or higher. Windows users should
36 skip to @ref{Git on Windows}.}
39 @node Main source code
40 @subsection Main source code
42 To get the main source code and documentation,
45 mkdir lilypond; cd lilypond
47 git remote add -f -t master -m master origin git://git.sv.gnu.org/lilypond.git/
48 git checkout -b master origin/master
52 @node Website source code
53 @subsection Website source code
55 To get the website (including translations),
58 mkdir lilypond-web ; cd lilypond-web
60 git remote add -f -t web -m web origin git://git.sv.gnu.org/lilypond.git/
61 git checkout -b web origin/web
65 @node Documentation translations source code
66 @subsection Documentation translations source code
68 To translate the documentation (@emph{not} the website),
70 @c TODO this runs off the side of the page in pdf. :(
72 mkdir lilypond-translation; cd lilypond-translation
74 git remote add -f -t lilypond/translation -m lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
75 git checkout -b lilypond/translation origin/lilypond/translation
80 @subsection Other branches
82 Most contributors will never need to touch the other branches. If
83 you wish to do so, you will need more familiarity with git.
88 This stores the Grand Unified Binary, our cross-platform building
90 @c TODO: merge the gub stuff with this CG.
91 For more info, see @uref{http://lilypond.org/gub}. The git
95 http://github.com/janneke/gub
99 These branches are for individual developers. They store code
100 which is not yet stable enough to be added to the @code{master}
103 @item @code{stable/XYZ}:
104 The branches are kept for archival reasons.
109 @node Other locations for git
110 @subsection Other locations for git
112 If you have difficulty connecting to most of the repositories
113 listed in earlier sections, try:
116 http://git.sv.gnu.org/r/lilypond.git
117 git://git.sv.gnu.org/lilypond.git
118 ssh://git.sv.gnu.org/srv/git/lilypond.git
121 @warning{The @code{git://} and @code{ssh://} URLs are intended for
125 @node Git user configuration
126 @subsection Git user configuration
128 To configure git to automatically use your name and email address
132 git config --global user.name "MYNAME"
133 git config --global user.email MYEMAIL@@EXAMPLE.NET
137 @node Updating the source code
138 @section Updating the source code
141 * Importance of updating::
143 * Resolving conflicts::
148 @node Importance of updating
149 @subsection Importance of updating
151 In a large project like LilyPond, contributors sometimes edit the
152 same file at the same time. As long as everybody updates their
153 version of the file with the most recent changes (@qq{pull}ing),
154 there are generally no problems with this multiple-person editing.
155 However, serious problems can arise if you do not pull before
160 @subsection Updating command
162 Whenever you are asked to pull, it means you should update your
163 local copy of the repository with the changes made by others on
164 the remote @code{git.sv.gnu.org} repository:
171 @node Resolving conflicts
172 @subsection Resolving conflicts
174 Occasionally an update may result in conflicts -- this happens
175 when you and somebody else have modified the same part of the same
176 file and git cannot figure out how to merge the two versions
177 together. When this happens, you must manually merge the two
181 FIXME: what the mao should people do?!?! Personally, I just break
186 @node Technical notes
187 @subsection Technical notes
189 TODO: I'm not going to bother with this section. -gp
191 Let's explain a bit of Git vocabulary. The @code{git pull origin}
192 command is just a shortcut for this command:
195 git pull git://git.sv.gnu.org/lilypond.git/ MY-BRANCH:origin/MY-BRANCH
198 A commit is a set of changes made to the sources; it also includes
199 the committish of the parent commit, the name and e-mail of the
200 author (the person who wrote the changes), the name and e-mail of
201 the committer (the person who brings these changes into the git
202 repository), and a commit message.
204 A committish is the SHA1 checksum of a commit, a number made of 40
205 hexadecimal digits, which acts as the internal unique identifier
206 for this commit. To refer to a particular revision, don't use
207 vague references like the (approximative) date, simply
208 copy'n'paste the committish.
210 A branch is a tree (in the mathematical or computer science sense)
211 of commits, and the topmost commit of this branch is called a
214 The @q{git fetch} command above has created a branch called
215 @code{origin/web} in your local Git repository. As this branch is
216 a copy of the remote branch web from git.sv.gnu.org LilyPond
217 repository, it is called a @qq{remote branch,} and is meant to track
218 the changes on the branch from git.sv.gnu.org: it will be updated
219 every time you run @q{git pull} or @q{git fetch} with this branch
220 reference as argument, e.g. by using .git/remotes/web remote file
221 when running @q{git fetch web}.
223 The @q{git checkout} command above has created a branch named @q{web}. At
224 the beginning, this branch is identical to @q{origin/web,} but it will
225 differ as soon as you make changes, e.g. adding newly translated
226 pages. Whenever you pull, you merge the changes from origin/web and
227 your web branch since the last pulling. If you do not have push
228 (i.e. @qq{write}) access on git.sv.gnu.org, your web branch will always
229 differ from origin/web. In this case, remember that other people
230 working like you on the remote web branch of
231 git://git.sv.gnu.org/lilypond.git/ know nothing about your own web
232 branch: this means that whenever you use a committish or make a patch,
233 others expect you to take the latest commit of origin/web branch as a
236 This README tries to explain most of Git commands needed for
237 translating the web site. However, you are invited to read
238 further documentation to make git more familiar to you; for
239 instance, take a look at @uref{http://git.or.cz/gitwiki/},
240 especially GitDocumentation and GitGlossary; a good alternative to
241 reading the wiki is reading the first two chapters of Git User's
243 @uref{http://www.kernel.org/pub/software/scm/git/docs/user-manual.html}
247 @node Sharing your changes
248 @section Sharing your changes
251 * Producing a patch::
252 * Committing directly::
256 @node Producing a patch
257 @subsection Producing a patch
259 Once you have finished editing your files, checked that your
260 changes meet the @ref{Code style} and/or @ref{Documentation
261 policy}, and checked that the entire thing compiles, you may
265 git format-patch origin
268 Send an email to @email{lilypond-devel@@gnu.org} with the diff as
272 @node Committing directly
273 @subsection Committing directly
275 Most contributors do not have permission to commit directly. If
276 you do, edit @file{.git/config}:
280 url = git://git.sv.gnu.org/lilypond.git/
281 %% into something like this:
282 url = ssh://gpercival@@git.sv.gnu.org/srv/git/lilypond.git
285 TODO: upload ssh key to somewhere?
294 @node Other interesting Git commands
295 @section Other interesting Git commands
299 * Applying git patches::
306 The commands above don't only bring you the latest version of the
307 sources, but also the full history of revisions (revisons, also
308 called commits, are changes made to the sources), stored in the
309 .git directory. You can browse this history with
312 git log # only shows the logs (author, committish and commit message)
313 git log -p # also shows diffs
314 gitk # shows history graphically
317 @warning{The @code{gitk} command may require a separate @code{gitk} package,
318 available in the appropriate distribution's repositories.}
320 @node Applying git patches
321 @subsection Applying git patches
323 Well-formed git patches should be committed with
329 Patches created without @code{git format-patch} should be
339 @section Git on Windows
341 @c Some of this may duplicate stuff in other sections
342 @c Clear this up later -td
344 @subsection Background to nomenclature
346 Git is a system for tracking the changes made to source files by
347 a distributed set of editors. It is designed to work without a
348 master repository, but we have chosen to have a master respository
349 for LilyPond files. Editors hold local copies of the master
350 repository together with any changes they have made locally. Local
351 changes are held in a local @q{branch}, of which there may be
352 several, but these instructions assume you are using just one. The
353 files visible in the local repository always correspond to those
354 on the currently @q{checked out} local branch.
356 Files are edited on a local branch, and in that state the
357 changes are said to be @q{unstaged}. When editing is complete, the
358 changes are moved to being @q{staged for commit}, and finally the
359 changes are @q{committed} to the local branch. Once
360 committed, the changes are given a unique reference number called the
361 @q{Committish} which identifies them to Git. Such committed changes
362 can be sent to the master repository by @q{pushing} them (if you
363 have write permission) or by sending them by email to someone who
364 has, either complete or as a @q{diff} or @q{patch} (which send
365 just the differences from master).
367 @subsection Installing git
370 @uref{http://code.google.com/p/msysgit/downloads/list}.
371 (Note, not msysGit, which is for Git developers) and
374 Start Git by clicking on the desktop icon.
375 This will bring up a command line bash shell. This may be
376 unfamiliar to Windows users. If so, follow these
377 instructions carefully. Commands are entered at a $ prompt
378 and are terminated by keying a newline.
380 @subsection Initialising Git
382 Decide where you wish to place your local Git repository,
383 creating the folders in Windows as necessary. Here we
384 call the folder to contain the repository [path]/Git.
385 You will need to have space for around 150Mbytes.
387 In the git bash shell type
393 to position the shell at your new Git repository.
395 Note: if [path] contains folders with names containing
408 to initialize your Git repository.
410 Then type (all on one line; the shell will wrap automatically)
413 git remote add -f -t master origin git://git.sv.gnu.org/lilypond.git
416 to download the lilypond master files.
418 @warning{Be patient! Even on a broadband connection this can take
419 10 minutes or more. Wait for lots of [new tag] messages
422 We now need to generate a local copy of the downloaded files
423 in a new local branch. Your local branch needs to have a
424 name, here we call it @q{lily-local} - you may wish to make up
430 git checkout -b lily-local origin/master
433 to create the lily-local branch containing the local copies of the
434 master files. You will be advised your local branch has been set
435 up to track the remote branch.
437 Return to Windows Explorer and look in your Git repository. You
438 should see lots of folders. For example, the LilyPond documentation
439 can be found in Git/Documentation/user.
441 Terminate the Git bash shell by typing @code{exit}.
445 Almost all subsequent work will use the Git Graphical User
446 Interface, which avoids having to type command line
447 commands. To start Git GUI first start the Git bash shell by
448 clicking on the desktop icon, and type
455 The Git GUI will open in a new window. It contains four panels
456 and 7 pull-down menus. At this stage do not use any of the
457 commands under Branch, Commit, Merge or Remote. These will
460 The two panels on the left contain the names of files which
461 you are in the process of editing (Unstaged Changes), and
462 files you have finished editing and have staged ready for
463 committing (Staged Changes). At this stage these panels will
464 be empty as you have not yet made any changes to any file.
465 After a file has been edited and saved the top panel on the right
466 will display the differences between the edited file selected
467 in one of the panels on the left and the last version committed.
469 The final panel at bottom right is used to enter a descriptive
470 message about the change before committing it.
472 The Git GUI is terminated by entering CNTL-Q while it is the
473 active window or by clicking on the usual Windows close-window
476 @subsection Personalising your local git repository
478 Open the Git GUI, click on
484 and enter your name and email address in the
485 left-hand (Git Repository) panel. Leave everything
486 else unchanged and save it.
488 @subsection Checking out a branch
490 At this stage you have two branches in your local repository,
491 both identical. To see them click on
497 You should have one local branch called @w{lily-local} and one
498 tracking branch called @w{origin/master}. The latter is your
499 local copy of the @w{remote/origin/master} branch in the master
500 LilyPond repository. The @w{lily-local} branch is where you
501 will make your local changes.
503 When a particular branch is selected, i.e., checked out, the
504 files visible in your repository are changed to reflect the
505 state of the files on that branch.
507 @subsection Updating files from @w{remote/origin/master}
509 Before starting the editing of a file, ensure your local branches
510 contain the latest version in @w{remote/origin/master} by first
514 Remote -> Fetch from -> origin
520 This will place the latest version of every file, including all the
521 changes made by others,
522 into the @q{origin/master} branch of the tracking branches
523 in your git repository. You can see these files by checking
524 out this branch. This will not affect any files you have
525 modified in your local branch.
527 You then need to merge these fetched files into your local
528 branch by clicking on
535 and if necessary select the local branch into which the merge
538 Note that a merge cannot be completed if there are any local
539 uncommitted changes on the lily-local branch.
541 This will update all the files in that branch to reflect the
542 current state of the @w{origin/master} branch. If any of the
543 changes conflict with changes you have made yourself recently
544 you will be notified of the conflict (see below).
546 @subsection Editing files
548 First ensure your lily-local branch is checked out, then
549 simply edit the files in your local Git repository with your
550 favourite editor and save them back there. If any file contains
551 non-ASCII characters ensure you save it in UTF-8 format. Git will
552 detect any changes whenever you restart Git GUI and the file names
553 will then be listed in the Unstaged Changes panel.
554 Or you can click the Rescan button to refresh the panel
555 contents at any time. You may break off and resume at
558 The changes you have made may be displayed in diff form
559 in the top right-hand panel by clicking on the name in
562 When your editing is complete, move the files from being
563 Unstaged to Staged by clicking the document symbol to
564 the left of each name. If you change your mind it can
565 be moved back by clicking on the ticked box to the
568 Finally the changes you have made may be committed to
569 your lily-local branch by entering a brief message in
570 the Commit Message box and clicking the Commit button.
572 If you wish to amend your changes after a commit has been
573 made, the original version and the changes you made in that
574 commit may be recovered by selecting
577 Commit -> Amend Last Commit
581 or by checking the Amend Last Commit radio button at bottom left.
582 This will return the changes to the Staged state, so further
583 editing made be carried out within that commit. This must only be
584 done @emph{before} the changes have been Pushed or sent to your
585 mentor for Pushing - after that it is too late and corrections
586 have to be made as a separate commit.
589 @subsection Sending changes to remote/origin/master
591 If you do not have write access to @w{remote/origin/master} you will
592 need to send your changes by email to someone who does.
594 First you need to create a diff or patch file containing
595 your changes. To create this, the file must first be
596 committed. Then terminate the Git GUI. In the
597 git bash shell first cd to your Git repository with
603 if necessary, then produce the patch with
606 git format-patch origin
609 This will create a patch file for all the locally committed files
610 which differ from @w{origin/master}. The patch file can be found
611 in [path]/Git and will have a name formed from n and the commit
614 @subsection Resolving merge conflicts
616 As soon as you have committed a changed file your local
617 branch has diverged from @w{origin/master}, and will
618 remain diverged until your changes have been committed
619 in @w{remote/origin/master} and Fetched back into your
620 @w{origin/master}. Similarly, if a new commit has been made
621 to @w{remote/origin/master} by someone else and Fetched, your
622 lily-local branch is divergent. You can detect a divergent
623 branch by clicking on
626 Repository -> Visualise all branch history
629 This opens up a very useful new window called @q{gitk}.
630 Use this to browse all the commits made by others.
632 If the diagram at top left of the resulting window
633 does not show your branch's tag on the same node as
634 the @w{remote/origins/master} tag your branch has diverged from
635 @w{origin/master}. This is quite normal if files you have modified
636 yourself have not yet been Pushed to @w{remote/origin/master} and
637 Fetched, or if files modified and committed by others have been
638 Fetched since you last Merged @w{origin/master} into your lily-local
641 If a file being merged from @w{origin/master} differs from
642 one you have modified in a way that cannot be resolved
643 automatically by git, Merge will report a Conflict
644 which you must resolve by editing the file to create the
645 version you wish to keep.
647 This could happen if the person updating @w{remote/origin/master}
648 for you has added some changes of his own before
649 committing your changes to @w{remote/origin/master}, or if someone
650 else has changed the same file since you last
651 fetched the file from @w{remote/origin/master}.
653 Open the file in your editor and look for sections which
654 are delimited with ...
656 [to be completed when I next have a merge conflict to be
657 sure I give the right instructions -td]
660 @subsection Other actions
662 The instructions above describe the simplest way of using
663 git on Windows. Other git facilities which may usefully
664 supplement these include
668 @item Using multiple local branches (Create, Rename, Delete)
669 @item Resetting branches
670 @item Cherry-picking commits
671 @item Pushing commits to @w{remote/origin/master}
672 @item Using gitk to review history
676 Once familiarity with using git on Windows has been gained the
677 standard git manuals can be used to learn about these.