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 * Working with several Git branches::
13 * Sharing your changes::
14 * Other interesting Git commands::
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
96 tool. For more info, see @uref{http://lilypond.org/gub}. The git
100 http://github.com/janneke/gub
103 @item @code{dev/XYZ}:
104 These branches are for individual developers. They store code
105 which is not yet stable enough to be added to the @code{master}
108 @item @code{stable/XYZ}:
109 The branches are kept for archival reasons.
114 @node Other locations for git
115 @subsection Other locations for git
117 If you have difficulty connecting to most of the repositories
118 listed in earlier sections, try:
121 git://git.sv.gnu.org/lilypond.git
122 http://git.sv.gnu.org/r/lilypond.git
123 ssh://git.sv.gnu.org/srv/git/lilypond.git
126 Using HTTP protocol is slowest, so it is not recommended unless both
127 SSH and Git protocols fail, which happens e.g. if you connect to
128 internet through a router that filters out Git and/or SSH connections.
131 @node Git user configuration
132 @subsection Git user configuration
134 To configure git to automatically use your name and email address
135 for commits and patches,
138 git config --global user.name "MYNAME"
139 git config --global user.email myemail@@example.net
143 @node Updating the source code
144 @section Updating the source code
147 * Importance of updating::
149 * Resolving conflicts::
150 * Introduction to Git concepts::
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 hae 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 Introduction to Git concepts
193 @subsection Introduction to Git concepts
195 A bit of Git vocabulary will be explained below. The following is
196 just introduction material; for better understanding of Git concepts,
197 you are invited to read further documentation, especially Git
198 Community Book at @uref{http://book.git-scm.com/}.
200 The @code{git pull origin} command above is just a shortcut for this
204 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
208 where @code{@var{branch}} is typically @code{master}, @code{web} or
209 @code{lilypond/translation}; if you do not know or remember, see
210 @ref{Getting the source code} to remember which commands you issued or
211 which source code you wanted to get.
213 A @emph{commit} is a set of changes made to the sources; it also
214 includes the committish of the parent commit, the name and e-mail of
215 the @emph{author} (the person who wrote the changes), the name and
216 e-mail of the @emph{committer} (the person who brings these changes
217 into the Git repository), and a commit message.
219 A @emph{committish} is the SHA1 checksum of a commit, a number made of
220 40 hexadecimal digits, which acts as the internal unique identifier
221 for this commit. To refer to a particular revision, don't use vague
222 references like the (approximative) date, simply copy and paste the
225 A @emph{branch} is nothing more than a pointer to a particular commit,
226 which is called the @emph{head} of the branch; when referring to a
227 branch, one often acutally thinks about its head and the ancestor
230 Now we will explain the two last commands you used to get the source
231 code from Git -- see @ref{Getting the source code}.
234 git remote add -f -t @var{branch} -m @var{branch} origin git://git.sv.gnu.org/lilypond.git/
235 git checkout -b @var{branch} origin/@var{branch}
238 The @command{git remote} has created a branch called
239 @code{origin/@var{branch}} in your local Git repository. As this
240 branch is a copy of the remote branch web from git.sv.gnu.org LilyPond
241 repository, it is called a @emph{remote branch}, and is meant to track
242 the changes on the branch from git.sv.gnu.org: it will be updated
243 every time you run @command{git pull origin} or @command{git fetch
246 The @command{git checkout} command has created a branch named
247 @code{@var{branch}}. At the beginning, this branch is identical to
248 @code{origin/@var{branch}}, but it will differ as soon as you make
249 changes, e.g. adding newly translated pages or editing some
250 documentation or code source file. Whenever you pull, you merge the
251 changes from @code{origin/@var{branch}} and @code{@var{branch}} since
252 the last pulling. If you do not have push (i.e. @qq{write}) access on
253 git.sv.gnu.org, your @code{@var{branch}} will always differ from
254 @code{origin/@var{branch}}. In this case, remember that other people
255 working like you with the remote branch @code{@var{branch}} of
256 git://git.sv.gnu.org/lilypond.git/ (called @code{origin/@var{branch}}
257 on your local repository) know nothing about your own
258 @code{@var{branch}}: this means that whenever you use a committish or
259 make a patch, others expect you to take the latest commit of
260 @code{origin/@var{branch}} as a reference.
262 Finally, please remember to read the man page of every Git command you
263 will find in this manual in case you want to discover alternate
264 methods or just understand how it works.
267 @node Working with several Git branches
268 @section Working with several Git branches
270 It is possible to work with several branches on the same local Git
271 repository; this is especially useful for translators who may have to
272 deal with both @code{lilypond/translation} and a stable branch,
273 e.g. @code{stable/2.12}.
275 Some Git commands are introduced first, then a workflow with several
276 Git branches of LilyPond source code is presented.
279 * Git commands for managing several branches::
280 * Working on LilyPond sources with several branches::
283 @node Git commands for managing several branches
284 @subsection Git commands for managing several branches
286 @subsubheading Listing branches and remotes
288 You can get the exact path or URL of all remotes with
295 To list Git branches on your local repositories, run
298 git branch # list local branches only
299 git branch -r # list remote branches
300 git branch -a # list all branches
304 @subsubheading Checking out branches
306 To know the currently checked out branch, i.e. the branch whose source
307 files are present in your working tree, read the first line of the
315 The currently checked out branch is also marked with an asterisk in
316 the output of @command{git branch}.
318 You can check out another branch @code{@var{other_branch}}, i.e. check
319 out @code{@var{other_branch}} to the working tree, by running
322 git checkout @var{other_branch}
325 Note that it is possible to check out another branch while having
326 uncommitted changes, but it is not recommended unless you know what
327 you are doing; it is recommended to run @command{git status} to check
328 this kind of issue before checking out another branch.
331 @subsubheading Merging branches
333 To merge branch @code{@var{foo}} into branch @code{@var{bar}}, i.e. to
334 @qq{add} all changes made in branch @code{@var{foo}} to branch
335 @code{@var{bar}}, run
338 git checkout @var{bar}
342 If any conflict happens, see @ref{Resolving conflicts}.
344 There are common usage cases for merging: as a translator, you will
345 often want to merge @code{master} into @code{lilypond/translation}; on
346 the other hand, the Translations meister wants to merge
347 @code{lilypond/translation} into @code{master} whenever he has checked
348 that @code{lilypond/translation} builds successfully.
351 @node Working on LilyPond sources with several branches
352 @subsection Working on LilyPond sources with several branches
354 @subsubheading Fetching new branches from git.sv.gnu.org
356 To fetch and check out a new branch named @code{@var{branch}} on
357 git.sv.gnu.org, run from top of the Git repository
360 git config --add remote.origin.fetch +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
361 git checkout --track -b @var{branch} origin/@var{branch}
364 After this, you can pull @code{@var{branch}} from git.sv.gnu.org with
370 Note that this command generally fetches all branches you added with
371 @command{git remote add} (when you initialized the repository) or
372 @command{git config --add}, i.e. it updates all remote branches from
373 remote @code{origin}, then it merges the remote branch tracked by
374 current branch into current branch. For example, if your current
375 branch is @code{master} --- which is the case if you got the sources
376 with the commands described in @ref{Main source code} and did not
377 issue any @command{git checkout} command --- @code{origin/master} will
378 be merged into @code{master}.
381 @subsubheading Local clones, or having several working trees
383 If you play with several Git branches, e.g. @code{master},
384 @code{lilypond/translation}, @code{stable/2.12}), you may want to have
385 one source and build tree for each branch; this is possible with
386 subdirectories of your local Git repository, used as local cloned
387 subrepositories. To create a local clone for the branch named
388 @code{@var{branch}}, run
391 git checkout @var{branch}
392 git clone -l -s -n . @var{subdir}
397 Note that @code{@var{subdir}} must be a directory name which does not
398 already exist. In @code{@var{subdir}}, you can use all Git commands
399 to browse revisions history, commit and uncommit changes; to update
400 the cloned subrepository with changes made on the main repository, cd
401 into @code{@var{subdir}} and run @command{git pull}; to send changes
402 made on the subrepository back to the main repository, run
403 @command{git push} from @code{@var{subdir}}. Note that only one
404 branch (the currently checked out branch) is created in the
405 subrepository by default; it is possible to have several branches in a
406 subrepository and do usual operations (checkout, merge, create,
407 delete...) on these branches, but this possibility is not detailed
410 When you push @code{@var{branch}} from @code{@var{subdir}} to the main
411 repository, and @code{@var{branch}} is checked out in the main
412 repository, you must save uncommitted changes (see @command{git
413 stash}) and do @command{git reset --hard} in the main repository in
414 order to apply pushed changes in the working tree of the main
418 @node Sharing your changes
419 @section Sharing your changes
422 * Producing a patch::
423 * Committing directly::
427 @node Producing a patch
428 @subsection Producing a patch
430 Once you have finished editing your files, checked that your changes
431 meet the @ref{Code style}, and/or @ref{Documentation policy}, properly
432 set up your name and email in @ref{Git user configuration}, and
433 checked that the entire thing compiles, you may
437 git-format-patch HEAD
440 Send an email to @email{lilypond-devel@@gnu.org} with the diff as
444 @node Committing directly
445 @subsection Committing directly
447 Most contributors do not have permission to commit directly. If you
448 do, make sure you have set up your name and email in @ref{Git user
449 configuration}, then edit @file{.git/config}: change the line
452 url = git://git.sv.gnu.org/lilypond.git/
458 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
462 where @var{user} is your login name on Savannah.
464 If you have not already done so, you should generate and upload a SSH
465 key: open @uref{https://savannah.gnu.org/my/} in your browser, then go to
466 @q{Preferences} then to something like @q{Edit SSH Keys}, and follow
467 the instructions on that page.
476 @node Other interesting Git commands
477 @section Other interesting Git commands
481 * Applying git patches::
488 The commands above don't only bring you the latest version of the
489 sources, but also the full history of revisions (revisons, also
490 called commits, are changes made to the sources), stored in the
491 .git directory. You can browse this history with
494 git log # only shows the logs (author, committish and commit message)
495 git log -p # also shows diffs
496 gitk # shows history graphically
499 @warning{The @code{gitk} command may require a separate @code{gitk} package,
500 available in the appropriate distribution's repositories.}
502 @node Applying git patches
503 @subsection Applying git patches
505 Well-formed git patches should be committed with
511 Patches created without @code{git-format-patch} should be
521 @section Git on Windows
523 @c Some of this may duplicate stuff in other sections
524 @c Clear this up later -td
526 @subsection Background to nomenclature
528 Git is a system for tracking the changes made to source files by
529 a distributed set of editors. It is designed to work without a
530 master repository, but we have chosen to have a master respository
531 for LilyPond files. Editors hold local copies of the master
532 repository together with any changes they have made locally. Local
533 changes are held in a local @q{branch}, of which there may be
534 several, but these instructions assume you are using just one. The
535 files visible in the local repository always correspond to those
536 on the currently @q{checked out} local branch.
538 Files are edited on a local branch, and in that state the
539 changes are said to be @q{unstaged}. When editing is complete, the
540 changes are moved to being @q{staged for commit}, and finally the
541 changes are @q{committed} to the local branch. Once
542 committed, the changes are given a unique reference number called the
543 @q{Committish} which identifies them to Git. Such committed changes
544 can be sent to the master repository by @q{pushing} them (if you
545 have write permission) or by sending them by email to someone who
546 has, either complete or as a @q{diff} or @q{patch} (which send
547 just the differences from master).
549 @subsection Installing git
552 @uref{http://code.google.com/p/msysgit/downloads/list}.
553 (Note, not msysGit, which is for Git developers) and
556 Start Git by clicking on the desktop icon.
557 This will bring up a command line bash shell. This may be
558 unfamiliar to Windows users. If so, follow these
559 instructions carefully. Commands are entered at a $ prompt
560 and are terminated by keying a newline.
562 @subsection Initialising Git
564 Decide where you wish to place your local Git repository,
565 creating the folders in Windows as necessary. Here we
566 call the folder to contain the repository [path]/Git.
567 You will need to have space for around 150Mbytes.
569 In the git bash shell type
575 to position the shell at your new Git repository.
577 Note: if [path] contains folders with names containing
590 to initialize your Git repository.
592 Then type (all on one line; the shell will wrap automatically)
595 git remote add -f -t master origin git://git.sv.gnu.org/lilypond.git
598 to download the lilypond master files.
600 @warning{Be patient! Even on a broadband connection this can take
601 10 minutes or more. Wait for lots of [new tag] messages
604 We now need to generate a local copy of the downloaded files
605 in a new local branch. Your local branch needs to have a
606 name, here we call it @q{lily-local} - you may wish to make up
612 git checkout -b lily-local origin/master
615 to create the lily-local branch containing the local copies of the
616 master files. You will be advised your local branch has been set
617 up to track the remote branch.
619 Return to Windows Explorer and look in your Git repository. You
620 should see lots of folders. For example, the LilyPond documentation
621 can be found in Git/Documentation/user.
623 Terminate the Git bash shell by typing @code{exit}.
627 Almost all subsequent work will use the Git Graphical User
628 Interface, which avoids having to type command line
629 commands. To start Git GUI first start the Git bash shell by
630 clicking on the desktop icon, and type
637 The Git GUI will open in a new window. It contains four panels
638 and 7 pull-down menus. At this stage do not use any of the
639 commands under Branch, Commit, Merge or Remote. These will
642 The two panels on the left contain the names of files which
643 you are in the process of editing (Unstaged Changes), and
644 files you have finished editing and have staged ready for
645 committing (Staged Changes). At this stage these panels will
646 be empty as you have not yet made any changes to any file.
647 After a file has been edited and saved the top panel on the right
648 will display the differences between the edited file selected
649 in one of the panels on the left and the last version committed.
651 The final panel at bottom right is used to enter a descriptive
652 message about the change before committing it.
654 The Git GUI is terminated by entering CNTL-Q while it is the
655 active window or by clicking on the usual Windows close-window
658 @subsection Personalising your local git repository
660 Open the Git GUI, click on
666 and enter your name and email address in the
667 left-hand (Git Repository) panel. Leave everything
668 else unchanged and save it.
670 @subsection Checking out a branch
672 At this stage you have two branches in your local repository,
673 both identical. To see them click on
679 You should have one local branch called @w{lily-local} and one
680 tracking branch called @w{origin/master}. The latter is your
681 local copy of the @w{remote/origin/master} branch in the master
682 LilyPond repository. The @w{lily-local} branch is where you
683 will make your local changes.
685 When a particular branch is selected, i.e., checked out, the
686 files visible in your repository are changed to reflect the
687 state of the files on that branch.
689 @subsection Updating files from @w{remote/origin/master}
691 Before starting the editing of a file, ensure your local branches
692 contain the latest version in @w{remote/origin/master} by first
696 Remote -> Fetch from -> origin
702 This will place the latest version of every file, including all the
703 changes made by others,
704 into the @q{origin/master} branch of the tracking branches
705 in your git repository. You can see these files by checking
706 out this branch. This will not affect any files you have
707 modified in your local branch.
709 You then need to merge these fetched files into your local
710 branch by clicking on
717 and if necessary select the local branch into which the merge
720 Note that a merge cannot be completed if there are any local
721 uncommitted changes on the lily-local branch.
723 This will update all the files in that branch to reflect the
724 current state of the @w{origin/master} branch. If any of the
725 changes conflict with changes you have made yourself recently
726 you will be notified of the conflict (see below).
728 @subsection Editing files
730 First ensure your lily-local branch is checked out, then
731 simply edit the files in your local Git repository with your
732 favourite editor and save them back there. If any file contains
733 non-ASCII characters ensure you save it in UTF-8 format. Git will
734 detect any changes whenever you restart Git GUI and the file names
735 will then be listed in the Unstaged Changes panel.
736 Or you can click the Rescan button to refresh the panel
737 contents at any time. You may break off and resume at
740 The changes you have made may be displayed in diff form
741 in the top right-hand panel by clicking on the name in
744 When your editing is complete, move the files from being
745 Unstaged to Staged by clicking the document symbol to
746 the left of each name. If you change your mind it can
747 be moved back by clicking on the ticked box to the
750 Finally the changes you have made may be committed to
751 your lily-local branch by entering a brief message in
752 the Commit Message box and clicking the Commit button.
754 If you wish to amend your changes after a commit has been
755 made, the original version and the changes you made in that
756 commit may be recovered by selecting
759 Commit -> Amend Last Commit
763 or by checking the Amend Last Commit radio button at bottom left.
764 This will return the changes to the Staged state, so further
765 editing made be carried out within that commit. This must only be
766 done @emph{before} the changes have been Pushed or sent to your
767 mentor for Pushing - after that it is too late and corrections
768 have to be made as a separate commit.
771 @subsection Sending changes to remote/origin/master
773 If you do not have write access to @w{remote/origin/master} you will
774 need to send your changes by email to someone who does.
776 First you need to create a diff or patch file containing
777 your changes. To create this, the file must first be
778 committed. Then terminate the Git GUI. In the
779 git bash shell first cd to your Git repository with
785 if necessary, then produce the patch with
791 where n an integer, normally 1. This will create a
792 patch file for all the locally committed files which differ
793 from @w{origin/master}. The patch file can be found in
794 [path]/Git and will have a name formed from n and the
797 @subsection Resolving merge conflicts
799 As soon as you have committed a changed file your local
800 branch has diverged from @w{origin/master}, and will
801 remain diverged until your changes have been committed
802 in @w{remote/origin/master} and Fetched back into your
803 @w{origin/master}. Similarly, if a new commit has been made
804 to @w{remote/origin/master} by someone else and Fetched, your
805 lily-local branch is divergent. You can detect a divergent
806 branch by clicking on
809 Repository -> Visualise all branch history
812 This opens up a very useful new window called @q{gitk}.
813 Use this to browse all the commits made by others.
815 If the diagram at top left of the resulting window
816 does not show your branch's tag on the same node as
817 the @w{remote/origins/master} tag your branch has diverged from
818 @w{origin/master}. This is quite normal if files you have modified
819 yourself have not yet been Pushed to @w{remote/origin/master} and
820 Fetched, or if files modified and committed by others have been
821 Fetched since you last Merged @w{origin/master} into your lily-local
824 If a file being merged from @w{origin/master} differs from
825 one you have modified in a way that cannot be resolved
826 automatically by git, Merge will report a Conflict
827 which you must resolve by editing the file to create the
828 version you wish to keep.
830 This could happen if the person updating @w{remote/origin/master}
831 for you has added some changes of his own before
832 committing your changes to @w{remote/origin/master}, or if someone
833 else has changed the same file since you last
834 fetched the file from @w{remote/origin/master}.
836 Open the file in your editor and look for sections which
837 are delimited with ...
839 [to be completed when I next have a merge conflict to be
840 sure I give the right instructions -td]
843 @subsection Other actions
845 The instructions above describe the simplest way of using
846 git on Windows. Other git facilities which may usefully
847 supplement these include
851 @item Using multiple local branches (Create, Rename, Delete)
852 @item Resetting branches
853 @item Cherry-picking commits
854 @item Pushing commits to @w{remote/origin/master}
855 @item Using gitk to review history
859 Once familiarity with using git on Windows has been gained the
860 standard git manuals can be used to learn about these.