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::
18 @node Getting the source code
19 @section Getting the source code
24 * Website source code::
25 * Documentation translations source code::
27 * Other locations for git::
28 * Git user configuration::
31 @node Git introduction
32 @subsection Git introduction
34 The source code is kept in a Git respository. This allows us to
35 track changes to files, and for multiple people to work on the
36 same set of files efficiently.
38 @warning{These instructions assume that you are using the
39 command-line version of Git 1.5 or higher. Windows users should
40 skip to @ref{Git on Windows}.}
43 @node Main source code
44 @subsection Main source code
46 To get the main source code and documentation,
48 @c WARNING: when updating the commands below, please
49 @c update the other flavors in the two next nodes
50 @c and in Introduction to Git concepts
52 mkdir lilypond; cd lilypond
54 git remote add -f -t master -m master origin git://git.sv.gnu.org/lilypond.git/
55 git checkout -b master origin/master
59 @node Website source code
60 @subsection Website source code
62 To get the website (including translations),
65 mkdir lilypond-web ; cd lilypond-web
67 git remote add -f -t web -m web origin git://git.sv.gnu.org/lilypond.git/
68 git checkout -b web origin/web
72 @node Documentation translations source code
73 @subsection Documentation translations source code
75 To translate the documentation (@emph{not} the website),
78 mkdir lilypond-translation; cd lilypond-translation
80 git remote add -f -t lilypond/translation -m lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
81 git checkout -b lilypond/translation origin/lilypond/translation
86 @subsection Other branches
88 Most contributors will never need to touch the other branches. If
89 you wish to do so, you will need more familiarity with git.
94 This stores the Grand Unified Binary, our cross-platform building
96 @c TODO: merge the gub stuff with this CG.
97 For more info, see @uref{http://lilypond.org/gub}. The git
101 http://github.com/janneke/gub
104 @item @code{dev/XYZ}:
105 These branches are for individual developers. They store code
106 which is not yet stable enough to be added to the @code{master}
109 @item @code{stable/XYZ}:
110 The branches are kept for archival reasons.
115 @node Other locations for git
116 @subsection Other locations for git
118 If you have difficulty connecting to most of the repositories
119 listed in earlier sections, try:
122 http://git.sv.gnu.org/r/lilypond.git
123 git://git.sv.gnu.org/lilypond.git
124 ssh://git.sv.gnu.org/srv/git/lilypond.git
127 Using HTTP protocol is slowest, so it is not recommended unless both
128 SSH and Git protocols fail, which happens e.g. if you connect to
129 internet through a router that filters out Git and/or SSH connections.
132 @node Git user configuration
133 @subsection Git user configuration
135 To configure git to automatically use your name and email address
136 for commits and patches,
139 git config --global user.name "MYNAME"
140 git config --global user.email MYEMAIL@@EXAMPLE.NET
144 @node Updating the source code
145 @section Updating the source code
148 * Importance of updating::
150 * Resolving conflicts::
154 @node Importance of updating
155 @subsection Importance of updating
157 In a large project like LilyPond, contributors sometimes edit the same
158 file at the same time. As long as everybody updates their version of
159 the file with the most recent changes (@emph{pulling}), there are
160 generally no problems with this multiple-person editing. However,
161 boring problems can arise if you do not pull before attempting commit,
162 e.g. you may encounter a conflict; in this case, see @ref{Resolving
167 @subsection Updating command
169 Whenever you are asked to pull, it means you should update your
170 local copy of the repository with the changes made by others on
171 the remote @code{git.sv.gnu.org} repository:
178 @node Resolving conflicts
179 @subsection Resolving conflicts
181 Occasionally an update may result in conflicts -- this happens
182 when you and somebody else have modified the same part of the same
183 file and git cannot figure out how to merge the two versions
184 together. When this happens, you must manually merge the two
187 If you need some documentation to understand and resolve conflicts,
188 see paragraphs @emph{How conflicts are presented} and @emph{How to
189 resolve conflicts} in @command{git merge} man page.
192 @node Sharing your changes
193 @section Sharing your changes
196 * Producing a patch::
197 * Committing directly::
201 @node Producing a patch
202 @subsection Producing a patch
204 Once you have finished editing your files, checked that your changes
205 meet the @ref{Code style}, and/or @ref{Documentation policy}, properly
206 set up your name and email in @ref{Git user configuration}, and
207 checked that the entire thing compiles, you may:
211 git format-patch origin
214 The commit should include a brief message describing the change.
215 This consists of a one-line summary describing the change, and
216 if necessary a blank line followed by several lines giving the
220 Did household chores.
222 I hung up the wet laundry and then washed the car. I also
223 vacuumed the floors, rinsed the dirty dishes, fed the cat, and
224 recalibrated the temporal flux machine.
227 If the change is to the documentation only then the one-line
228 summary should be prefixed with @qq{Docs: }.
230 If you added a file to the source code, you must add it to git
238 (and possibly modify the @file{GNUmakefile})
240 These commands will produce one or more files named
241 @file{0001-xyz}, @file{0002-abc}, etc. in the top directory of the
242 git tree. Send an email to @email{lilypond-devel@@gnu.org} with
243 these files attached, and a developer will review and apply the
244 patches to the main repository.
247 @node Committing directly
248 @subsection Committing directly
250 Most contributors do not have permission to commit directly. If you
251 do, make sure you have set up your name and email in @ref{Git user
252 configuration}, then edit @file{.git/config}: change the line
255 url = git://git.sv.gnu.org/lilypond.git/
262 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
266 where @var{user} is your login name on Savannah.
268 If you have not already done so, you should generate and upload a SSH
269 key: open @uref{https://savannah.gnu.org/my/} in your browser, then go to
270 @q{Preferences} then to something like @q{Edit SSH Keys}, and follow
271 the instructions on that page.
279 @node Advanced git stuff
280 @section Advanced git stuff
282 @warning{This section is not necessary for normal contributors;
283 these commands are presented for information for people interested
284 in learning more about git.}
287 It is possible to work with several branches on the same local Git
288 repository; this is especially useful for translators who may have to
289 deal with both @code{lilypond/translation} and a stable branch,
290 e.g. @code{stable/2.12}.
292 Some Git commands are introduced first, then a workflow with several
293 Git branches of LilyPond source code is presented.
296 * Introduction to Git concepts::
297 * Git commands for managing several branches::
298 * Working on LilyPond sources with several branches::
300 * Applying git patches::
304 @node Introduction to Git concepts
305 @subsection Introduction to Git concepts
307 A bit of Git vocabulary will be explained below. The following is
308 just introduction material; for better understanding of Git concepts,
309 you are invited to read further documentation, especially Git
310 Community Book at @uref{http://book.git-scm.com/}.
312 The @code{git pull origin} command above is just a shortcut for this
316 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
320 where @code{@var{branch}} is typically @code{master}, @code{web} or
321 @code{lilypond/translation}; if you do not know or remember, see
322 @ref{Getting the source code} to remember which commands you issued or
323 which source code you wanted to get.
325 A @emph{commit} is a set of changes made to the sources; it also
326 includes the committish of the parent commit, the name and e-mail of
327 the @emph{author} (the person who wrote the changes), the name and
328 e-mail of the @emph{committer} (the person who brings these changes
329 into the Git repository), and a commit message.
331 A @emph{committish} is the SHA1 checksum of a commit, a number made of
332 40 hexadecimal digits, which acts as the internal unique identifier
333 for this commit. To refer to a particular revision, don't use vague
334 references like the (approximative) date, simply copy and paste the
337 A @emph{branch} is nothing more than a pointer to a particular commit,
338 which is called the @emph{head} of the branch; when referring to a
339 branch, one often acutally thinks about its head and the ancestor
342 Now we will explain the two last commands you used to get the source
343 code from Git -- see @ref{Getting the source code}.
346 git remote add -f -t @var{branch} -m @var{branch} origin git://git.sv.gnu.org/lilypond.git/
347 git checkout -b @var{branch} origin/@var{branch}
350 The @command{git remote} has created a branch called
351 @code{origin/@var{branch}} in your local Git repository. As this
352 branch is a copy of the remote branch web from git.sv.gnu.org LilyPond
353 repository, it is called a @emph{remote branch}, and is meant to track
354 the changes on the branch from git.sv.gnu.org: it will be updated
355 every time you run @command{git pull origin} or @command{git fetch
358 The @command{git checkout} command has created a branch named
359 @code{@var{branch}}. At the beginning, this branch is identical to
360 @code{origin/@var{branch}}, but it will differ as soon as you make
361 changes, e.g. adding newly translated pages or editing some
362 documentation or code source file. Whenever you pull, you merge the
363 changes from @code{origin/@var{branch}} and @code{@var{branch}} since
364 the last pulling. If you do not have push (i.e. @qq{write}) access on
365 git.sv.gnu.org, your @code{@var{branch}} will always differ from
366 @code{origin/@var{branch}}. In this case, remember that other people
367 working like you with the remote branch @code{@var{branch}} of
368 git://git.sv.gnu.org/lilypond.git/ (called @code{origin/@var{branch}}
369 on your local repository) know nothing about your own
370 @code{@var{branch}}: this means that whenever you use a committish or
371 make a patch, others expect you to take the latest commit of
372 @code{origin/@var{branch}} as a reference.
374 Finally, please remember to read the man page of every Git command you
375 will find in this manual in case you want to discover alternate
376 methods or just understand how it works.
379 @node Git commands for managing several branches
380 @subsection Git commands for managing several branches
382 @subsubheading Listing branches and remotes
384 You can get the exact path or URL of all remotes with
391 To list Git branches on your local repositories, run
394 git branch # list local branches only
395 git branch -r # list remote branches
396 git branch -a # list all branches
400 @subsubheading Checking out branches
402 To know the currently checked out branch, i.e. the branch whose source
403 files are present in your working tree, read the first line of the
411 The currently checked out branch is also marked with an asterisk in
412 the output of @command{git branch}.
414 You can check out another branch @code{@var{other_branch}}, i.e. check
415 out @code{@var{other_branch}} to the working tree, by running
418 git checkout @var{other_branch}
421 Note that it is possible to check out another branch while having
422 uncommitted changes, but it is not recommended unless you know what
423 you are doing; it is recommended to run @command{git status} to check
424 this kind of issue before checking out another branch.
427 @subsubheading Merging branches
429 To merge branch @code{@var{foo}} into branch @code{@var{bar}}, i.e. to
430 @qq{add} all changes made in branch @code{@var{foo}} to branch
431 @code{@var{bar}}, run
434 git checkout @var{bar}
438 If any conflict happens, see @ref{Resolving conflicts}.
440 There are common usage cases for merging: as a translator, you will
441 often want to merge @code{master} into @code{lilypond/translation}; on
442 the other hand, the Translations meister wants to merge
443 @code{lilypond/translation} into @code{master} whenever he has checked
444 that @code{lilypond/translation} builds successfully.
447 @node Working on LilyPond sources with several branches
448 @subsection Working on LilyPond sources with several branches
450 @subsubheading Fetching new branches from git.sv.gnu.org
452 To fetch and check out a new branch named @code{@var{branch}} on
453 git.sv.gnu.org, run from top of the Git repository
456 git config --add remote.origin.fetch +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
457 git checkout --track -b @var{branch} origin/@var{branch}
460 After this, you can pull @code{@var{branch}} from git.sv.gnu.org with
466 Note that this command generally fetches all branches you added with
467 @command{git remote add} (when you initialized the repository) or
468 @command{git config --add}, i.e. it updates all remote branches from
469 remote @code{origin}, then it merges the remote branch tracked by
470 current branch into current branch. For example, if your current
471 branch is @code{master} --- which is the case if you got the sources
472 with the commands described in @ref{Main source code} and did not
473 issue any @command{git checkout} command --- @code{origin/master} will
474 be merged into @code{master}.
477 @subsubheading Local clones, or having several working trees
479 If you play with several Git branches, e.g. @code{master},
480 @code{lilypond/translation}, @code{stable/2.12}), you may want to have
481 one source and build tree for each branch; this is possible with
482 subdirectories of your local Git repository, used as local cloned
483 subrepositories. To create a local clone for the branch named
484 @code{@var{branch}}, run
487 git checkout @var{branch}
488 git clone -l -s -n . @var{subdir}
493 Note that @code{@var{subdir}} must be a directory name which does not
494 already exist. In @code{@var{subdir}}, you can use all Git commands
495 to browse revisions history, commit and uncommit changes; to update
496 the cloned subrepository with changes made on the main repository, cd
497 into @code{@var{subdir}} and run @command{git pull}; to send changes
498 made on the subrepository back to the main repository, run
499 @command{git push} from @code{@var{subdir}}. Note that only one
500 branch (the currently checked out branch) is created in the
501 subrepository by default; it is possible to have several branches in a
502 subrepository and do usual operations (checkout, merge, create,
503 delete...) on these branches, but this possibility is not detailed
506 When you push @code{@var{branch}} from @code{@var{subdir}} to the main
507 repository, and @code{@var{branch}} is checked out in the main
508 repository, you must save uncommitted changes (see @command{git
509 stash}) and do @command{git reset --hard} in the main repository in
510 order to apply pushed changes in the working tree of the main
518 The commands above don't only bring you the latest version of the
519 sources, but also the full history of revisions (revisons, also
520 called commits, are changes made to the sources), stored in the
521 .git directory. You can browse this history with
524 git log # only shows the logs (author, committish and commit message)
525 git log -p # also shows diffs
526 gitk # shows history graphically
529 @warning{The @code{gitk} command may require a separate @code{gitk} package,
530 available in the appropriate distribution's repositories.}
532 @node Applying git patches
533 @subsection Applying git patches
535 Well-formed git patches should be committed with
541 Patches created without @code{git format-patch} should be
551 @section Git on Windows
553 @c Some of this may duplicate stuff in other sections
554 @c Clear this up later -td
556 @subsection Background to nomenclature
558 Git is a system for tracking the changes made to source files by
559 a distributed set of editors. It is designed to work without a
560 master repository, but we have chosen to have a master respository
561 for LilyPond files. Editors hold local copies of the master
562 repository together with any changes they have made locally. Local
563 changes are held in a local @q{branch}, of which there may be
564 several, but these instructions assume you are using just one. The
565 files visible in the local repository always correspond to those
566 on the currently @q{checked out} local branch.
568 Files are edited on a local branch, and in that state the
569 changes are said to be @q{unstaged}. When editing is complete, the
570 changes are moved to being @q{staged for commit}, and finally the
571 changes are @q{committed} to the local branch. Once
572 committed, the changes are given a unique reference number called the
573 @q{Committish} which identifies them to Git. Such committed changes
574 can be sent to the master repository by @q{pushing} them (if you
575 have write permission) or by sending them by email to someone who
576 has, either complete or as a @q{diff} or @q{patch} (which send
577 just the differences from master).
579 @subsection Installing git
582 @uref{http://code.google.com/p/msysgit/downloads/list}
583 (note, not msysGit, which is for Git developers and not PortableGit,
584 which is not a full git installation) and
587 Note that most users will not need to install SSH. That is not
588 required until you have been granted direct push permissions to
589 the master git repository.
591 Start Git by clicking on the desktop icon.
592 This will bring up a command line bash shell. This may be
593 unfamiliar to Windows users. If so, follow these
594 instructions carefully. Commands are entered at a $ prompt
595 and are terminated by keying a newline.
597 @subsection Initialising Git
599 Decide where you wish to place your local Git repository,
600 creating the folders in Windows as necessary. Here we
601 call the folder to contain the repository [path]/Git.
602 You will need to have space for around 150Mbytes.
604 Start the Git bash shell by clicking on the desk-top icon installed
611 to position the shell at your new Git repository.
613 Note: if [path] contains folders with names containing
626 to initialize your Git repository.
628 Then type (all on one line; the shell will wrap automatically)
631 git remote add -f -t master origin git://git.sv.gnu.org/lilypond.git
634 to download the lilypond master files.
636 @warning{Be patient! Even on a broadband connection this can take
637 10 minutes or more. Wait for lots of [new tag] messages
640 We now need to generate a local copy of the downloaded files
641 in a new local branch. Your local branch needs to have a
642 name, here we call it @q{lily-local} - you may wish to make up
648 git checkout -b lily-local origin/master
651 to create the lily-local branch containing the local copies of the
652 master files. You will be advised your local branch has been set
653 up to track the remote branch.
655 Return to Windows Explorer and look in your Git repository. You
656 should see lots of folders. For example, the LilyPond documentation
657 can be found in Git/Documentation/user.
659 Terminate the Git bash shell by typing @code{exit}.
663 Almost all subsequent work will use the Git Graphical User
664 Interface, which avoids having to type command line
665 commands. To start Git GUI first start the Git bash shell by
666 clicking on the desktop icon, and type
673 The Git GUI will open in a new window. It contains four panels
674 and 7 pull-down menus. At this stage do not use any of the
675 commands under Branch, Commit, Merge or Remote. These will
678 The two panels on the left contain the names of files which
679 you are in the process of editing (Unstaged Changes), and
680 files you have finished editing and have staged ready for
681 committing (Staged Changes). At this stage these panels will
682 be empty as you have not yet made any changes to any file.
683 After a file has been edited and saved the top panel on the right
684 will display the differences between the edited file selected
685 in one of the panels on the left and the last version committed.
687 The final panel at bottom right is used to enter a descriptive
688 message about the change before committing it.
690 The Git GUI is terminated by entering CNTL-Q while it is the
691 active window or by clicking on the usual Windows close-window
694 @subsection Personalising your local git repository
696 Open the Git GUI, click on
702 and enter your name and email address in the
703 left-hand (Git Repository) panel. Leave everything
704 else unchanged and save it.
706 Note that Windows users must leave the default setting for line
707 endings unchanged. All files in a git repository must have lines
708 terminated by just a LF, as this is required for Merge to work, but
709 Windows files are terminated by CRLF by default. The git default
710 setting causes the line endings of files in a Windows git repository
711 to be flipped automatically between LF and CRLF as required. This
712 enables files to be edited by any Windows editor without causing
713 problems in the git repository.
715 @subsection Checking out a branch
717 At this stage you have two branches in your local repository,
718 both identical. To see them click on
724 You should have one local branch called @w{lily-local} and one
725 tracking branch called @w{origin/master}. The latter is your
726 local copy of the @w{remote/origin/master} branch in the master
727 LilyPond repository. The @w{lily-local} branch is where you
728 will make your local changes.
730 When a particular branch is selected, i.e., checked out, the
731 files visible in your repository are changed to reflect the
732 state of the files on that branch.
734 @subsection Updating files from @w{remote/origin/master}
736 Before starting the editing of a file, ensure your local branches
737 contain the latest version in @w{remote/origin/master} by first
741 Remote -> Fetch from -> origin
747 This will place the latest version of every file, including all the
748 changes made by others,
749 into the @q{origin/master} branch of the tracking branches
750 in your git repository. You can see these files by checking
751 out this branch. This will not affect any files you have
752 modified in your local branch.
754 You then need to merge these fetched files into your local
755 branch by clicking on
762 and if necessary select the local branch into which the merge
765 Note that a merge cannot be completed if there are any local
766 uncommitted changes on the lily-local branch.
768 This will update all the files in that branch to reflect the
769 current state of the @w{origin/master} branch. If any of the
770 changes conflict with changes you have made yourself recently
771 you will be notified of the conflict (see below).
773 @subsection Editing files
775 First ensure your lily-local branch is checked out, then
776 simply edit the files in your local Git repository with your
777 favourite editor and save them back there. If any file contains
778 non-ASCII characters ensure you save it in UTF-8 format. Git will
779 detect any changes whenever you restart Git GUI and the file names
780 will then be listed in the Unstaged Changes panel.
781 Or you can click the Rescan button to refresh the panel
782 contents at any time. You may break off and resume at
785 The changes you have made may be displayed in diff form
786 in the top right-hand panel by clicking on the name in
789 When your editing is complete, move the files from being
790 Unstaged to Staged by clicking the document symbol to
791 the left of each name. If you change your mind it can
792 be moved back by clicking on the ticked box to the
795 Finally the changes you have made may be committed to
796 your lily-local branch by entering a brief message in
797 the Commit Message box and clicking the Commit button.
799 If you wish to amend your changes after a commit has been
800 made, the original version and the changes you made in that
801 commit may be recovered by selecting
804 Commit -> Amend Last Commit
808 or by checking the Amend Last Commit radio button at bottom left.
809 This will return the changes to the Staged state, so further
810 editing made be carried out within that commit. This must only be
811 done @emph{before} the changes have been Pushed or sent to your
812 mentor for Pushing - after that it is too late and corrections
813 have to be made as a separate commit.
816 @subsection Sending changes to remote/origin/master
818 If you do not have write access to @w{remote/origin/master} you will
819 need to send your changes by email to someone who does.
821 First you need to create a diff or patch file containing
822 your changes. To create this, the file must first be
823 committed. Then terminate the Git GUI. In the
824 git bash shell first cd to your Git repository with
830 if necessary, then produce the patch with
833 git format-patch origin
836 This will create a patch file for all the locally committed files
837 which differ from @w{origin/master}. The patch file can be found
838 in [path]/Git and will have a name formed from n and the commit
841 @subsection Resolving merge conflicts
843 As soon as you have committed a changed file your local
844 branch has diverged from @w{origin/master}, and will
845 remain diverged until your changes have been committed
846 in @w{remote/origin/master} and Fetched back into your
847 @w{origin/master}. Similarly, if a new commit has been made
848 to @w{remote/origin/master} by someone else and Fetched, your
849 lily-local branch is divergent. You can detect a divergent
850 branch by clicking on
853 Repository -> Visualise all branch history
856 This opens up a very useful new window called @q{gitk}.
857 Use this to browse all the commits made by others.
859 If the diagram at top left of the resulting window
860 does not show your branch's tag on the same node as
861 the @w{remote/origins/master} tag your branch has diverged from
862 @w{origin/master}. This is quite normal if files you have modified
863 yourself have not yet been Pushed to @w{remote/origin/master} and
864 Fetched, or if files modified and committed by others have been
865 Fetched since you last Merged @w{origin/master} into your lily-local
868 If a file being merged from @w{origin/master} differs from
869 one you have modified in a way that cannot be resolved
870 automatically by git, Merge will report a Conflict
871 which you must resolve by editing the file to create the
872 version you wish to keep.
874 This could happen if the person updating @w{remote/origin/master}
875 for you has added some changes of his own before
876 committing your changes to @w{remote/origin/master}, or if someone
877 else has changed the same file since you last
878 fetched the file from @w{remote/origin/master}.
880 Open the file in your editor and look for sections which
881 are delimited with ...
883 [to be completed when I next have a merge conflict to be
884 sure I give the right instructions -td]
887 @subsection Other actions
889 The instructions above describe the simplest way of using
890 git on Windows. Other git facilities which may usefully
891 supplement these include
895 @item Using multiple local branches (Create, Rename, Delete)
896 @item Resetting branches
897 @item Cherry-picking commits
898 @item Pushing commits to @w{remote/origin/master}
899 @item Using gitk to review history
903 Once familiarity with using git on Windows has been gained the
904 standard git manuals can be used to learn about these.