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::
10 * Applying git patches::
15 @node Getting the source code
16 @section Getting the source code
18 The source code is kept in a git respository.
20 @warning{These instructions assume that you are using the
21 command-line version of git 1.5 or higher.}
26 * Website source code::
27 * Documentation translations source code::
29 * Other locations for git::
30 * Git user configuration::
33 @node Main source code
34 @subsection Main source code
36 To get the main source code and documentation,
41 mkdir lilypond; cd lilypond
43 git remote add -f -t master -m master origin git://git.sv.gnu.org/lilypond.git/
44 git checkout -b master origin/master
48 @node Website source code
49 @subsection Website source code
51 To get the website (including translations),
54 mkdir lilyweb ; cd lilyweb
56 git remote add -f -t web -m web origin git://git.sv.gnu.org/lilypond.git/
57 git checkout -b web origin/web
61 @node Documentation translations source code
62 @subsection Documentation translations source code
64 To translate the documentation (@emph{not} the website),
69 mkdir lilytranslate ; cd lilytranslate
71 git remote add -f -t web -m web origin git://git.sv.gnu.org/lilypond.git/
72 git checkout -b web origin/web
77 @subsection Other branches
79 Most contributors will never need to touch the other branches. If
80 you wish to do so, you will need more familiarity with git.
85 This stores the Grand Unified Binary, our cross-platform building
89 FIXME: insert new gub addy
93 These branches are for individual developers. They store code
94 which is not yet stable enough to be added to the @code{master}
97 @item @code{stable/XYZ}:
98 The branches are kept for archival reasons.
103 @node Other locations for git
104 @subsection Other locations for git
106 If you have difficulty connecting to most of the repositories
107 listed in earlier sections, try:
110 git://git.sv.gnu.org/lilypond.git
111 http://git.sv.gnu.org/r/lilypond.git
112 ssh://git.sv.gnu.org/srv/git/lilypond.git
116 @node Git user configuration
117 @subsection Git user configuration
119 To configure git to automatically use your name and email address
123 git config --global user.name "MYNAME"
124 git config --global user.email myemail@@example.net
128 @node Updating the source code
129 @section Updating the source code
132 * Importance of updating::
134 * Resolving conflicts::
138 @node Importance of updating
139 @subsection Importance of updating
141 In a large project like LilyPond, contributors sometimes edit the
142 same file at the same time. As long as everybody updates their
143 version of the file with the most recent changes (@qq{pull}ing),
144 there are generally no problems with this multiple-person editing.
145 However, serious problems can arise if you do not pull before
149 @subsection Updating command
151 Whenever you are asked to pull, it means you should update your
152 local copy of the repository with the changes made by others on
153 the remote @code{git.sv.gnu.org} repository:
159 @node Resolving conflicts
160 @subsection Resolving conflicts
162 Occasionally an update may result in conflicts -- this happens
163 when you and somebody else hae modified the same part of the same
164 file and git cannot figure out how to merge the two versions
165 together. When this happens, you must manually merge the two
173 @node Technical notes
174 @subsection Technical notes
176 Let's explain a bit of Git vocabulary. The @code{git pull
177 origin} command is just a shortcut for this command:
180 git pull git://git.sv.gnu.org/lilypond.git/ MY-BRANCH:origin/MY-BRANCH
183 A commit is a set of changes made to the sources; it also includes the
184 committish of the parent commit, the name and e-mail of the author
185 (the person who wrote the changes), the name and e-mail of the
186 committer (the person who brings these changes into the git
187 repository), and a commit message.
189 A committish is the SHA1 checksum of a commit, a number made of 40
190 hexadecimal digits, which acts as the internal unique identifier for
191 this commit. To refer to a particular revision, don't use vague
192 references like the (approximative) date, simply copy'n'paste the
195 A branch is a tree (in the mathematical or computer science sense) of
196 commits, and the topmost commit of this branch is called a head.
198 The "git fetch" command above has created a branch called origin/web
199 in your local Git repository. As this branch is a copy of the remote
200 branch web from git.sv.gnu.org LilyPond repository, it is
201 called a `remote branch', and is meant to track the changes on the
202 branch from git.sv.gnu.org: it will be updated every time you run 'git
203 pull' or 'git fetch' with this branch reference as argument, e.g.
204 by using .git/remotes/web remote file when running 'git fetch web'.
206 The 'git checkout' command above has created a branch named 'web'. At
207 the beginning, this branch is identical to 'origin/web', but it will
208 differ as soon as you make changes, e.g. adding newly translated
209 pages. Whenever you pull, you merge the changes from origin/web and
210 your web branch since the last pulling. If you do not have push
211 (i.e. "write") access on git.sv.gnu.org, your web branch will always
212 differ from origin/web. In this case, remember that other people
213 working like you on the remote web branch of
214 git://git.sv.gnu.org/lilypond.git/ know nothing about your own web
215 branch: this means that whenever you use a committish or make a patch,
216 others expect you to take the lastest commit of origin/web branch as a
219 This README tries to explain most of Git commands needed for
220 translating the web site. However, you are invited to read
221 further documentation to make git more familiar to you; for
222 instance, take a look at @uref{http://git.or.cz/gitwiki/},
223 especially GitDocumentation and GitGlossary; a good alternative to
224 reading the wiki is reading the first two chapters of Git User's
226 @uref{http://www.kernel.org/pub/software/scm/git/docs/user-manual.html}
231 @node Sharing your changes
232 @section Sharing your changes
236 * Producing a patch::
237 * Committing directly::
240 @node Producing a patch
241 @subsection Producing a patch
243 Once you have finished editing your files, checked that your
244 changes meet the @ref{Code style} and/or @ref{Documentation
245 policy}, and checked that the entire thing compiles, you may
249 git-format-patch HEAD
252 Send an email to @email{lilypond-devel@@gnu.org} with the diff as
256 @node Committing directly
257 @subsection Committing directly
259 Most contributors do not have permission to commit directly. If
260 you do, edit @file{.git/config} to contain
266 You may then @code{git push}.
269 @node Other interesting Git commands
270 @section Other interesting Git commands
272 The commands above don't only bring you the latest version of the
273 sources, but also the full history of revisions (revisons, also
274 called commits, are changes made to the sources), stored in the
275 .git directory. You can browse this history with
278 git log # only shows the logs (author, committish and commit message)
279 git log -p # also shows diffs
280 gitk # shows history graphically
284 @node Applying git patches
285 @section Applying git patches
287 Well-formed git patches should be committed with
293 Patches created without @code{git-format-patch} should be
303 @section Git on Windows
305 @c Some of this may duplicate stuff in other sections
306 @c Clear this up later -td
308 @subsection Background to nomenclature
310 Git is a system for tracking the changes made to source files by
311 a distributed set of editors. It is designed to work without a
312 master repository, but we have chosen to have a master respository
313 for LilyPond files. Editors hold local copies of the master
314 repository together with any changes they have made locally. Local
315 changes are held in a local @q{branch}, of which there may be
316 several. The files in the local repository always correspond to
317 those on the currently @q{checked out} local branch.
319 Files are edited on a local branch, and in that state the
320 changes are said to be @q{unstaged}. When editing is complete, the
321 changes are moved to being @q{staged for commit}, and finally the
322 changes are @q{committed} to the local branch. Once
323 committed, the changes are given a unique reference number called the
324 @q{Committish} which identifies them to Git. Such committed changes
325 can be sent to the master repository by @q{pushing} them (if you
326 have write permission) or by sending them by email to someone who
327 has, either complete or as a @q{diff} or @q{patch} (which send
328 just the differences from master).
330 @subsection Installing git
333 @uref{http://code.google.com/p/msysgit/downloads/list}.
334 (Note, not msysGit, which is for Git developers) and
335 install. Start Git by clicking on the desktop icon.
336 This will bring up a command line bash shell. This will be
337 unfamiliar to most Windows users, so follow these
338 instructions carefully. Commands are entered at a $ prompt
339 and are terminated by keying a newline.
341 @subsection Initialising Git
343 Decide where you wish to place your local Git repository,
344 creating the folders in Windows as necessary. Here we
345 call the folder to contain the repository [path]/Git.
346 You will need to have space for around 150Mbytes.
348 In the git bash shell type
354 to position the shell at your new Git repository.
356 Note: if [path] contains folders with names containing
369 to initialize your Git repository.
371 Then type (all on one line; the shell will wrap automatically)
374 git remote add -f -t master origin git://git.sv.gnu.org/lilypond.git
377 to download the lilypond master files.
379 @warning{Be patient! Even on a broadband connection this can take
380 10 minutes or more. Wait for lots of [new tag] messages
383 We now need to generate a local copy of the downloaded files
384 in a new local branch. Your local branch needs to have a
385 name, here we call it @q{lily-local} - make up your own.
389 git checkout -b lily-local origin/master
392 to create the lily-local branch containing the local copies of the
393 master files. You will be advised your local branch has been set
394 up to track the remote branch.
396 Return to Windows and look in your Git repository. You
397 should see lots of folders. The LilyPond documentation
398 can be found in Git/Documentation/user.
400 Terminate the Git bash shell with the exit command.
404 Almost all subsequent work will use the Git Graphical User
405 Interface, which avoids having to type command line
406 commands. To start Git GUI first start the Git bash shell by
407 clicking on the desktop icon, and type
414 The Git GUI will open in a new window. It contains four panels
415 and 7 pull-down menus. At this stage do not use any of the
416 commands under Branch, Commit, Merge or Remote. These will
419 The two panels on the left contain the names of files which
420 you are in the process of editing (Unstaged Changes),and
421 files you have finished editing and have staged ready for
422 committing (Staged Changes). At this stage these panels will
423 be empty as your local branch is the same as the master branch.
424 After a file has been edited and saved the top panel on the right
425 will display the differences between the edited file selected
426 from one of the left panels and the one on master. The
427 final panel at bottom right is used to enter a descriptive
428 message about the change before committing a file.
430 The Git GUI is terminated by entering CNTL-Q while it is the
431 active window or by clicking on the usual Windows close-window
434 @subsection Personalising your local git repository
436 Open the Git GUI, click on
442 and enter your name and email address in the
443 left-hand (Git Repository) panel. Leave everything
444 else unchanged and save it.
446 @subsection Checking out a branch
448 At this stage you have two branches in your local repository,
449 both identical. To see them click on
455 You should have one local branch called lily-local and one
456 tracking branch called origin/master.
458 When a particular branch is selected, i.e., checked out, the
459 files visible in your repository are changed to reflect the
460 changes made on that branch.
462 @subsection Updating files from master
464 Before starting the editing of a file ensure you have the
465 latest copy from master by first clicking
468 Remote -> Fetch from -> origin
473 This will place details of all the changes made by others
474 into the @q{origin/master} branch of the tracking branches
475 in your git repository. You can see these files by checking
476 out this branch. This will not affect any files
477 you have modified in any of your local branches.
479 To merge the changed files into your local branch click on
485 and if necessary select the local branch into which the merge
488 This will update all the files in that branch to reflect the
489 currect state of the origin/master branch. If any of the changes
490 conflict with changes you have made yourself recently
491 you will be notified of the conflict (see below).
493 @subsection Editing files
495 Simply edit the files in your local Git repository with
496 your favourite editor and save them back there. If any file contains
497 non-ASCII characters ensure you save it in UTF8 format. Git will
498 detect any changes whenever you restart Git GUI
499 and the file names will then be listed in the Unstaged Changes panel.
500 Or you can click the Rescan button to refresh the panel
501 contents at any time. You may break off and resume at
504 The changes you have made may be displayed in diff form
505 in the top right-hand panel by clicking on the name in
508 When your editing is complete, move the files from being
509 Unstaged to Staged by clicking the document symbol to
510 the left of each name. If you change your mind it can
511 be moved back by clicking on the ticked box to the
514 If you wish to cancel your changes the original version
515 may be recovered at any time before a commit is made
516 by selecting Commit -> Revert changes. This will even
517 recover a deleted file.
519 Finally the changes you have made may be committed to
520 your local branch by entering a brief message in
521 the Commit Message box and clicking the Commit button.
523 @subsection Sending changes to origin/master
525 If you do not have write access to master you will
526 need to send your changes by email to someone who does.
528 First you need to create a diff or patch file containing
529 your changes. To create this, the file must first be
530 committed. Then terminate the Git GUI. In the
531 git bash shell first cd to your Git repository with
537 if necessary, then produce the patch with
543 where n an integer, normally 1. This will create a
544 patch file for all the locally committed files which
545 differ from master. The patch file can be found in
546 [path]/Git and will have a name formed from n and the
549 @subsection Resolving merge conflicts
551 As soon as you have committed a changed file your
552 local branch has diverged from master, and will
553 remain diverged until your changes have been committed
554 in master. Similarly, if a new commit has been made
555 to master by someone else, your branch is divergent.
556 You can detect a divergent branch my clicking on
559 Repository -> Visualise all branch history
562 This opens up a very useful new window called @q{gitk}.
564 If the diagram at top left of the resulting window
565 does not show your branch on a single node at the
566 top your branch has diverged from master. This is
567 quite normal if files you have modified yourself
568 have not yet been committed to master, or if files
569 have been modified and committed by others since
572 If a file being merged from master differs from
573 one you have modified in a way that cannot be resolved
574 automatically by git, Merge will report a Conflict
575 which you must resolve by editing the file to create the
576 version you wish to keep.
578 This could happen if the person updating master
579 for you has added some changes of his own before
580 committing your changes to master, or if someone
581 else has updated the same parent file as you at
584 Open the file in your editor and look for sections which
587 [to be completed when I next have a merge conflict to be
588 sure I give the right instructions -td]