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,
47 mkdir lilypond; cd lilypond
49 git remote add -f -t master -m master origin git://git.sv.gnu.org/lilypond.git/
50 git checkout -b master origin/master
54 @node Website source code
55 @subsection Website source code
57 To get the website (including translations),
62 mkdir lilypond-web ; cd lilypond-web
64 git remote add -f -t web -m web origin git://git.sv.gnu.org/lilypond.git/
65 git checkout -b web origin/web
69 @node Documentation translations source code
70 @subsection Documentation translations source code
72 To translate the documentation (@emph{not} the website),
77 mkdir lilypond-translate; cd lilypond-translate
79 git remote add -f -t web -m web origin git://git.sv.gnu.org/lilypond.git/
80 git checkout -b web origin/web
85 @subsection Other branches
87 Most contributors will never need to touch the other branches. If
88 you wish to do so, you will need more familiarity with git.
93 This stores the Grand Unified Binary, our cross-platform building
94 tool. For more info, see @uref{http://lilypond.org/gub}. The git
98 http://github.com/janneke/gub
101 @item @code{dev/XYZ}:
102 These branches are for individual developers. They store code
103 which is not yet stable enough to be added to the @code{master}
106 @item @code{stable/XYZ}:
107 The branches are kept for archival reasons.
112 @node Other locations for git
113 @subsection Other locations for git
115 If you have difficulty connecting to most of the repositories
116 listed in earlier sections, try:
119 git://git.sv.gnu.org/lilypond.git
120 http://git.sv.gnu.org/r/lilypond.git
121 ssh://git.sv.gnu.org/srv/git/lilypond.git
124 @warning{The @code{git://} and @code{ssh://} URLs are intended for
127 @node Git user configuration
128 @subsection Git user configuration
130 To configure git to automatically use your name and email address
134 git config --global user.name "MYNAME"
135 git config --global user.email myemail@@example.net
139 @node Updating the source code
140 @section Updating the source code
143 * Importance of updating::
145 * Resolving conflicts::
150 @node Importance of updating
151 @subsection Importance of updating
153 In a large project like LilyPond, contributors sometimes edit the
154 same file at the same time. As long as everybody updates their
155 version of the file with the most recent changes (@qq{pull}ing),
156 there are generally no problems with this multiple-person editing.
157 However, serious problems can arise if you do not pull before
162 @subsection Updating command
164 Whenever you are asked to pull, it means you should update your
165 local copy of the repository with the changes made by others on
166 the remote @code{git.sv.gnu.org} repository:
173 @node Resolving conflicts
174 @subsection Resolving conflicts
176 Occasionally an update may result in conflicts -- this happens
177 when you and somebody else hae modified the same part of the same
178 file and git cannot figure out how to merge the two versions
179 together. When this happens, you must manually merge the two
187 @node Technical notes
188 @subsection Technical notes
190 TODO: I'm not going to bother with this section. -gp
192 Let's explain a bit of Git vocabulary. The @code{git pull origin}
193 command is just a shortcut for this command:
196 git pull git://git.sv.gnu.org/lilypond.git/ MY-BRANCH:origin/MY-BRANCH
199 A commit is a set of changes made to the sources; it also includes
200 the committish of the parent commit, the name and e-mail of the
201 author (the person who wrote the changes), the name and e-mail of
202 the committer (the person who brings these changes into the git
203 repository), and a commit message.
205 A committish is the SHA1 checksum of a commit, a number made of 40
206 hexadecimal digits, which acts as the internal unique identifier
207 for this commit. To refer to a particular revision, don't use
208 vague references like the (approximative) date, simply
209 copy'n'paste the committish.
211 A branch is a tree (in the mathematical or computer science sense)
212 of commits, and the topmost commit of this branch is called a
215 The "git fetch" command above has created a branch called
216 @code{origin/web} in your local Git repository. As this branch is
217 a copy of the remote branch web from git.sv.gnu.org LilyPond
218 repository, it is called a `remote branch', and is meant to track
219 the changes on the branch from git.sv.gnu.org: it will be updated
220 every time you run 'git pull' or 'git fetch' with this branch
221 reference as argument, e.g. by using .git/remotes/web remote file
222 when running 'git fetch web'.
224 The 'git checkout' command above has created a branch named 'web'. At
225 the beginning, this branch is identical to 'origin/web', but it will
226 differ as soon as you make changes, e.g. adding newly translated
227 pages. Whenever you pull, you merge the changes from origin/web and
228 your web branch since the last pulling. If you do not have push
229 (i.e. "write") access on git.sv.gnu.org, your web branch will always
230 differ from origin/web. In this case, remember that other people
231 working like you on the remote web branch of
232 git://git.sv.gnu.org/lilypond.git/ know nothing about your own web
233 branch: this means that whenever you use a committish or make a patch,
234 others expect you to take the lastest commit of origin/web branch as a
237 This README tries to explain most of Git commands needed for
238 translating the web site. However, you are invited to read
239 further documentation to make git more familiar to you; for
240 instance, take a look at @uref{http://git.or.cz/gitwiki/},
241 especially GitDocumentation and GitGlossary; a good alternative to
242 reading the wiki is reading the first two chapters of Git User's
244 @uref{http://www.kernel.org/pub/software/scm/git/docs/user-manual.html}
248 @node Sharing your changes
249 @section Sharing your changes
252 * Producing a patch::
253 * Committing directly::
257 @node Producing a patch
258 @subsection Producing a patch
260 Once you have finished editing your files, checked that your
261 changes meet the @ref{Code style} and/or @ref{Documentation
262 policy}, and checked that the entire thing compiles, you may
266 git-format-patch HEAD
269 Send an email to @email{lilypond-devel@@gnu.org} with the diff as
273 @node Committing directly
274 @subsection Committing directly
276 Most contributors do not have permission to commit directly. If
277 you do, edit @file{.git/config} to contain
280 FIXME? Is anything needed, or did the previous commands set it
284 You may then @code{git push}.
287 @node Other interesting Git commands
288 @section Other interesting Git commands
292 * Applying git patches::
299 The commands above don't only bring you the latest version of the
300 sources, but also the full history of revisions (revisons, also
301 called commits, are changes made to the sources), stored in the
302 .git directory. You can browse this history with
305 git log # only shows the logs (author, committish and commit message)
306 git log -p # also shows diffs
307 gitk # shows history graphically
310 @warning{The @code{gitk} command may require a separate @code{gitk} package,
311 available in the appropriate distribution's repositories.}
313 @node Applying git patches
314 @subsection Applying git patches
316 Well-formed git patches should be committed with
322 Patches created without @code{git-format-patch} should be
332 @section Git on Windows
334 @c Some of this may duplicate stuff in other sections
335 @c Clear this up later -td
337 @subsection Background to nomenclature
339 Git is a system for tracking the changes made to source files by
340 a distributed set of editors. It is designed to work without a
341 master repository, but we have chosen to have a master respository
342 for LilyPond files. Editors hold local copies of the master
343 repository together with any changes they have made locally. Local
344 changes are held in a local @q{branch}, of which there may be
345 several, but these instructions assume you are using just one. The
346 files visible in the local repository always correspond to those
347 on the currently @q{checked out} local branch.
349 Files are edited on a local branch, and in that state the
350 changes are said to be @q{unstaged}. When editing is complete, the
351 changes are moved to being @q{staged for commit}, and finally the
352 changes are @q{committed} to the local branch. Once
353 committed, the changes are given a unique reference number called the
354 @q{Committish} which identifies them to Git. Such committed changes
355 can be sent to the master repository by @q{pushing} them (if you
356 have write permission) or by sending them by email to someone who
357 has, either complete or as a @q{diff} or @q{patch} (which send
358 just the differences from master).
360 @subsection Installing git
363 @uref{http://code.google.com/p/msysgit/downloads/list}.
364 (Note, not msysGit, which is for Git developers) and
367 Start Git by clicking on the desktop icon.
368 This will bring up a command line bash shell. This may be
369 unfamiliar to Windows users. If so, follow these
370 instructions carefully. Commands are entered at a $ prompt
371 and are terminated by keying a newline.
373 @subsection Initialising Git
375 Decide where you wish to place your local Git repository,
376 creating the folders in Windows as necessary. Here we
377 call the folder to contain the repository [path]/Git.
378 You will need to have space for around 150Mbytes.
380 In the git bash shell type
386 to position the shell at your new Git repository.
388 Note: if [path] contains folders with names containing
401 to initialize your Git repository.
403 Then type (all on one line; the shell will wrap automatically)
406 git remote add -f -t master origin git://git.sv.gnu.org/lilypond.git
409 to download the lilypond master files.
411 @warning{Be patient! Even on a broadband connection this can take
412 10 minutes or more. Wait for lots of [new tag] messages
415 We now need to generate a local copy of the downloaded files
416 in a new local branch. Your local branch needs to have a
417 name, here we call it @q{lily-local} - you may wish to make up
423 git checkout -b lily-local origin/master
426 to create the lily-local branch containing the local copies of the
427 master files. You will be advised your local branch has been set
428 up to track the remote branch.
430 Return to Windows Explorer and look in your Git repository. You
431 should see lots of folders. For example, the LilyPond documentation
432 can be found in Git/Documentation/user.
434 Terminate the Git bash shell by typing @code{exit}.
438 Almost all subsequent work will use the Git Graphical User
439 Interface, which avoids having to type command line
440 commands. To start Git GUI first start the Git bash shell by
441 clicking on the desktop icon, and type
448 The Git GUI will open in a new window. It contains four panels
449 and 7 pull-down menus. At this stage do not use any of the
450 commands under Branch, Commit, Merge or Remote. These will
453 The two panels on the left contain the names of files which
454 you are in the process of editing (Unstaged Changes), and
455 files you have finished editing and have staged ready for
456 committing (Staged Changes). At this stage these panels will
457 be empty as you have not yet made any changes to any file.
458 After a file has been edited and saved the top panel on the right
459 will display the differences between the edited file selected
460 in one of the panels on the left and the last version committed.
462 The final panel at bottom right is used to enter a descriptive
463 message about the change before committing it.
465 The Git GUI is terminated by entering CNTL-Q while it is the
466 active window or by clicking on the usual Windows close-window
469 @subsection Personalising your local git repository
471 Open the Git GUI, click on
477 and enter your name and email address in the
478 left-hand (Git Repository) panel. Leave everything
479 else unchanged and save it.
481 @subsection Checking out a branch
483 At this stage you have two branches in your local repository,
484 both identical. To see them click on
490 You should have one local branch called @w{lily-local} and one
491 tracking branch called @w{origin/master}. The latter is your
492 local copy of the @w{remote/origin/master} branch in the master
493 LilyPond repository. The @w{lily-local} branch is where you
494 will make your local changes.
496 When a particular branch is selected, i.e., checked out, the
497 files visible in your repository are changed to reflect the
498 state of the files on that branch.
500 @subsection Updating files from @w{remote/origin/master}
502 Before starting the editing of a file, ensure your local branches
503 contain the latest version in @w{remote/origin/master} by first
507 Remote -> Fetch from -> origin
513 This will place the latest version of every file, including all the
514 changes made by others,
515 into the @q{origin/master} branch of the tracking branches
516 in your git repository. You can see these files by checking
517 out this branch. This will not affect any files you have
518 modified in your local branch.
520 You then need to merge these fetched files into your local
521 branch by clicking on
528 and if necessary select the local branch into which the merge
531 Note that a merge cannot be completed if there are any local
532 uncommitted changes on the lily-local branch.
534 This will update all the files in that branch to reflect the
535 current state of the @w{origin/master} branch. If any of the
536 changes conflict with changes you have made yourself recently
537 you will be notified of the conflict (see below).
539 @subsection Editing files
541 First ensure your lily-local branch is checked out, then
542 simply edit the files in your local Git repository with your
543 favourite editor and save them back there. If any file contains
544 non-ASCII characters ensure you save it in UTF-8 format. Git will
545 detect any changes whenever you restart Git GUI and the file names
546 will then be listed in the Unstaged Changes panel.
547 Or you can click the Rescan button to refresh the panel
548 contents at any time. You may break off and resume at
551 The changes you have made may be displayed in diff form
552 in the top right-hand panel by clicking on the name in
555 When your editing is complete, move the files from being
556 Unstaged to Staged by clicking the document symbol to
557 the left of each name. If you change your mind it can
558 be moved back by clicking on the ticked box to the
561 Finally the changes you have made may be committed to
562 your lily-local branch by entering a brief message in
563 the Commit Message box and clicking the Commit button.
565 If you wish to amend your changes after a commit has been
566 made, the original version and the changes you made in that
567 commit may be recovered by selecting
570 Commit -> Amend Last Commit
574 or by checking the Amend Last Commit radio button at bottom left.
575 This will return the changes to the Staged state, so further
576 editing made be carried out within that commit. This must only be
577 done @emph{before} the changes have been Pushed or sent to your
578 mentor for Pushing - after that it is too late and corrections
579 have to be made as a separate commit.
582 @subsection Sending changes to remote/origin/master
584 If you do not have write access to @w{remote/origin/master} you will
585 need to send your changes by email to someone who does.
587 First you need to create a diff or patch file containing
588 your changes. To create this, the file must first be
589 committed. Then terminate the Git GUI. In the
590 git bash shell first cd to your Git repository with
596 if necessary, then produce the patch with
602 where n an integer, normally 1. This will create a
603 patch file for all the locally committed files which differ
604 from @w{origin/master}. The patch file can be found in
605 [path]/Git and will have a name formed from n and the
608 @subsection Resolving merge conflicts
610 As soon as you have committed a changed file your local
611 branch has diverged from @w{origin/master}, and will
612 remain diverged until your changes have been committed
613 in @w{remote/origin/master} and Fetched back into your
614 @w{origin/master}. Similarly, if a new commit has been made
615 to @w{remote/origin/master} by someone else and Fetched, your
616 lily-local branch is divergent. You can detect a divergent
617 branch by clicking on
620 Repository -> Visualise all branch history
623 This opens up a very useful new window called @q{gitk}.
624 Use this to browse all the commits made by others.
626 If the diagram at top left of the resulting window
627 does not show your branch's tag on the same node as
628 the @w{remote/origins/master} tag your branch has diverged from
629 @w{origin/master}. This is quite normal if files you have modified
630 yourself have not yet been Pushed to @w{remote/origin/master} and
631 Fetched, or if files modified and committed by others have been
632 Fetched since you last Merged @w{origin/master} into your lily-local
635 If a file being merged from @w{origin/master} differs from
636 one you have modified in a way that cannot be resolved
637 automatically by git, Merge will report a Conflict
638 which you must resolve by editing the file to create the
639 version you wish to keep.
641 This could happen if the person updating @w{remote/origin/master}
642 for you has added some changes of his own before
643 committing your changes to @w{remote/origin/master}, or if someone
644 else has changed the same file since you last
645 fetched the file from @w{remote/origin/master}.
647 Open the file in your editor and look for sections which
648 are delimited with ...
650 [to be completed when I next have a merge conflict to be
651 sure I give the right instructions -td]
654 @subsection Other actions
656 The instructions above describe the simplest way of using
657 git on Windows. Other git facilities which may usefully
658 supplement these include
662 @item Using multiple local branches (Create, Rename, Delete)
663 @item Resetting branches
664 @item Cherry-picking commits
665 @item Pushing commits to @w{remote/origin/master}
666 @item Using gitk to review history
670 Once familiarity with using git on Windows has been gained the
671 standard git manuals can be used to learn about these.