1 @c -*- coding: us-ascii; mode: texinfo; -*-
2 @node Starting with git
3 @chapter Starting with git
5 To complete or present in another form the introduction to Git usage
6 in this chapter, it may be a good idea to look for Git documentation
7 at @uref{http://git-scm.com/documentation},
10 * Getting the source code::
11 * Updating the source code::
12 * Sharing your changes::
13 * Advanced git stuff::
15 * Development inside VirtualBox (compiling on Windows)::
19 @node Getting the source code
20 @section Getting the source code
25 * Website source code::
26 * Documentation translations source code::
28 * Other locations for git::
29 * Git user configuration::
32 @node Git introduction
33 @subsection Git introduction
35 The source code is kept in a Git respository. This allows us to
36 track changes to files, and for multiple people to work on the
37 same set of files efficiently.
39 @warning{These instructions assume that you are using the
40 command-line version of Git 1.5 or higher. Windows users should
41 skip to @ref{Git on Windows}.}
44 @node Main source code
45 @subsection Main source code
47 To get the main source code and documentation,
49 @c WARNING: when updating the commands below, please
50 @c update the other flavors in the two next nodes
51 @c and in Introduction to Git concepts
53 mkdir lilypond; cd lilypond
55 git remote add -f -t master -m master origin git://git.sv.gnu.org/lilypond.git/
56 git checkout -b master origin/master
60 @node Website source code
61 @subsection Website source code
63 To get the website (including translations),
66 mkdir lilypond-web ; cd lilypond-web
68 git remote add -f -t web -m web origin git://git.sv.gnu.org/lilypond.git/
69 git checkout -b web origin/web
73 @node Documentation translations source code
74 @subsection Documentation translations source code
76 To translate the documentation (@emph{not} the website),
79 mkdir lilypond-translation; cd lilypond-translation
81 git remote add -f -t lilypond/translation -m lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
82 git checkout -b lilypond/translation origin/lilypond/translation
87 @subsection Other branches
89 Most contributors will never need to touch the other branches. If
90 you wish to do so, you will need more familiarity with git.
95 This stores the Grand Unified Binary, our cross-platform building
97 @c TODO: merge the gub stuff with this CG.
98 For more info, see @uref{http://lilypond.org/gub}. The git
102 http://github.com/janneke/gub
105 @item @code{dev/XYZ}:
106 These branches are for individual developers. They store code
107 which is not yet stable enough to be added to the @code{master}
110 @item @code{stable/XYZ}:
111 The branches are kept for archival reasons.
116 @node Other locations for git
117 @subsection Other locations for git
119 If you have difficulty connecting to most of the repositories
120 listed in earlier sections, try:
123 http://git.sv.gnu.org/r/lilypond.git
124 git://git.sv.gnu.org/lilypond.git
125 ssh://git.sv.gnu.org/srv/git/lilypond.git
128 Using HTTP protocol is slowest, so it is not recommended unless both
129 SSH and Git protocols fail, which happens e.g. if you connect to
130 internet through a router that filters out Git and/or SSH connections.
133 @node Git user configuration
134 @subsection Git user configuration
136 To configure git to automatically use your name and email address
137 for commits and patches,
140 git config --global user.name "MYNAME"
141 git config --global user.email MYEMAIL@@EXAMPLE.NET
145 @node Updating the source code
146 @section Updating the source code
149 * Importance of updating::
151 * Resolving conflicts::
155 @node Importance of updating
156 @subsection Importance of updating
158 In a large project like LilyPond, contributors sometimes edit the same
159 file at the same time. As long as everybody updates their version of
160 the file with the most recent changes (@emph{pulling}), there are
161 generally no problems with this multiple-person editing. However,
162 boring problems can arise if you do not pull before attempting commit,
163 e.g. you may encounter a conflict; in this case, see @ref{Resolving
168 @subsection Updating command
170 Whenever you are asked to pull, it means you should update your
171 local copy of the repository with the changes made by others on
172 the remote @code{git.sv.gnu.org} repository:
179 @node Resolving conflicts
180 @subsection Resolving conflicts
182 Occasionally an update may result in conflicts -- this happens
183 when you and somebody else have modified the same part of the same
184 file and git cannot figure out how to merge the two versions
185 together. When this happens, you must manually merge the two
188 If you need some documentation to understand and resolve conflicts,
189 see paragraphs @emph{How conflicts are presented} and @emph{How to
190 resolve conflicts} in @command{git merge} man page.
193 @node Sharing your changes
194 @section Sharing your changes
197 * Producing a patch::
198 * Committing directly::
202 @node Producing a patch
203 @subsection Producing a patch
205 Once you have finished editing your files, checked that your changes
206 meet the @ref{Code style}, and/or @ref{Documentation policy}, properly
207 set up your name and email in @ref{Git user configuration}, and
208 checked that the entire thing compiles, you may:
212 git format-patch origin
215 The commit should include a brief message describing the change.
216 This consists of a one-line summary describing the change, and
217 if necessary a blank line followed by several lines giving the
221 Did household chores.
223 I hung up the wet laundry and then washed the car. I also
224 vacuumed the floors, rinsed the dirty dishes, fed the cat, and
225 recalibrated the temporal flux machine.
228 If the change is to the documentation only then the one-line
229 summary should be prefixed with @qq{Docs: }.
231 If you added a file to the source code, you must add it to git
239 (and possibly modify the @file{GNUmakefile})
241 These commands will produce one or more files named
242 @file{0001-xyz}, @file{0002-abc}, etc. in the top directory of the
243 git tree. Send an email to @email{lilypond-devel@@gnu.org} with
244 these files attached, and a developer will review and apply the
245 patches to the main repository.
248 @node Committing directly
249 @subsection Committing directly
251 Most contributors do not have permission to commit directly. If you
252 do, make sure you have set up your name and email in @ref{Git user
253 configuration}, then edit @file{.git/config}: change the line
256 url = git://git.sv.gnu.org/lilypond.git/
263 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
267 where @var{user} is your login name on Savannah.
269 If you have not already done so, you should generate and upload a
270 SSH key: open @uref{https://savannah.gnu.org/my/} in your browser,
271 go to @q{Account Configuration}, then to something like
272 @q{Edit SSH Keys}, and follow the instructions on that page.
280 Note that recent versions of Git (Git 1.6.3 or later) will issue a
281 big warning if the above command is used. The simplest solution
282 is to add a new section to @file{.git/config} that looks like
291 Then @code{git push origin} will work as before. For more
292 details, consult the @code{git push} man page.
295 @node Advanced git stuff
296 @section Advanced git stuff
298 @warning{This section is not necessary for normal contributors;
299 these commands are presented for information for people interested
300 in learning more about git.}
303 It is possible to work with several branches on the same local Git
304 repository; this is especially useful for translators who may have to
305 deal with both @code{lilypond/translation} and a stable branch,
306 e.g. @code{stable/2.12}.
308 Some Git commands are introduced first, then a workflow with several
309 Git branches of LilyPond source code is presented.
312 * Introduction to Git concepts::
313 * Git commands for managing several branches::
314 * Working on LilyPond sources with several branches::
316 * Applying git patches::
320 @node Introduction to Git concepts
321 @subsection Introduction to Git concepts
323 A bit of Git vocabulary will be explained below. The following is
324 just introduction material; for better understanding of Git concepts,
325 you are invited to read further documentation, especially Git
326 Community Book at @uref{http://book.git-scm.com/}.
328 The @code{git pull origin} command above is just a shortcut for this
332 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
336 where @code{@var{branch}} is typically @code{master}, @code{web} or
337 @code{lilypond/translation}; if you do not know or remember, see
338 @ref{Getting the source code} to remember which commands you issued or
339 which source code you wanted to get.
341 A @emph{commit} is a set of changes made to the sources; it also
342 includes the committish of the parent commit, the name and e-mail of
343 the @emph{author} (the person who wrote the changes), the name and
344 e-mail of the @emph{committer} (the person who brings these changes
345 into the Git repository), and a commit message.
347 A @emph{committish} is the SHA1 checksum of a commit, a number made of
348 40 hexadecimal digits, which acts as the internal unique identifier
349 for this commit. To refer to a particular revision, don't use vague
350 references like the (approximative) date, simply copy and paste the
353 A @emph{branch} is nothing more than a pointer to a particular commit,
354 which is called the @emph{head} of the branch; when referring to a
355 branch, one often acutally thinks about its head and the ancestor
358 Now we will explain the two last commands you used to get the source
359 code from Git -- see @ref{Getting the source code}.
362 git remote add -f -t @var{branch} -m @var{branch} origin git://git.sv.gnu.org/lilypond.git/
363 git checkout -b @var{branch} origin/@var{branch}
366 The @command{git remote} has created a branch called
367 @code{origin/@var{branch}} in your local Git repository. As this
368 branch is a copy of the remote branch web from git.sv.gnu.org LilyPond
369 repository, it is called a @emph{remote branch}, and is meant to track
370 the changes on the branch from git.sv.gnu.org: it will be updated
371 every time you run @command{git pull origin} or @command{git fetch
374 The @command{git checkout} command has created a branch named
375 @code{@var{branch}}. At the beginning, this branch is identical to
376 @code{origin/@var{branch}}, but it will differ as soon as you make
377 changes, e.g. adding newly translated pages or editing some
378 documentation or code source file. Whenever you pull, you merge the
379 changes from @code{origin/@var{branch}} and @code{@var{branch}} since
380 the last pulling. If you do not have push (i.e. @qq{write}) access on
381 git.sv.gnu.org, your @code{@var{branch}} will always differ from
382 @code{origin/@var{branch}}. In this case, remember that other people
383 working like you with the remote branch @code{@var{branch}} of
384 git://git.sv.gnu.org/lilypond.git/ (called @code{origin/@var{branch}}
385 on your local repository) know nothing about your own
386 @code{@var{branch}}: this means that whenever you use a committish or
387 make a patch, others expect you to take the latest commit of
388 @code{origin/@var{branch}} as a reference.
390 Finally, please remember to read the man page of every Git command you
391 will find in this manual in case you want to discover alternate
392 methods or just understand how it works.
395 @node Git commands for managing several branches
396 @subsection Git commands for managing several branches
398 @subsubheading Listing branches and remotes
400 You can get the exact path or URL of all remotes with
407 To list Git branches on your local repositories, run
410 git branch # list local branches only
411 git branch -r # list remote branches
412 git branch -a # list all branches
416 @subsubheading Checking out branches
418 To know the currently checked out branch, i.e. the branch whose source
419 files are present in your working tree, read the first line of the
427 The currently checked out branch is also marked with an asterisk in
428 the output of @command{git branch}.
430 You can check out another branch @code{@var{other_branch}}, i.e. check
431 out @code{@var{other_branch}} to the working tree, by running
434 git checkout @var{other_branch}
437 Note that it is possible to check out another branch while having
438 uncommitted changes, but it is not recommended unless you know what
439 you are doing; it is recommended to run @command{git status} to check
440 this kind of issue before checking out another branch.
443 @subsubheading Merging branches
445 To merge branch @code{@var{foo}} into branch @code{@var{bar}}, i.e. to
446 @qq{add} all changes made in branch @code{@var{foo}} to branch
447 @code{@var{bar}}, run
450 git checkout @var{bar}
454 If any conflict happens, see @ref{Resolving conflicts}.
456 There are common usage cases for merging: as a translator, you will
457 often want to merge @code{master} into @code{lilypond/translation}; on
458 the other hand, the Translations meister wants to merge
459 @code{lilypond/translation} into @code{master} whenever he has checked
460 that @code{lilypond/translation} builds successfully.
463 @node Working on LilyPond sources with several branches
464 @subsection Working on LilyPond sources with several branches
466 @subsubheading Fetching new branches from git.sv.gnu.org
468 To fetch and check out a new branch named @code{@var{branch}} on
469 git.sv.gnu.org, run from top of the Git repository
472 git config --add remote.origin.fetch +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
473 git checkout --track -b @var{branch} origin/@var{branch}
476 After this, you can pull @code{@var{branch}} from git.sv.gnu.org with
482 Note that this command generally fetches all branches you added with
483 @command{git remote add} (when you initialized the repository) or
484 @command{git config --add}, i.e. it updates all remote branches from
485 remote @code{origin}, then it merges the remote branch tracked by
486 current branch into current branch. For example, if your current
487 branch is @code{master} --- which is the case if you got the sources
488 with the commands described in @ref{Main source code} and did not
489 issue any @command{git checkout} command --- @code{origin/master} will
490 be merged into @code{master}.
493 @subsubheading Local clones, or having several working trees
495 If you play with several Git branches, e.g. @code{master},
496 @code{lilypond/translation}, @code{stable/2.12}), you may want to have
497 one source and build tree for each branch; this is possible with
498 subdirectories of your local Git repository, used as local cloned
499 subrepositories. To create a local clone for the branch named
500 @code{@var{branch}}, run
503 git checkout @var{branch}
504 git clone -l -s -n . @var{subdir}
509 Note that @code{@var{subdir}} must be a directory name which does not
510 already exist. In @code{@var{subdir}}, you can use all Git commands
511 to browse revisions history, commit and uncommit changes; to update
512 the cloned subrepository with changes made on the main repository, cd
513 into @code{@var{subdir}} and run @command{git pull}; to send changes
514 made on the subrepository back to the main repository, run
515 @command{git push} from @code{@var{subdir}}. Note that only one
516 branch (the currently checked out branch) is created in the
517 subrepository by default; it is possible to have several branches in a
518 subrepository and do usual operations (checkout, merge, create,
519 delete...) on these branches, but this possibility is not detailed
522 When you push @code{@var{branch}} from @code{@var{subdir}} to the main
523 repository, and @code{@var{branch}} is checked out in the main
524 repository, you must save uncommitted changes (see @command{git
525 stash}) and do @command{git reset --hard} in the main repository in
526 order to apply pushed changes in the working tree of the main
533 The commands above don't only bring you the latest version of the
534 sources, but also the full history of revisions (revisons, also
535 called commits, are changes made to the sources), stored in the
536 .git directory. You can browse this history with
539 git log # only shows the logs (author, committish and commit message)
540 git log -p # also shows diffs
541 gitk # shows history graphically
544 @warning{The @code{gitk} command may require a separate @code{gitk} package,
545 available in the appropriate distribution's repositories.}
548 @node Applying git patches
549 @subsection Applying git patches
551 Well-formed git patches created with @code{git format-patch}
552 should be committed with the following command:
558 Patches created without @code{git format-patch} can be applied in
559 two steps. The first step is to apply the patch to the working
563 git apply @var{patch}
567 The second step is to commit the changes and give credit to the
568 author of the patch. This can be done with the following command:
571 git commit -a --author="First Last <user@@example.net>"
576 @section Git on Windows
578 @c Some of this may duplicate stuff in other sections
579 @c Clear this up later -td
581 @subsection Background to nomenclature
583 Git is a system for tracking the changes made to source files by
584 a distributed set of editors. It is designed to work without a
585 master repository, but we have chosen to have a master respository
586 for LilyPond files. Editors hold local copies of the master
587 repository together with any changes they have made locally. Local
588 changes are held in a local @q{branch}, of which there may be
589 several, but these instructions assume you are using just one. The
590 files visible in the local repository always correspond to those
591 on the currently @q{checked out} local branch.
593 Files are edited on a local branch, and in that state the
594 changes are said to be @q{unstaged}. When editing is complete, the
595 changes are moved to being @q{staged for commit}, and finally the
596 changes are @q{committed} to the local branch. Once
597 committed, the changes are given a unique reference number called the
598 @q{Committish} which identifies them to Git. Such committed changes
599 can be sent to the master repository by @q{pushing} them (if you
600 have write permission) or by sending them by email to someone who
601 has, either complete or as a @q{diff} or @q{patch} (which send
602 just the differences from master).
604 @subsection Installing git
607 @uref{http://code.google.com/p/msysgit/downloads/list}
608 (note, not msysGit, which is for Git developers and not PortableGit,
609 which is not a full git installation) and
612 Note that most users will not need to install SSH. That is not
613 required until you have been granted direct push permissions to
614 the master git repository.
616 Start Git by clicking on the desktop icon.
617 This will bring up a command line bash shell. This may be
618 unfamiliar to Windows users. If so, follow these
619 instructions carefully. Commands are entered at a $ prompt
620 and are terminated by keying a newline.
622 @subsection Initialising Git
624 Decide where you wish to place your local Git repository,
625 creating the folders in Windows as necessary. Here we
626 call the folder to contain the repository [path]/Git.
627 You will need to have space for around 150Mbytes.
629 Start the Git bash shell by clicking on the desk-top icon installed
636 to position the shell at your new Git repository.
638 Note: if [path] contains folders with names containing
651 to initialize your Git repository.
653 Then type (all on one line; the shell will wrap automatically)
656 git remote add -f -t master origin git://git.sv.gnu.org/lilypond.git
659 to download the lilypond master files.
661 @warning{Be patient! Even on a broadband connection this can take
662 10 minutes or more. Wait for lots of [new tag] messages
665 We now need to generate a local copy of the downloaded files
666 in a new local branch. Your local branch needs to have a
667 name, here we call it @q{lily-local} - you may wish to make up
673 git checkout -b lily-local origin/master
676 to create the lily-local branch containing the local copies of the
677 master files. You will be advised your local branch has been set
678 up to track the remote branch.
680 Return to Windows Explorer and look in your Git repository. You
681 should see lots of folders. For example, the LilyPond documentation
682 can be found in Git/Documentation/user.
684 Terminate the Git bash shell by typing @code{exit}.
688 Almost all subsequent work will use the Git Graphical User
689 Interface, which avoids having to type command line
690 commands. To start Git GUI first start the Git bash shell by
691 clicking on the desktop icon, and type
698 The Git GUI will open in a new window. It contains four panels
699 and 7 pull-down menus. At this stage do not use any of the
700 commands under Branch, Commit, Merge or Remote. These will
703 The two panels on the left contain the names of files which
704 you are in the process of editing (Unstaged Changes), and
705 files you have finished editing and have staged ready for
706 committing (Staged Changes). At this stage these panels will
707 be empty as you have not yet made any changes to any file.
708 After a file has been edited and saved the top panel on the right
709 will display the differences between the edited file selected
710 in one of the panels on the left and the last version committed.
712 The final panel at bottom right is used to enter a descriptive
713 message about the change before committing it.
715 The Git GUI is terminated by entering CNTL-Q while it is the
716 active window or by clicking on the usual Windows close-window
719 @subsection Personalising your local git repository
721 Open the Git GUI, click on
727 and enter your name and email address in the
728 left-hand (Git Repository) panel. Leave everything
729 else unchanged and save it.
731 Note that Windows users must leave the default setting for line
732 endings unchanged. All files in a git repository must have lines
733 terminated by just a LF, as this is required for Merge to work, but
734 Windows files are terminated by CRLF by default. The git default
735 setting causes the line endings of files in a Windows git repository
736 to be flipped automatically between LF and CRLF as required. This
737 enables files to be edited by any Windows editor without causing
738 problems in the git repository.
740 @subsection Checking out a branch
742 At this stage you have two branches in your local repository,
743 both identical. To see them click on
749 You should have one local branch called @w{lily-local} and one
750 tracking branch called @w{origin/master}. The latter is your
751 local copy of the @w{remote/origin/master} branch in the master
752 LilyPond repository. The @w{lily-local} branch is where you
753 will make your local changes.
755 When a particular branch is selected, i.e., checked out, the
756 files visible in your repository are changed to reflect the
757 state of the files on that branch.
759 @subsection Updating files from @w{remote/origin/master}
761 Before starting the editing of a file, ensure your local branches
762 contain the latest version in @w{remote/origin/master} by first
766 Remote -> Fetch from -> origin
772 This will place the latest version of every file, including all the
773 changes made by others,
774 into the @q{origin/master} branch of the tracking branches
775 in your git repository. You can see these files by checking
776 out this branch. This will not affect any files you have
777 modified in your local branch.
779 You then need to merge these fetched files into your local
780 branch by clicking on
787 and if necessary select the local branch into which the merge
790 Note that a merge cannot be completed if there are any local
791 uncommitted changes on the lily-local branch.
793 This will update all the files in that branch to reflect the
794 current state of the @w{origin/master} branch. If any of the
795 changes conflict with changes you have made yourself recently
796 you will be notified of the conflict (see below).
798 @subsection Editing files
800 First ensure your lily-local branch is checked out, then
801 simply edit the files in your local Git repository with your
802 favourite editor and save them back there. If any file contains
803 non-ASCII characters ensure you save it in UTF-8 format. Git will
804 detect any changes whenever you restart Git GUI and the file names
805 will then be listed in the Unstaged Changes panel.
806 Or you can click the Rescan button to refresh the panel
807 contents at any time. You may break off and resume at
810 The changes you have made may be displayed in diff form
811 in the top right-hand panel by clicking on the name in
814 When your editing is complete, move the files from being
815 Unstaged to Staged by clicking the document symbol to
816 the left of each name. If you change your mind it can
817 be moved back by clicking on the ticked box to the
820 Finally the changes you have made may be committed to
821 your lily-local branch by entering a brief message in
822 the Commit Message box and clicking the Commit button.
824 If you wish to amend your changes after a commit has been
825 made, the original version and the changes you made in that
826 commit may be recovered by selecting
829 Commit -> Amend Last Commit
833 or by checking the Amend Last Commit radio button at bottom left.
834 This will return the changes to the Staged state, so further
835 editing made be carried out within that commit. This must only be
836 done @emph{before} the changes have been Pushed or sent to your
837 mentor for Pushing - after that it is too late and corrections
838 have to be made as a separate commit.
841 @subsection Sending changes to remote/origin/master
843 If you do not have write access to @w{remote/origin/master} you will
844 need to send your changes by email to someone who does.
846 First you need to create a diff or patch file containing
847 your changes. To create this, the file must first be
848 committed. Then terminate the Git GUI. In the
849 git bash shell first cd to your Git repository with
855 if necessary, then produce the patch with
858 git format-patch origin
861 This will create a patch file for all the locally committed files
862 which differ from @w{origin/master}. The patch file can be found
863 in [path]/Git and will have a name formed from n and the commit
866 @subsection Resolving merge conflicts
868 As soon as you have committed a changed file your local
869 branch has diverged from @w{origin/master}, and will
870 remain diverged until your changes have been committed
871 in @w{remote/origin/master} and Fetched back into your
872 @w{origin/master}. Similarly, if a new commit has been made
873 to @w{remote/origin/master} by someone else and Fetched, your
874 lily-local branch is divergent. You can detect a divergent
875 branch by clicking on
878 Repository -> Visualise all branch history
881 This opens up a very useful new window called @q{gitk}.
882 Use this to browse all the commits made by others.
884 If the diagram at top left of the resulting window
885 does not show your branch's tag on the same node as
886 the @w{remote/origins/master} tag your branch has diverged from
887 @w{origin/master}. This is quite normal if files you have modified
888 yourself have not yet been Pushed to @w{remote/origin/master} and
889 Fetched, or if files modified and committed by others have been
890 Fetched since you last Merged @w{origin/master} into your lily-local
893 If a file being merged from @w{origin/master} differs from
894 one you have modified in a way that cannot be resolved
895 automatically by git, Merge will report a Conflict
896 which you must resolve by editing the file to create the
897 version you wish to keep.
899 This could happen if the person updating @w{remote/origin/master}
900 for you has added some changes of his own before
901 committing your changes to @w{remote/origin/master}, or if someone
902 else has changed the same file since you last
903 fetched the file from @w{remote/origin/master}.
905 Open the file in your editor and look for sections which
906 are delimited with ...
908 [to be completed when I next have a merge conflict to be
909 sure I give the right instructions -td]
912 @subsection Other actions
914 The instructions above describe the simplest way of using
915 git on Windows. Other git facilities which may usefully
916 supplement these include
920 @item Using multiple local branches (Create, Rename, Delete)
921 @item Resetting branches
922 @item Cherry-picking commits
923 @item Pushing commits to @w{remote/origin/master}
924 @item Using gitk to review history
928 Once familiarity with using git on Windows has been gained the
929 standard git manuals can be used to learn about these.
932 @node Development inside VirtualBox (compiling on Windows)
933 @section Development inside VirtualBox (compiling on Windows)