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
219 If the change is to the documentation only the one-line summary
220 should be prefixed with "Docs: ".
222 If you added a file to the source code, you must add it to git
230 (and possibly modify the @file{GNUmakefile})
232 These commands will produce one or more files named
233 @file{0001-xyz}, @file{0002-abc}, etc. in the top directory of the
234 git tree. Send an email to @email{lilypond-devel@@gnu.org} with
235 these files attached.
238 @node Committing directly
239 @subsection Committing directly
241 Most contributors do not have permission to commit directly. If you
242 do, make sure you have set up your name and email in @ref{Git user
243 configuration}, then edit @file{.git/config}: change the line
246 url = git://git.sv.gnu.org/lilypond.git/
253 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
257 where @var{user} is your login name on Savannah.
259 If you have not already done so, you should generate and upload a SSH
260 key: open @uref{https://savannah.gnu.org/my/} in your browser, then go to
261 @q{Preferences} then to something like @q{Edit SSH Keys}, and follow
262 the instructions on that page.
270 @node Advanced git stuff
271 @section Advanced git stuff
273 @warning{This section is not necessary for normal contributors;
274 these commands are presented for information for people interested
275 in learning more about git.}
278 It is possible to work with several branches on the same local Git
279 repository; this is especially useful for translators who may have to
280 deal with both @code{lilypond/translation} and a stable branch,
281 e.g. @code{stable/2.12}.
283 Some Git commands are introduced first, then a workflow with several
284 Git branches of LilyPond source code is presented.
287 * Introduction to Git concepts::
288 * Git commands for managing several branches::
289 * Working on LilyPond sources with several branches::
291 * Applying git patches::
295 @node Introduction to Git concepts
296 @subsection Introduction to Git concepts
298 A bit of Git vocabulary will be explained below. The following is
299 just introduction material; for better understanding of Git concepts,
300 you are invited to read further documentation, especially Git
301 Community Book at @uref{http://book.git-scm.com/}.
303 The @code{git pull origin} command above is just a shortcut for this
307 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
311 where @code{@var{branch}} is typically @code{master}, @code{web} or
312 @code{lilypond/translation}; if you do not know or remember, see
313 @ref{Getting the source code} to remember which commands you issued or
314 which source code you wanted to get.
316 A @emph{commit} is a set of changes made to the sources; it also
317 includes the committish of the parent commit, the name and e-mail of
318 the @emph{author} (the person who wrote the changes), the name and
319 e-mail of the @emph{committer} (the person who brings these changes
320 into the Git repository), and a commit message.
322 A @emph{committish} is the SHA1 checksum of a commit, a number made of
323 40 hexadecimal digits, which acts as the internal unique identifier
324 for this commit. To refer to a particular revision, don't use vague
325 references like the (approximative) date, simply copy and paste the
328 A @emph{branch} is nothing more than a pointer to a particular commit,
329 which is called the @emph{head} of the branch; when referring to a
330 branch, one often acutally thinks about its head and the ancestor
333 Now we will explain the two last commands you used to get the source
334 code from Git -- see @ref{Getting the source code}.
337 git remote add -f -t @var{branch} -m @var{branch} origin git://git.sv.gnu.org/lilypond.git/
338 git checkout -b @var{branch} origin/@var{branch}
341 The @command{git remote} has created a branch called
342 @code{origin/@var{branch}} in your local Git repository. As this
343 branch is a copy of the remote branch web from git.sv.gnu.org LilyPond
344 repository, it is called a @emph{remote branch}, and is meant to track
345 the changes on the branch from git.sv.gnu.org: it will be updated
346 every time you run @command{git pull origin} or @command{git fetch
349 The @command{git checkout} command has created a branch named
350 @code{@var{branch}}. At the beginning, this branch is identical to
351 @code{origin/@var{branch}}, but it will differ as soon as you make
352 changes, e.g. adding newly translated pages or editing some
353 documentation or code source file. Whenever you pull, you merge the
354 changes from @code{origin/@var{branch}} and @code{@var{branch}} since
355 the last pulling. If you do not have push (i.e. @qq{write}) access on
356 git.sv.gnu.org, your @code{@var{branch}} will always differ from
357 @code{origin/@var{branch}}. In this case, remember that other people
358 working like you with the remote branch @code{@var{branch}} of
359 git://git.sv.gnu.org/lilypond.git/ (called @code{origin/@var{branch}}
360 on your local repository) know nothing about your own
361 @code{@var{branch}}: this means that whenever you use a committish or
362 make a patch, others expect you to take the latest commit of
363 @code{origin/@var{branch}} as a reference.
365 Finally, please remember to read the man page of every Git command you
366 will find in this manual in case you want to discover alternate
367 methods or just understand how it works.
370 @node Git commands for managing several branches
371 @subsection Git commands for managing several branches
373 @subsubheading Listing branches and remotes
375 You can get the exact path or URL of all remotes with
382 To list Git branches on your local repositories, run
385 git branch # list local branches only
386 git branch -r # list remote branches
387 git branch -a # list all branches
391 @subsubheading Checking out branches
393 To know the currently checked out branch, i.e. the branch whose source
394 files are present in your working tree, read the first line of the
402 The currently checked out branch is also marked with an asterisk in
403 the output of @command{git branch}.
405 You can check out another branch @code{@var{other_branch}}, i.e. check
406 out @code{@var{other_branch}} to the working tree, by running
409 git checkout @var{other_branch}
412 Note that it is possible to check out another branch while having
413 uncommitted changes, but it is not recommended unless you know what
414 you are doing; it is recommended to run @command{git status} to check
415 this kind of issue before checking out another branch.
418 @subsubheading Merging branches
420 To merge branch @code{@var{foo}} into branch @code{@var{bar}}, i.e. to
421 @qq{add} all changes made in branch @code{@var{foo}} to branch
422 @code{@var{bar}}, run
425 git checkout @var{bar}
429 If any conflict happens, see @ref{Resolving conflicts}.
431 There are common usage cases for merging: as a translator, you will
432 often want to merge @code{master} into @code{lilypond/translation}; on
433 the other hand, the Translations meister wants to merge
434 @code{lilypond/translation} into @code{master} whenever he has checked
435 that @code{lilypond/translation} builds successfully.
438 @node Working on LilyPond sources with several branches
439 @subsection Working on LilyPond sources with several branches
441 @subsubheading Fetching new branches from git.sv.gnu.org
443 To fetch and check out a new branch named @code{@var{branch}} on
444 git.sv.gnu.org, run from top of the Git repository
447 git config --add remote.origin.fetch +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
448 git checkout --track -b @var{branch} origin/@var{branch}
451 After this, you can pull @code{@var{branch}} from git.sv.gnu.org with
457 Note that this command generally fetches all branches you added with
458 @command{git remote add} (when you initialized the repository) or
459 @command{git config --add}, i.e. it updates all remote branches from
460 remote @code{origin}, then it merges the remote branch tracked by
461 current branch into current branch. For example, if your current
462 branch is @code{master} --- which is the case if you got the sources
463 with the commands described in @ref{Main source code} and did not
464 issue any @command{git checkout} command --- @code{origin/master} will
465 be merged into @code{master}.
468 @subsubheading Local clones, or having several working trees
470 If you play with several Git branches, e.g. @code{master},
471 @code{lilypond/translation}, @code{stable/2.12}), you may want to have
472 one source and build tree for each branch; this is possible with
473 subdirectories of your local Git repository, used as local cloned
474 subrepositories. To create a local clone for the branch named
475 @code{@var{branch}}, run
478 git checkout @var{branch}
479 git clone -l -s -n . @var{subdir}
484 Note that @code{@var{subdir}} must be a directory name which does not
485 already exist. In @code{@var{subdir}}, you can use all Git commands
486 to browse revisions history, commit and uncommit changes; to update
487 the cloned subrepository with changes made on the main repository, cd
488 into @code{@var{subdir}} and run @command{git pull}; to send changes
489 made on the subrepository back to the main repository, run
490 @command{git push} from @code{@var{subdir}}. Note that only one
491 branch (the currently checked out branch) is created in the
492 subrepository by default; it is possible to have several branches in a
493 subrepository and do usual operations (checkout, merge, create,
494 delete...) on these branches, but this possibility is not detailed
497 When you push @code{@var{branch}} from @code{@var{subdir}} to the main
498 repository, and @code{@var{branch}} is checked out in the main
499 repository, you must save uncommitted changes (see @command{git
500 stash}) and do @command{git reset --hard} in the main repository in
501 order to apply pushed changes in the working tree of the main
509 The commands above don't only bring you the latest version of the
510 sources, but also the full history of revisions (revisons, also
511 called commits, are changes made to the sources), stored in the
512 .git directory. You can browse this history with
515 git log # only shows the logs (author, committish and commit message)
516 git log -p # also shows diffs
517 gitk # shows history graphically
520 @warning{The @code{gitk} command may require a separate @code{gitk} package,
521 available in the appropriate distribution's repositories.}
523 @node Applying git patches
524 @subsection Applying git patches
526 Well-formed git patches should be committed with
532 Patches created without @code{git format-patch} should be
542 @section Git on Windows
544 @c Some of this may duplicate stuff in other sections
545 @c Clear this up later -td
547 @subsection Background to nomenclature
549 Git is a system for tracking the changes made to source files by
550 a distributed set of editors. It is designed to work without a
551 master repository, but we have chosen to have a master respository
552 for LilyPond files. Editors hold local copies of the master
553 repository together with any changes they have made locally. Local
554 changes are held in a local @q{branch}, of which there may be
555 several, but these instructions assume you are using just one. The
556 files visible in the local repository always correspond to those
557 on the currently @q{checked out} local branch.
559 Files are edited on a local branch, and in that state the
560 changes are said to be @q{unstaged}. When editing is complete, the
561 changes are moved to being @q{staged for commit}, and finally the
562 changes are @q{committed} to the local branch. Once
563 committed, the changes are given a unique reference number called the
564 @q{Committish} which identifies them to Git. Such committed changes
565 can be sent to the master repository by @q{pushing} them (if you
566 have write permission) or by sending them by email to someone who
567 has, either complete or as a @q{diff} or @q{patch} (which send
568 just the differences from master).
570 @subsection Installing git
573 @uref{http://code.google.com/p/msysgit/downloads/list}.
574 (Note, not msysGit, which is for Git developers) and
577 Start Git by clicking on the desktop icon.
578 This will bring up a command line bash shell. This may be
579 unfamiliar to Windows users. If so, follow these
580 instructions carefully. Commands are entered at a $ prompt
581 and are terminated by keying a newline.
583 @subsection Initialising Git
585 Decide where you wish to place your local Git repository,
586 creating the folders in Windows as necessary. Here we
587 call the folder to contain the repository [path]/Git.
588 You will need to have space for around 150Mbytes.
590 In the git bash shell type
596 to position the shell at your new Git repository.
598 Note: if [path] contains folders with names containing
611 to initialize your Git repository.
613 Then type (all on one line; the shell will wrap automatically)
616 git remote add -f -t master origin git://git.sv.gnu.org/lilypond.git
619 to download the lilypond master files.
621 @warning{Be patient! Even on a broadband connection this can take
622 10 minutes or more. Wait for lots of [new tag] messages
625 We now need to generate a local copy of the downloaded files
626 in a new local branch. Your local branch needs to have a
627 name, here we call it @q{lily-local} - you may wish to make up
633 git checkout -b lily-local origin/master
636 to create the lily-local branch containing the local copies of the
637 master files. You will be advised your local branch has been set
638 up to track the remote branch.
640 Return to Windows Explorer and look in your Git repository. You
641 should see lots of folders. For example, the LilyPond documentation
642 can be found in Git/Documentation/user.
644 Terminate the Git bash shell by typing @code{exit}.
648 Almost all subsequent work will use the Git Graphical User
649 Interface, which avoids having to type command line
650 commands. To start Git GUI first start the Git bash shell by
651 clicking on the desktop icon, and type
658 The Git GUI will open in a new window. It contains four panels
659 and 7 pull-down menus. At this stage do not use any of the
660 commands under Branch, Commit, Merge or Remote. These will
663 The two panels on the left contain the names of files which
664 you are in the process of editing (Unstaged Changes), and
665 files you have finished editing and have staged ready for
666 committing (Staged Changes). At this stage these panels will
667 be empty as you have not yet made any changes to any file.
668 After a file has been edited and saved the top panel on the right
669 will display the differences between the edited file selected
670 in one of the panels on the left and the last version committed.
672 The final panel at bottom right is used to enter a descriptive
673 message about the change before committing it.
675 The Git GUI is terminated by entering CNTL-Q while it is the
676 active window or by clicking on the usual Windows close-window
679 @subsection Personalising your local git repository
681 Open the Git GUI, click on
687 and enter your name and email address in the
688 left-hand (Git Repository) panel. Leave everything
689 else unchanged and save it.
691 @subsection Checking out a branch
693 At this stage you have two branches in your local repository,
694 both identical. To see them click on
700 You should have one local branch called @w{lily-local} and one
701 tracking branch called @w{origin/master}. The latter is your
702 local copy of the @w{remote/origin/master} branch in the master
703 LilyPond repository. The @w{lily-local} branch is where you
704 will make your local changes.
706 When a particular branch is selected, i.e., checked out, the
707 files visible in your repository are changed to reflect the
708 state of the files on that branch.
710 @subsection Updating files from @w{remote/origin/master}
712 Before starting the editing of a file, ensure your local branches
713 contain the latest version in @w{remote/origin/master} by first
717 Remote -> Fetch from -> origin
723 This will place the latest version of every file, including all the
724 changes made by others,
725 into the @q{origin/master} branch of the tracking branches
726 in your git repository. You can see these files by checking
727 out this branch. This will not affect any files you have
728 modified in your local branch.
730 You then need to merge these fetched files into your local
731 branch by clicking on
738 and if necessary select the local branch into which the merge
741 Note that a merge cannot be completed if there are any local
742 uncommitted changes on the lily-local branch.
744 This will update all the files in that branch to reflect the
745 current state of the @w{origin/master} branch. If any of the
746 changes conflict with changes you have made yourself recently
747 you will be notified of the conflict (see below).
749 @subsection Editing files
751 First ensure your lily-local branch is checked out, then
752 simply edit the files in your local Git repository with your
753 favourite editor and save them back there. If any file contains
754 non-ASCII characters ensure you save it in UTF-8 format. Git will
755 detect any changes whenever you restart Git GUI and the file names
756 will then be listed in the Unstaged Changes panel.
757 Or you can click the Rescan button to refresh the panel
758 contents at any time. You may break off and resume at
761 The changes you have made may be displayed in diff form
762 in the top right-hand panel by clicking on the name in
765 When your editing is complete, move the files from being
766 Unstaged to Staged by clicking the document symbol to
767 the left of each name. If you change your mind it can
768 be moved back by clicking on the ticked box to the
771 Finally the changes you have made may be committed to
772 your lily-local branch by entering a brief message in
773 the Commit Message box and clicking the Commit button.
775 If you wish to amend your changes after a commit has been
776 made, the original version and the changes you made in that
777 commit may be recovered by selecting
780 Commit -> Amend Last Commit
784 or by checking the Amend Last Commit radio button at bottom left.
785 This will return the changes to the Staged state, so further
786 editing made be carried out within that commit. This must only be
787 done @emph{before} the changes have been Pushed or sent to your
788 mentor for Pushing - after that it is too late and corrections
789 have to be made as a separate commit.
792 @subsection Sending changes to remote/origin/master
794 If you do not have write access to @w{remote/origin/master} you will
795 need to send your changes by email to someone who does.
797 First you need to create a diff or patch file containing
798 your changes. To create this, the file must first be
799 committed. Then terminate the Git GUI. In the
800 git bash shell first cd to your Git repository with
806 if necessary, then produce the patch with
809 git format-patch origin
812 This will create a patch file for all the locally committed files
813 which differ from @w{origin/master}. The patch file can be found
814 in [path]/Git and will have a name formed from n and the commit
817 @subsection Resolving merge conflicts
819 As soon as you have committed a changed file your local
820 branch has diverged from @w{origin/master}, and will
821 remain diverged until your changes have been committed
822 in @w{remote/origin/master} and Fetched back into your
823 @w{origin/master}. Similarly, if a new commit has been made
824 to @w{remote/origin/master} by someone else and Fetched, your
825 lily-local branch is divergent. You can detect a divergent
826 branch by clicking on
829 Repository -> Visualise all branch history
832 This opens up a very useful new window called @q{gitk}.
833 Use this to browse all the commits made by others.
835 If the diagram at top left of the resulting window
836 does not show your branch's tag on the same node as
837 the @w{remote/origins/master} tag your branch has diverged from
838 @w{origin/master}. This is quite normal if files you have modified
839 yourself have not yet been Pushed to @w{remote/origin/master} and
840 Fetched, or if files modified and committed by others have been
841 Fetched since you last Merged @w{origin/master} into your lily-local
844 If a file being merged from @w{origin/master} differs from
845 one you have modified in a way that cannot be resolved
846 automatically by git, Merge will report a Conflict
847 which you must resolve by editing the file to create the
848 version you wish to keep.
850 This could happen if the person updating @w{remote/origin/master}
851 for you has added some changes of his own before
852 committing your changes to @w{remote/origin/master}, or if someone
853 else has changed the same file since you last
854 fetched the file from @w{remote/origin/master}.
856 Open the file in your editor and look for sections which
857 are delimited with ...
859 [to be completed when I next have a merge conflict to be
860 sure I give the right instructions -td]
863 @subsection Other actions
865 The instructions above describe the simplest way of using
866 git on Windows. Other git facilities which may usefully
867 supplement these include
871 @item Using multiple local branches (Create, Rename, Delete)
872 @item Resetting branches
873 @item Cherry-picking commits
874 @item Pushing commits to @w{remote/origin/master}
875 @item Using gitk to review history
879 Once familiarity with using git on Windows has been gained the
880 standard git manuals can be used to learn about these.