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 web origin/web
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 hae 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 "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 `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 'git pull' or 'git fetch' with this branch
220 reference as argument, e.g. by using .git/remotes/web remote file
221 when running 'git fetch web'.
223 The 'git checkout' command above has created a branch named 'web'. At
224 the beginning, this branch is identical to '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. "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 lastest 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} to contain
279 FIXME? Is anything needed, or did the previous commands set it
283 You may then @code{git push}.
286 @node Other interesting Git commands
287 @section Other interesting Git commands
291 * Applying git patches::
298 The commands above don't only bring you the latest version of the
299 sources, but also the full history of revisions (revisons, also
300 called commits, are changes made to the sources), stored in the
301 .git directory. You can browse this history with
304 git log # only shows the logs (author, committish and commit message)
305 git log -p # also shows diffs
306 gitk # shows history graphically
309 @warning{The @code{gitk} command may require a separate @code{gitk} package,
310 available in the appropriate distribution's repositories.}
312 @node Applying git patches
313 @subsection Applying git patches
315 Well-formed git patches should be committed with
321 Patches created without @code{git format-patch} should be
331 @section Git on Windows
333 @c Some of this may duplicate stuff in other sections
334 @c Clear this up later -td
336 @subsection Background to nomenclature
338 Git is a system for tracking the changes made to source files by
339 a distributed set of editors. It is designed to work without a
340 master repository, but we have chosen to have a master respository
341 for LilyPond files. Editors hold local copies of the master
342 repository together with any changes they have made locally. Local
343 changes are held in a local @q{branch}, of which there may be
344 several, but these instructions assume you are using just one. The
345 files visible in the local repository always correspond to those
346 on the currently @q{checked out} local branch.
348 Files are edited on a local branch, and in that state the
349 changes are said to be @q{unstaged}. When editing is complete, the
350 changes are moved to being @q{staged for commit}, and finally the
351 changes are @q{committed} to the local branch. Once
352 committed, the changes are given a unique reference number called the
353 @q{Committish} which identifies them to Git. Such committed changes
354 can be sent to the master repository by @q{pushing} them (if you
355 have write permission) or by sending them by email to someone who
356 has, either complete or as a @q{diff} or @q{patch} (which send
357 just the differences from master).
359 @subsection Installing git
362 @uref{http://code.google.com/p/msysgit/downloads/list}.
363 (Note, not msysGit, which is for Git developers) and
366 Start Git by clicking on the desktop icon.
367 This will bring up a command line bash shell. This may be
368 unfamiliar to Windows users. If so, follow these
369 instructions carefully. Commands are entered at a $ prompt
370 and are terminated by keying a newline.
372 @subsection Initialising Git
374 Decide where you wish to place your local Git repository,
375 creating the folders in Windows as necessary. Here we
376 call the folder to contain the repository [path]/Git.
377 You will need to have space for around 150Mbytes.
379 In the git bash shell type
385 to position the shell at your new Git repository.
387 Note: if [path] contains folders with names containing
400 to initialize your Git repository.
402 Then type (all on one line; the shell will wrap automatically)
405 git remote add -f -t master origin git://git.sv.gnu.org/lilypond.git
408 to download the lilypond master files.
410 @warning{Be patient! Even on a broadband connection this can take
411 10 minutes or more. Wait for lots of [new tag] messages
414 We now need to generate a local copy of the downloaded files
415 in a new local branch. Your local branch needs to have a
416 name, here we call it @q{lily-local} - you may wish to make up
422 git checkout -b lily-local origin/master
425 to create the lily-local branch containing the local copies of the
426 master files. You will be advised your local branch has been set
427 up to track the remote branch.
429 Return to Windows Explorer and look in your Git repository. You
430 should see lots of folders. For example, the LilyPond documentation
431 can be found in Git/Documentation/user.
433 Terminate the Git bash shell by typing @code{exit}.
437 Almost all subsequent work will use the Git Graphical User
438 Interface, which avoids having to type command line
439 commands. To start Git GUI first start the Git bash shell by
440 clicking on the desktop icon, and type
447 The Git GUI will open in a new window. It contains four panels
448 and 7 pull-down menus. At this stage do not use any of the
449 commands under Branch, Commit, Merge or Remote. These will
452 The two panels on the left contain the names of files which
453 you are in the process of editing (Unstaged Changes), and
454 files you have finished editing and have staged ready for
455 committing (Staged Changes). At this stage these panels will
456 be empty as you have not yet made any changes to any file.
457 After a file has been edited and saved the top panel on the right
458 will display the differences between the edited file selected
459 in one of the panels on the left and the last version committed.
461 The final panel at bottom right is used to enter a descriptive
462 message about the change before committing it.
464 The Git GUI is terminated by entering CNTL-Q while it is the
465 active window or by clicking on the usual Windows close-window
468 @subsection Personalising your local git repository
470 Open the Git GUI, click on
476 and enter your name and email address in the
477 left-hand (Git Repository) panel. Leave everything
478 else unchanged and save it.
480 @subsection Checking out a branch
482 At this stage you have two branches in your local repository,
483 both identical. To see them click on
489 You should have one local branch called @w{lily-local} and one
490 tracking branch called @w{origin/master}. The latter is your
491 local copy of the @w{remote/origin/master} branch in the master
492 LilyPond repository. The @w{lily-local} branch is where you
493 will make your local changes.
495 When a particular branch is selected, i.e., checked out, the
496 files visible in your repository are changed to reflect the
497 state of the files on that branch.
499 @subsection Updating files from @w{remote/origin/master}
501 Before starting the editing of a file, ensure your local branches
502 contain the latest version in @w{remote/origin/master} by first
506 Remote -> Fetch from -> origin
512 This will place the latest version of every file, including all the
513 changes made by others,
514 into the @q{origin/master} branch of the tracking branches
515 in your git repository. You can see these files by checking
516 out this branch. This will not affect any files you have
517 modified in your local branch.
519 You then need to merge these fetched files into your local
520 branch by clicking on
527 and if necessary select the local branch into which the merge
530 Note that a merge cannot be completed if there are any local
531 uncommitted changes on the lily-local branch.
533 This will update all the files in that branch to reflect the
534 current state of the @w{origin/master} branch. If any of the
535 changes conflict with changes you have made yourself recently
536 you will be notified of the conflict (see below).
538 @subsection Editing files
540 First ensure your lily-local branch is checked out, then
541 simply edit the files in your local Git repository with your
542 favourite editor and save them back there. If any file contains
543 non-ASCII characters ensure you save it in UTF-8 format. Git will
544 detect any changes whenever you restart Git GUI and the file names
545 will then be listed in the Unstaged Changes panel.
546 Or you can click the Rescan button to refresh the panel
547 contents at any time. You may break off and resume at
550 The changes you have made may be displayed in diff form
551 in the top right-hand panel by clicking on the name in
554 When your editing is complete, move the files from being
555 Unstaged to Staged by clicking the document symbol to
556 the left of each name. If you change your mind it can
557 be moved back by clicking on the ticked box to the
560 Finally the changes you have made may be committed to
561 your lily-local branch by entering a brief message in
562 the Commit Message box and clicking the Commit button.
564 If you wish to amend your changes after a commit has been
565 made, the original version and the changes you made in that
566 commit may be recovered by selecting
569 Commit -> Amend Last Commit
573 or by checking the Amend Last Commit radio button at bottom left.
574 This will return the changes to the Staged state, so further
575 editing made be carried out within that commit. This must only be
576 done @emph{before} the changes have been Pushed or sent to your
577 mentor for Pushing - after that it is too late and corrections
578 have to be made as a separate commit.
581 @subsection Sending changes to remote/origin/master
583 If you do not have write access to @w{remote/origin/master} you will
584 need to send your changes by email to someone who does.
586 First you need to create a diff or patch file containing
587 your changes. To create this, the file must first be
588 committed. Then terminate the Git GUI. In the
589 git bash shell first cd to your Git repository with
595 if necessary, then produce the patch with
598 git format-patch origin
601 This will create a patch file for all the locally committed files
602 which differ from @w{origin/master}. The patch file can be found
603 in [path]/Git and will have a name formed from n and the commit
606 @subsection Resolving merge conflicts
608 As soon as you have committed a changed file your local
609 branch has diverged from @w{origin/master}, and will
610 remain diverged until your changes have been committed
611 in @w{remote/origin/master} and Fetched back into your
612 @w{origin/master}. Similarly, if a new commit has been made
613 to @w{remote/origin/master} by someone else and Fetched, your
614 lily-local branch is divergent. You can detect a divergent
615 branch by clicking on
618 Repository -> Visualise all branch history
621 This opens up a very useful new window called @q{gitk}.
622 Use this to browse all the commits made by others.
624 If the diagram at top left of the resulting window
625 does not show your branch's tag on the same node as
626 the @w{remote/origins/master} tag your branch has diverged from
627 @w{origin/master}. This is quite normal if files you have modified
628 yourself have not yet been Pushed to @w{remote/origin/master} and
629 Fetched, or if files modified and committed by others have been
630 Fetched since you last Merged @w{origin/master} into your lily-local
633 If a file being merged from @w{origin/master} differs from
634 one you have modified in a way that cannot be resolved
635 automatically by git, Merge will report a Conflict
636 which you must resolve by editing the file to create the
637 version you wish to keep.
639 This could happen if the person updating @w{remote/origin/master}
640 for you has added some changes of his own before
641 committing your changes to @w{remote/origin/master}, or if someone
642 else has changed the same file since you last
643 fetched the file from @w{remote/origin/master}.
645 Open the file in your editor and look for sections which
646 are delimited with ...
648 [to be completed when I next have a merge conflict to be
649 sure I give the right instructions -td]
652 @subsection Other actions
654 The instructions above describe the simplest way of using
655 git on Windows. Other git facilities which may usefully
656 supplement these include
660 @item Using multiple local branches (Create, Rename, Delete)
661 @item Resetting branches
662 @item Cherry-picking commits
663 @item Pushing commits to @w{remote/origin/master}
664 @item Using gitk to review history
668 Once familiarity with using git on Windows has been gained the
669 standard git manuals can be used to learn about these.