1 @c -*- coding: utf-8; mode: texinfo; -*-
4 @node Working with source code
5 @chapter Working with source code
7 @warning{New contributors should read @ref{Quick start}, and in
8 particular @ref{lily-git}, instead of this chapter.}
10 Advanced contributors will find this material quite useful,
11 particularly if they are working on major new features.
14 * Manually installing lily-git.tcl::
16 * Basic Git procedures::
17 * Advanced Git procedures::
19 * Repository directory structure::
20 * Other Git documentation::
24 @node Manually installing lily-git.tcl
25 @section Manually installing lily-git.tcl
27 We have created an easy-to-use GUI to simplify git for new
28 contributors. If you are comfortable with the command-line, then
29 skip ahead to @ref{Starting with Git}.
31 @warning{These instructions are only for people who are @emph{not}
34 @c there's some duplication in this section with stuff covered in
35 @c Quick Start, but moving it into a macro inside included/ would
36 @c be getting a bit icky. -gp
40 If you haven't already, download and install Git.
44 @item Windows users: download the @code{.exe} file labeled
45 @qq{Full installer for official Git} from:
48 @uref{http://code.google.com/p/msysgit/downloads/list}
51 @item Other operating systems: either install @command{git} with
52 your package manager, or download it from the @qq{Binaries}
56 @uref{http://git-scm.com/download}
63 Download the @command{lily-git.tcl} script from:
65 @c don't change the cgit link below to gitweb; gitweb uses
66 @c long filenames like "scripts_auxiliar_lily-git.tcl"
69 @uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
73 To run the program from the command line, navigate to the
74 directory containing @command{lily-git.tcl} and enter:
81 Click on the @qq{Get source} button.
83 This will create a directory called @file{lilypond-git/} within
84 your home directory, and will download the source code into that
85 directory (around 150@tie{}Mb). When the process is finished, the
86 @qq{Command output} window will display @qq{Done}, and the button
87 label will change to say @qq{Update source}.
90 Navigate to the @file{lilypond-git/} directory to view the source
95 @warning{Throughout the rest of this manual, most command-line
96 input should be entered from @file{$LILYPOND_GIT}. This is
97 referred to as the @emph{top source directory}.}
99 Further instructions are in @ref{How to use lily-git}.
102 @node Starting with Git
103 @section Starting with Git
105 Using the Git program directly (as opposed to using the
106 @command{lily-git.tcl} GUI) allows you to have much greater control
107 over the contributing process. You should consider using Git if
108 you want to work on complex projects, or if you want to work on
109 multiple projects concurrently.
114 * Git for the impatient::
115 * Other repositories::
116 * Downloading remote branches::
121 @subsection Setting up
123 @warning{These instructions assume that you are using the
124 command-line version of Git 1.7 or higher.}
128 * Initializing a repository::
134 @unnumberedsubsubsec Installing Git
136 If you are using a Unix-based machine, the easiest way to download
137 and install Git is through a package manager such as @command{rpm}
138 or @command{apt-get} -- the installation is generally automatic.
139 The only required package is (usually) called @command{git-core},
140 although some of the auxiliary @command{git@var{*}} packages are
141 also useful (such as @command{gitk}).
143 Alternatively, you can visit the Git website
144 (@uref{http://git-scm.com/}) for downloadable binaries and
148 @node Initializing a repository
149 @unnumberedsubsubsec Initializing a repository
151 Once Git is installed, get a copy of the source code:
154 git clone git://git.sv.gnu.org/lilypond.git ~/lilypond-git
157 The above command will put the it in @file{~/lilypond-git}, where
158 @code{~} represents your home directory.
160 @subsubheading Technical details
162 This creates (within the @file{$LILYPOND_GIT} directory) a
163 subdirectory called @file{.git/}, which Git uses to keep track of
164 changes to the repository, among other things. Normally you don't
165 need to access it, but it's good to know it's there.
168 @node Configuring Git
169 @unnumberedsubsubsec Configuring Git
171 @warning{Throughout the rest of this manual, all command-line
172 input should be entered from the top directory of the Git
173 repository being discussed (eg. @file{$LILYPOND_GIT}). This is
174 referred to as the @emph{top source directory}.}
176 Before working with the copy of the main LilyPond repository, you
177 should configure some basic settings with the
178 @command{git@tie{}config} command. Git allows you to set both
179 global and repository-specific options.
181 To configure settings that affect all repositories, use the
182 @option{--global} command line option. For example, the first
183 two options that you should always set are your @var{name} and
184 @var{email}, since Git needs these to keep track of commit
188 git config --global user.name "@var{John Smith}"
189 git config --global user.email @var{john@@example.com}
192 To configure Git to use colored output where possible, use:
195 git config --global color.ui auto
198 The text editor that opens when using @command{git@tie{}commit}
199 can also be changed. If none of your editor-related environment
200 variables are set ($GIT_EDITOR, $VISUAL, or $EDITOR), the default
201 editor is usually @command{vi} or @command{vim}. If you're not
202 familiar with either of these, you should probably change the
203 default to an editor that you know how to use. For example, to
204 change the default editor to @command{nano}, enter:
207 git config --global core.editor @var{nano}
210 Finally, and in some ways most importantly, let's make sure that
211 we know what branch we're on. If you're not using LilyDev, add
212 this to your @file{~/.bashrc}:
215 export PS1="\u@\h \w\$(__git_ps1)$ "
218 If you are not using LilyDev, you may need to install the
219 additional @code{git-completion} package, but it is definitely
223 @subsubheading Technical details
225 Git stores the information entered with
226 @command{git@tie{}config@tie{}--global} in the file
227 @file{.gitconfig}, located in your home directory. This file can
228 also be modified directly, without using
229 @command{git@tie{}config}. The @file{.gitconfig} file generated
230 by the above commands would look like this:
235 email = john@@example.com
242 Using the @command{git@tie{}config} command @emph{without} the
243 @option{--global} option configures repository-specific settings,
244 which are stored in the file @file{.git/config}. This file is
245 created when a repository is initialized (using
246 @command{git@tie{}init}), and by default contains these lines:
250 repositoryformatversion = 0
253 logallrefupdates = true
256 However, since different repository-specific options are
257 recommended for different development tasks, it is best to avoid
258 setting any now. Specific recommendations will be mentioned later
262 @node Git for the impatient
263 @subsection Git for the impatient
265 @advanced{The intent of this subsection is to get you working on lilypond as
266 soon as possible. If you want to learn about git, go read
267 @ref{Other Git documentation}.
269 Also, these instructions are designed to eliminate the most common
270 problems we have found in using git. If you already know git and
271 have a different way of working, great! Feel free to ignore the
272 advice in this subsection.}
275 Ok, so you've been using @command{lily-git.tcl} for a while, but
276 it's time to take the next step. Since our review process delays
277 patches by 60-120 hours, and you want to be able to work on other
278 stuff while your previous work is getting reviewed, you're going
279 to use @strong{branches}.
281 You can think of a branch as being a separate copy of the source
282 code. But don't worry about it.
284 @subsubheading Start work: make a new branch
286 Let's pretend you want to add a section to the Contributor's Guide
287 about using branches.
289 Start by updating the repository, then making a new branch. Call
290 the branch anything you want as long as the name starts with
291 @code{dev/}. Branch names that don't begin with @code{dev/} are
292 reserved for special things in lilypond.
296 git pull -r origin master
300 @subsubheading Switch to that branch
302 Nothing has happened to the files yet. Let's change into the new
303 branch. You can think of this as @qq{loading a file}, although in
304 this case it's really @qq{loading a directory and subdirectories
311 Your prompt now shows you that you're on the other branch:
314 gperciva@@LilyDev:~/lilypond-git (dev/cg)$
317 To be able to manage multiple lilypond issues at once, you'll need to switch
318 branches. You should have each lilypond issue on a separate branch.
319 Switching branches is easy:
323 git checkout origin/staging
324 git checkout origin/release/unstable
328 Branches that begin with @code{origin/} are part of the remote repository,
329 rather than your local repository, so when you check them out you get a
330 temporary local branch. You should never make changes directly on a
331 branch beginning with @code{origin/}. You get changes into the remote
332 repository by making them in local branches, and then pushing them to
333 @code{origin/staging} as described below.
335 @subsubheading Make your changes
337 Edit files, then commit them.
344 Remember how I said that switching to a branch was like
345 @qq{loading a directory}? Well, you've just @qq{saved a
346 directory}, so that you can @qq{load} it later.
348 @advanced{If you have used @command{cvs} or @command{svn}, you may
349 be very confused: those programs use @qq{commit} to mean
350 @qq{upload my changes to the shared source repository}.
351 Unfortunately, just to be different, @w{@command{git commit}}
352 means @qq{save my changes to the files}.}
354 When you create a new file, you need to add it to git, then commit it:
357 git add input/regression/avoid-crash-on-condition.ly
362 Edit more files. Commit them again. Edit yet more files, commit
363 them again. Go eat dinner. Switch to @code{master} so you can
364 play with the latest changes from other developers. Switch back
365 to your branch and edit some more. Commit those changes.
367 At this stage, don't worry about how many commits you have.
370 @subsubheading Save commits to external files
372 Branches are nerve-wracking until you get used to them. You can
373 save your hard work as individual @file{.patch} files. Be sure to
374 commit your changes first.
378 git format-patch master
381 I personally have between 4 and 20 of those files saved in a
382 special folder at any point in time. Git experts might laugh as
383 that behavior, but I feel a @emph{lot} better knowing that I've
387 @subsubheading Prepare your branch for review
389 After committing, you can update your branch with the latest master:
394 git pull -r origin master
400 Due to the speed of lilypond development, sometimes
401 @code{master} has changed so much that your branch can no
402 longer be applied to it. In that happens, you will have a merge
403 conflict. Stop for a moment to either cry or have a stiff drink,
404 then proceed to @ref{Merge conflicts}.
407 @subsubheading Upload your branch
409 Finally, you're finished your changes. Time to upload for review.
410 Make sure that you're on your branch, then upload:
418 @subsubheading Wait for reviews
420 While you're waiting for a countdown and reviews, go back to
421 master, make a @code{dev/doc-beams} branch, and start adding doc
422 suggestions from issue 12345 from the tracker. Or make a
423 @code{dev/page-breaks} and fix bug in page breaking. Or whatever.
424 Don't worry, your @code{dev/cg} is safe.
427 @subsubheading Combining commits (optional unless you have broken commits)
429 Does the history of your branch look good?
435 If you have a lot of commits on your branch, you might want to
436 combine some of them. Alternately, you may like your commits, but
437 want to edit the commit messages.
443 Follow instructions on the screen.
445 @warning{This step gives you the power to completely lose your
446 work. Make a backup of your commits by saving them to
447 @file{.patch} files before playing with this. If you do lose
448 your work, don't despair. You can get it back by using @code{git reflog}.
449 The use of @code{git reflog} is not covered here.}
451 @warning{If any of the commits on your branch represent partial work that will
452 not pass @var{make && make doc}, you @strong{must} squash these
453 commits into a working commit. Otherwise, your push will break staging
454 and will not be able to be merged to master. In general, you will
455 be safer to have one commit per push.}
458 @subsubheading Push to staging
460 When you've got the coveted @code{Patch-push} status, time to
465 git rebase origin/staging dev/cg~0
469 @warning{Do not skip the @command{gitk} step; a quick 5-second
470 check of the visual history can save a great deal of frustration
471 later on. You should see a set of your commits that are ahead of
472 @code{origin/staging}, with no label for the top commit -- only a
475 @warning{If @code{origin/staging} and @code{origin/master} are the
476 same commit, your branch (@code{dev/cg} in the example) will also
477 be at the top of the @code{gitk} tree. This is normal.}
479 If everything looks good, push it:
482 git push origin HEAD:staging
485 Then change back to your working branch:
491 @warning{It is a best practice to avoid rebasing any of your branches
492 to @code{origin/staging}. If @code{origin/staging} is broken, it
493 will be deleted and rebuilt. If you have rebased one of your branches
494 to @code{origin/staging}, the broken commits can end up in your branch.
495 The commands given above do the rebase on a temporary branch, and avoid
496 changing your working branch.}
499 @subsubheading Delete your branch (safe)
501 After a few hours, if there's nothing wrong with your branch, it
502 should be automatically moved to @code{origin/master}. Update,
503 then try removing your branch:
507 git pull -r origin master
511 The last command will fail if the contents of @code{dev/cg} are
512 not present in @code{origin/master}.
515 @subsubheading Delete your branch (UNSAFE)
517 @c don't give explicit commands here -- this is too dangerous to copy and paste
518 Sometimes everything goes wrong. If you want to remove a branch even though
519 it will cause your work to be lost (that is, if the contents of @code{dev/cg}
520 are @strong{not} present in master), follow the instructions in @qq{Delete
521 your branch (safe)}, but replace the @code{-d} on the final line with
525 @node Other repositories
526 @subsection Other repositories
528 We have a few other code repositories.
532 * Grand Unified Builder (GUB)::
534 * yet more repositories::
538 @unnumberedsubsubsec lilypond-extra
540 There is a separate repository for general administrative scripts,
541 as well as pictures and media files for the website. People
542 interested in working on the website should download this
543 repository, and set their @code{$LILYPOND_WEB_MEDIA_GIT}
544 environment variable to point to that repository.
547 @uref{https://github.com/gperciva/lilypond-extra}
550 To configure an environment variable in bash (the default for most
551 GNU/Linux distributions),
554 export LILYPOND_WEB_MEDIA_GIT=$HOME/dir/of/lilypond-extra/
557 Be aware that @code{lilypond-extra} is the definitive source for some binary
558 files - in particular PDF versions of papers concerning LilyPond. To add
559 further PDFs of this sort, all that is necessary is to add the PDF to
560 @code{lilypond-extra} and then add a reference to it in the documentation. The
561 file will then be copied to the website when @code{make website} is run.
563 However, pictures that are also used in the documentation build are mastered in
564 the main git repository. If any of these is changed, it should be updated in
565 git, and then the updates copied to @code{lilypond-extra}.
567 @node Grand Unified Builder (GUB)
568 @unnumberedsubsubsec Grand Unified Builder (GUB)
570 Another item of interest might be the Grand Unified Builder, our
571 cross-platform building tool. Since it is used by other projects as
572 well, it is not stored in our gub repository. For more info, see
573 @uref{http://lilypond.org/gub}.
575 There are two locations for this repository: the version being used to
576 build lilypond, which is at
579 @uref{http://github.com/gperciva/gub}
582 and the original version by Jan Nieuwenhuizen, kept at
585 @uref{http://github.com/janneke/gub}
590 @unnumberedsubsubsec lilypad
592 Our binary releases on MacOS X and Windows contain a lightweight
593 text editor. This code is here:
596 https://github.com/gperciva/lilypad
600 @node yet more repositories
601 @unnumberedsubsubsec yet more repositories
603 There are a few other repositories floating around, which will
604 hopefully be documented in the near future.
607 @node Downloading remote branches
608 @subsection Downloading remote branches
610 @warning{contains obsolete + misleading info}
613 * Organization of remote branches::
614 * LilyPond repository sources::
619 @node Organization of remote branches
620 @unnumberedsubsubsec Organization of remote branches
623 The main LilyPond repository is organized into @emph{branches} to
624 facilitate development. These are often called @emph{remote}
625 branches to distinguish them from @emph{local} branches you might
626 create yourself (see @ref{Using local branches}).
628 The @code{master} branch contains all the source files used to
629 build LilyPond, which includes the program itself (both stable and
630 development releases), the documentation (and its translations),
631 and the website. Generally, the @code{master} branch is expected
632 to compile successfully.
634 The @code{translation} branch is a side branch that
635 allows translators to work without needing to worry about
636 compilation problems. Periodically, the Translation Meister
637 (after verifying that it doesn't break compilation), will
638 @emph{merge} this branch into @code{staging} to incorporate
639 recent translations. Similarly, the @code{master} branch is
640 usually merged into the @code{translation} branch after
641 significant changes to the English documentation. See
642 @ref{Translating the documentation} for details.
645 @node LilyPond repository sources
646 @unnumberedsubsubsec LilyPond repository sources
649 The recommended source for downloading a copy of the main
653 git://git.sv.gnu.org/lilypond.git
656 However, if your internet router filters out connections using the
657 GIT protocol, or if you experience difficulty connecting via GIT,
658 you can try these other sources:
661 ssh://git.sv.gnu.org/srv/git/lilypond.git
662 http://git.sv.gnu.org/r/lilypond.git
665 The SSH protocol can only be used if your system is properly set
666 up to use it. Also, the HTTP protocol is slowest, so it should
667 only be used as a last resort.
671 @unnumberedsubsubsec Other branches
673 Most contributors will never need to touch the other branches. If
674 you wish to do so, you will need more familiarity with Git; please
675 see @ref{Other Git documentation}.
678 @item @code{dev/XYZ}:
679 These branches are for individual developers. They store code
680 which is not yet stable enough to be added to the @code{master}
683 @item @code{stable/XYZ}:
684 The branches are kept for archival reasons.
686 @item @code{archive/XYZ}:
687 The branches are kept for archival reasons.
692 @node Basic Git procedures
693 @section Basic Git procedures
697 * The Git contributor's cycle::
698 * Pulling and rebasing::
699 * Using local branches::
700 * Commits and patches::
704 @node The Git contributor's cycle
705 @subsection The Git contributor's cycle
708 Here is a simplified view of the contribution process on Git:
712 Update your local repository by @emph{pulling} the most recent
713 updates from the remote repository.
716 Edit source files within your local repository's @emph{working
720 @emph{Commit} the changes you've made to a local @emph{branch}.
723 Generate a @emph{patch} to share your changes with the developers.
727 @node Pulling and rebasing
728 @subsection Pulling and rebasing
731 When developers push new patches to the @code{git.sv.gnu.org}
732 repository, your local repository is @strong{not} automatically
733 updated. It is important to keep your repository up-to-date by
734 periodically @emph{pulling} the most recent @emph{commits} from
735 the remote branch. Developers expect patches to be as current as
736 possible, since outdated patches require extra work before they
739 Occasionally you may need to rework some of your own modifications
740 to match changes made to the remote branch (see @ref{Resolving
741 conflicts}), and it's considerably easier to rework things
742 incrementally. If you don't update your repository along the way,
743 you may have to spend a lot of time resolving branch conflicts and
744 reconfiguring much of the work you've already done.
746 Fortunately, Git is able to resolve certain types of branch
747 conflicts automatically with a process called @emph{rebasing}.
748 When rebasing, Git tries to modify your old commits so they appear
749 as new commits (based on the latest updates). For a more involved
750 explanation, see the @command{git-rebase} man page.
752 To pull without rebasing (recommended for translators), use the
756 git pull # recommended for translators
759 If you're tracking the remote @code{master} branch, you should add
760 the @option{-r} option (short for @option{--rebase}) to keep commits
761 on your local branch current:
764 git pull -r # use with caution when translating
767 If you don't edit translated documentation and don't want to type
768 @option{-r} every time, configure the master branch to rebase by
769 default with this command:
772 git config branch.master.rebase true
775 If pull fails because of a message like
778 error: Your local changes to 'Documentation/learning/tutorial.itely'
779 would be overwritten by merge. Aborting.
786 Documentation/learning/tutorial.itely: needs update
787 refusing to pull with rebase: your working tree is not up-to-date
791 it means that you have modified some files in you working tree
792 without committing changes (see @ref{Commits and patches}); you
793 can use the @command{git@tie{}stash} command to work around this:
796 git stash # save uncommitted changes
797 git pull -r # pull using rebase (translators omit "-r")
798 git stash pop # reapply previously saved changes
801 Note that @command{git@tie{}stash@tie{}pop} will try to apply a
802 patch, and this may create a conflict. If this happens, see
803 @ref{Resolving conflicts}.
805 TODO: I think the next paragraph is confusing. Perhaps prepare
806 the reader for new terms `committish' and `head'? -mp
808 @warning{translators and documentation editors, if you have
809 changed committishes in the head of translated files using commits
810 you have not yet pushed to @code{git.sv.gnu.org}, please do not
811 rebase. If you want to avoid wondering whether you should rebase
812 each time you pull, please always use committishes from master
813 and/or translation branch on @code{git.sv.gnu.org}, which
814 in particular implies that you must push your changes to
815 documentation except committishes updates (possibly after having
816 rebased), then update the committishes and push them.}
818 TODO: when committishes automatic conditional update have been
819 tested and documented, append the following to the warning above:
820 Note that using update-committishes make target generally touches
823 @subsubheading Technical details
825 The @command{git@tie{}config} command mentioned above adds the
826 line @code{rebase = true} to the master branch in your local
827 repository's @file{.git/config} file:
832 merge = refs/heads/master
837 @node Using local branches
838 @subsection Using local branches
842 * Creating and removing branches::
843 * Listing branches and remotes::
844 * Checking out branches::
849 @node Creating and removing branches
850 @unnumberedsubsubsec Creating and removing branches
853 Local branches are useful when you're working on several different
854 projects concurrently. To create a new branch, enter:
857 git branch @var{name}
860 To delete a branch, enter:
863 git branch -d @var{name}
866 Git will ask you for confirmation if it sees that data would be
867 lost by deleting the branch. Use @option{-D} instead of @option{-d}
868 to bypass this. Note that you cannot delete a branch if it is
869 currently checked out.
872 @node Listing branches and remotes
873 @unnumberedsubsubsec Listing branches and remotes
875 You can get the exact path or URL of all remote branches by
882 To list Git branches on your local repositories, run
885 git branch # list local branches only
886 git branch -r # list remote branches
887 git branch -a # list all branches
891 @node Checking out branches
892 @unnumberedsubsubsec Checking out branches
894 To know the currently checked out branch, i.e. the branch whose
895 source files are present in your working tree, read the first line
903 The currently checked out branch is also marked with an asterisk
904 in the output of @command{git branch}.
906 You can check out another branch @code{@var{other_branch}}, i.e.
907 check out @code{@var{other_branch}} to the working tree, by
911 git checkout @var{other_branch}
914 Note that it is possible to check out another branch while having
915 uncommitted changes, but it is not recommended unless you know
916 what you are doing; it is recommended to run @command{git status}
917 to check this kind of issue before checking out another branch.
919 @node Merging branches
920 @unnumberedsubsubsec Merging branches
922 To merge branch @code{@var{foo}} into branch @code{@var{bar}},
923 i.e. to @qq{add} all changes made in branch @code{@var{foo}} to
924 branch @code{@var{bar}}, run
927 git checkout @var{bar}
931 If any conflict happens, see @ref{Resolving conflicts}.
933 There are common usage cases for merging: as a translator, you will
934 often want the Translations meister to merge @code{master} into
935 @code{translation}; on the other hand, the Translations meister wants
936 to merge @code{translation} into @code{staging} whenever he has
937 checked that @code{translation} builds successfully.
940 @node Commits and patches
941 @subsection Commits and patches
945 * Understanding commits::
949 * Uploading a patch for review::
953 @node Understanding commits
954 @unnumberedsubsubsec Understanding commits
956 Technically, a @emph{commit} is a single point in the history of a
957 branch, but most developers use the term to mean a @emph{commit
958 object}, which stores information about a particular revision. A
959 single commit can record changes to multiple source files, and
960 typically represents one logical set of related changes (such as a
961 bug-fix). You can list the ten most recent commits in your
962 current branch with this command:
965 git log -10 --oneline
968 If you're using an older version of Git and get an @q{unrecognized
969 argument} error, use this instead:
972 git log -10 --pretty=oneline --abbrev-commit
975 More interactive lists of the commits on the remote @code{master}
976 branch are available at
977 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=shortlog} and
978 @uref{http://git.sv.gnu.org/cgit/lilypond.git/log/}.
982 @unnumberedsubsubsec Making commits
985 Once you have modified some source files in your working
986 directory, you can make a commit with the following procedure:
990 Make sure you've configured Git properly (see @ref{Configuring
991 Git}). Check that your changes meet the requirements described in
992 @ref{Code style} and/or @ref{Documentation policy}. For advanced
993 edits, you may also want to verify that the changes don't break
994 the compilation process.
997 Run the following command:
1004 to make sure you're on the right branch, and to see which files
1005 have been modified, added or removed, etc. You may need to tell
1006 Git about any files you've added by running one of these:
1009 git add @var{file} # add untracked @var{file} individually
1010 git add . # add all untracked files in current directory
1014 After @command{git@tie{}add}, run @command{git@tie{}status} again
1015 to make sure you got everything. You may also need to modify
1019 Preview the changes about to be committed (to make sure everything
1027 The @code{HEAD} argument refers to the most recent commit on the
1028 currently checked-out branch.
1031 Generate the commit with:
1038 The @option{-a} is short for @option{--all} which includes modified
1039 and deleted files, but only those newly created files that have
1040 previously been added.
1045 @node Commit messages
1046 @unnumberedsubsubsec Commit messages
1049 When you run the @command{git@tie{}commit@tie{}-a} command, Git
1050 automatically opens the default text editor so you can enter a
1051 @emph{commit message}. If you find yourself in a foreign editing
1052 environment, you're probably in @command{vi} or @command{vim}. If
1053 you want to switch to an editor you're more familiar with, quit by
1054 typing @code{:q!} and pressing @code{<Enter>}. See
1055 @ref{Configuring Git} for instructions on changing the default
1058 In any case, Git will open a text file for your commit message
1059 that looks like this:
1063 # Please enter the commit message for your changes. Lines starting
1064 # with '#' will be ignored, and an empty message aborts the commit.
1066 # Changes to be committed:
1067 # (use "git reset HEAD <file>..." to unstage)
1069 # modified: working.itexi
1073 Your commit message should begin with a one-line summary
1074 describing the change (no more than 50 characters long), and if
1075 necessary a blank line followed by several lines giving the
1078 @c $ git log -1 --pretty=medium 4d6f1e5
1080 Doc: add Baerenreiter and Henle solo cello suites
1082 Added comparison of solo cello suite engravings to new essay with
1083 high-res images, fixed cropping on Finale example.
1086 Commit messages often start with a short prefix describing the
1087 general location of the changes. If a commit affects the
1088 documentation in English (or in several languages simultaneously)
1089 the commit message should be prefixed with @qq{Doc:@tie{}}. If
1090 the commit affects only one of the translations, the commit
1091 message should be prefixed with @qq{Doc-@var{**}:@tie{}}, where
1092 @var{**} is the two-letter language code. Commits that affect the
1093 website should use @qq{Web:@tie{}} for English, and
1094 @qq{Web-@var{**}:@tie{}} for the other languages. Also, changes
1095 to a single file are often prefixed with the name of the file
1096 involved. Visit the links listed in @ref{Understanding commits}
1100 @node Making patches
1101 @unnumberedsubsubsec Making patches
1103 If you want to share your changes with other contributors and
1104 developers, you need to generate @emph{patches} from your commits.
1105 We prefer it if you follow the instructions in
1106 @ref{Uploading a patch for review}. However, we present an
1107 alternate method here.
1109 You should always run @command{git@tie{}pull@tie{}-r} (translators
1110 should leave off the @option{-r}) before doing this to ensure that
1111 your patches are as current as possible.
1113 Once you have made one or more commits in your local repository,
1114 and pulled the most recent commits from the remote branch, you can
1115 generate patches from your local commits with the command:
1118 git format-patch origin
1121 The @code{origin} argument refers to the remote tracking branch at
1122 @code{git.sv.gnu.org}. This command generates a separate patch
1123 for each commit that's in the current branch but not in the remote
1124 branch. Patches are placed in the current working directory and
1125 will have names that look something like this:
1128 0001-Doc-Fix-typos.patch
1129 0002-Web-Remove-dead-links.patch
1133 Send an email (must be less than 64 KB) to
1134 @email{lilypond-devel@@gnu.org} briefly explaining your work, with
1135 the patch files attached. Translators should send patches to
1136 @email{translations@@lilynet.net}. After your patches are
1137 reviewed, the developers may push one or more of them to the main
1138 repository or discuss them with you.
1141 @node Uploading a patch for review
1142 @unnumberedsubsubsec Uploading a patch for review
1144 Any non-trivial change should be uploaded to our @qq{Rietveld}
1145 code review website:
1148 @uref{http://codereview.appspot.com/}
1151 @subsubheading @command{git-cl} install
1153 LilyDev users should skip over these @q{install} instructions.
1158 Install @command{git-cl} by entering:
1161 git clone https://github.com/gperciva/git-cl.git
1164 If that command fails for some reason, try this instead:
1167 git clone git://github.com/gperciva/git-cl.git
1171 Add the @file{git-cl/} directory to your PATH,
1172 or create a symbolic link to the @command{git-cl}
1173 and @command{upload.py} scripts in one of your PATH
1174 directories (such as @file{$HOME/bin}).
1176 In Ubuntu (and LilyDev), you can add directories to PATH
1177 by adding this line to a hidden file @file{.bashrc},
1178 located in your home directory:
1181 PATH=~/type-here-directory-containing-git-cl:"$@{PATH@}"
1186 @subsubheading @command{git-cl} configuration
1188 LilyDev users should perform these @q{configuration} instructions.
1192 You must have a google account; please create one if you do not
1195 Note that a google account does not need to be a gmail account; you can
1196 use any email address for your google account when you sign up.
1199 Move into the top source directory and then configure @command{git
1200 cl} with the following commands:
1207 For the @qq{Rietveld server} question, the default value
1208 (@qq{codereview.appspot.com}) should be accepted by
1209 answering with a newline (CR).
1211 The @qq{CC list} question should be answered with:
1214 lilypond-devel@@gnu.org
1217 The @qq{Tree status URL} value should be left blank. So should
1218 the @qq{ViewVC URL} value, since it is used by @command{git cl
1219 dcommit} which is only for repositories which use @command{git
1220 svn} (LilyPond doesn't).
1224 @subsubheading Uploading patch set
1226 @warning{Unless you are familiar with branches, only work on one
1227 set of changes at once.}
1229 There are two methods, depending on your git setup.
1233 @strong{Master branch}: (easy option, and used in @command{lily-git.tcl})
1235 If you added your patch to @code{master}, then:
1239 git cl upload origin/master
1242 @c Mention staging here?
1243 If you have git push ability, make sure that you @emph{remove}
1244 your patch (with @command{git rebase} or @command{git reset})
1245 before pushing other stuff.
1247 @c don't make this one an @example; we don't want to make it easy
1248 @c for people to use this accidently
1249 Notifications of patches are automatically added to our issue
1250 tracker to reduce the chance of patches getting lost. To suppress
1251 this (not recommended), add the @code{-n / --no-code-issue}
1255 @strong{Separate branch}: (complicated option)
1257 Ensure your changes are committed in a separate branch, which
1258 should differ from the reference branch to be used by just the
1259 changes to be uploaded. If the reference branch is to be
1260 origin/master, ensure this is up-to-date. If necessary, use git
1261 rebase to rebase the branch containing the changes to the head of
1262 origin/master. Finally, check out branch with the changes and
1266 git cl upload <reference SHA1 ID>
1270 where <reference SHA1 ID> is the SHA1 ID of the commit to be used
1271 as a reference source for the patch. Generally, this will be the
1272 SHA1 ID of origin/master, and in that case the command:
1275 git cl upload origin/master
1283 First you will see a terminal editor where you can edit the
1284 message that will accompany your patch. @command{git-cl} will
1285 respect the @env{EDITOR} environment variable if defined,
1286 otherwise it will use @command{vi} as the default editor.
1288 After prompting for your Google email address and password, the
1289 patch set will be posted to Rietveld, and you will be given a URL
1292 @warning{Some installations of git-cl fail when uploading a patch
1293 with certain filename extensions. If this happens, it can
1294 generally be fixed by editing the list of exceptions at top of
1297 @subsubheading Announcing your patch set
1299 You should then announce the patch by logging into the code review
1300 issue webpage and using @qq{Publish + Mail Comments} to add a
1301 (mostly bogus) comment to your issue. The text of your comment
1302 will be sent to our developer mailing list.
1304 @warning{There is no automatic notification of a new patch; you
1305 must add a comment yourself.}
1307 @subsubheading Revisions
1309 As revisions are made in response to comments, successive patch sets
1310 for the same issue can be uploaded by reissuing the git-cl command
1311 with the modified branch checked out.
1313 Sometimes in response to comments on revisions, the best way to
1314 work may require creation of a new branch in git. In order to
1315 associate the new branch with an existing Rietveld issue,
1316 the following command can be used:
1319 git cl issue issue-number
1323 where @code{issue-number} is the number of the existing Rietveld
1326 @subsubheading Resetting git cl
1328 If @command{git cl} becomes confused, you can @qq{reset} it by
1335 @subsubheading Wait for a countdown
1337 Your patch will be available for reviews for the next few hours or
1338 days. Three times a week, patches with no known problems are
1339 gathered into a @qq{patch countdown} and their status changed to
1340 @code{patch-countdown}. The countdown is a 48-hour waiting period
1341 in which any final reviews or complaints should be made.
1343 During the countdown, your patch may be set to
1344 @code{patch-needs_work}, indicating that you should fix something
1345 (or at least discuss why the patch needs no modification). If no
1346 problems are found, the patch will be set to @code{patch-push}.
1348 Once a patch has @code{patch-push}, it should be sent to your
1349 mentor for uploading. If you have git push ability, look at
1350 @ref{Pushing to staging}.
1353 @node Advanced Git procedures
1354 @section Advanced Git procedures
1357 @warning{This section is not necessary for normal contributors;
1358 these commands are presented for information for people interested
1359 in learning more about git.}
1361 It is possible to work with several branches on the same local Git
1362 repository; this is especially useful for translators who may have
1363 to deal with both @code{translation} and a stable branch,
1364 e.g. @code{stable/2.12}.
1366 Some Git commands are introduced first, then a workflow with
1367 several Git branches of LilyPond source code is presented.
1372 * Advanced Git concepts::
1373 * Resolving conflicts::
1374 * Reverting all local changes::
1376 * Applying remote patches::
1377 * Sending and receiving patches via email::
1378 * Cleaning up multiple patches::
1380 * Pushing to staging::
1384 @node Merge conflicts
1385 @subsection Merge conflicts
1387 To be filled in later, and/or moved to a different section. I
1388 just wanted to make sure that I had a stub ready somewhere.
1391 @node Advanced Git concepts
1392 @subsection Advanced Git concepts
1395 A bit of Git vocabulary will be explained below. The following is
1396 only introductory; for a better understanding of Git concepts, you
1397 may wish to read @ref{Other Git documentation}.
1399 The @code{git@tie{}pull@tie{}origin} command above is just a
1400 shortcut for this command:
1403 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
1407 where @code{@var{branch}} is typically @code{master} or
1408 @code{translation}; if you do not know or remember, see
1409 @ref{Downloading remote branches} to remember which commands you
1410 issued or which source code you wanted to get.
1412 A @emph{commit} is a set of changes made to the sources; it also
1413 includes the committish of the parent commit, the name and e-mail
1414 of the @emph{author} (the person who wrote the changes), the name
1415 and e-mail of the @emph{committer} (the person who brings these
1416 changes into the Git repository), and a commit message.
1418 A @emph{committish} is the SHA1 checksum of a commit, a number
1419 made of 40 hexadecimal digits, which acts as the internal unique
1420 identifier for this commit. To refer to a particular revision,
1421 don't use vague references like the (approximative) date, simply
1422 copy and paste the committish.
1424 A @emph{branch} is nothing more than a pointer to a particular
1425 commit, which is called the @emph{head} of the branch; when
1426 referring to a branch, one often actually thinks about its head
1427 and the ancestor commits of the head.
1430 @node Resolving conflicts
1431 @subsection Resolving conflicts
1434 Occasionally an update may result in conflicts -- this happens
1435 when you and somebody else have modified the same part of the same
1436 file and git cannot figure out how to merge the two versions
1437 together. When this happens, you must manually merge the two
1440 If you need some documentation to understand and resolve
1441 conflicts, see paragraphs @emph{How conflicts are presented} and
1442 @emph{How to resolve conflicts} in @command{git merge} man page.
1444 If all else fails, you can follow the instructions in
1445 @ref{Reverting all local changes}. Be aware that this eliminates
1446 any changes you have made!
1449 @node Reverting all local changes
1450 @subsection Reverting all local changes
1452 Sometimes git will become hopelessly confused, and you just want
1453 to get back to a known, stable state. This command destroys any
1454 local changes you have made in the currently checked-out branch,
1455 but at least you get back to the current online version:
1458 git reset --hard origin/master
1466 The commands above don't only bring you the latest version of the
1467 sources, but also the full history of revisions (revisions, also
1468 called commits, are changes made to the sources), stored in the
1469 @file{.git} directory. You can browse this history with
1472 git log # only shows the logs (author, committish and commit message)
1473 git log -p # also shows diffs
1474 gitk # shows history graphically
1477 @warning{The @code{gitk} command may require a separate
1478 @code{gitk} package, available in the appropriate distribution's
1482 @node Applying remote patches
1483 @subsection Applying remote patches
1486 TODO: Explain how to determine if a patch was created with
1487 @code{git@tie{}format-patch}.
1489 Well-formed git patches created with @code{git@tie{}format-patch}
1490 should be committed with the following command:
1496 Patches created without @code{git@tie{}format-patch} can be
1497 applied in two steps. The first step is to apply the patch to the
1498 working tree and the index:
1501 git apply --index @var{patch}
1505 The second step is to commit the changes and give credit to the
1506 author of the patch. This can be done with the following command:
1509 git commit --author="@var{John Smith} <@var{john@@example.com}>"
1512 Please note that using the @code{--index} option for patching is quite
1513 important here and @emph{cannot} reliably be replaced by using the
1514 @code{-a} option when committing: that would only commit files from the
1515 working tree that are already registered with git, so every file that
1516 the patch actually @emph{adds}, like a regtest for a fixed bug, would
1517 get lost. For the same reason, you should not use the git-independent
1518 @samp{patch} program for applying patches.
1520 @node Sending and receiving patches via email
1521 @subsection Sending and receiving patches via email
1524 The default @code{x-diff} MIME type associated with patch files
1525 (i.e., files whose name ends in @code{.patch}) means that the
1526 encoding of line endings may be changed from UNIX to DOS format
1527 when they are sent as attachments. Attempting to apply such an
1528 inadvertently altered patch will cause git to fail with a message
1529 about @q{whitespace errors}.
1531 The solution to such problems is surprisingly simple---just change
1532 the default file extension of patches generated by git to end in
1533 @code{.txt}, for example:
1536 git config format.suffix '.patch.txt'
1539 This should cause email programs to apply the correct base64
1540 encoding to attached patches.
1542 If you receive a patch with DOS instead of UNIX line-endings, it
1543 can be converted back using the @code{dos2unix} utility.
1545 Lots of useful information on email complications with patches is
1546 provided on the Wine wiki at
1547 @uref{http://wiki.winehq.org/GitWine}.
1550 @node Cleaning up multiple patches
1551 @subsection Cleaning up multiple patches
1553 If you have been developing on your own branch for a while, you
1554 may have more commmits than is really sensible. To revise your
1555 work and condense commits, use:
1558 git rebase origin/master
1559 git rebase -i origin/master
1562 @warning{Be a bit cautious -- if you completely remove commits
1563 during the interactive session, you will... err... completely
1564 remove those commits.}
1568 @subsection Commit access
1570 Most contributors are not able to commit patches directly to the
1571 main repository---only members of the LilyPond development team
1572 have @emph{commit access}. If you are a contributor and are
1573 interested in joining the development team, contact the Project
1574 Manager through the mailing list
1575 (@email{lilypond-devel@@gnu.org}). Generally, only contributors
1576 who have already provided a number of patches which have been
1577 pushed to the main repository will be considered for membership.
1579 If you have been approved by the Project Manager, use the
1580 following procedure to obtain commit access:
1584 If you don't already have one, set up a Savannah user account at
1585 @uref{https://savannah.gnu.org/account/register.php}. If your web
1586 browser responds with an @qq{untrusted connection} message when
1587 you visit the link, follow the steps for including the CAcert root
1588 certificate in your browser, given at
1589 @uref{http://savannah.gnu.org/tls/tutorial/}.
1591 @warning{Savannah will silently put your username in lower-case --
1592 do not try to use capital letters.}
1596 After registering, if you are not logged in automatically, login
1597 at @uref{https://savannah.gnu.org/account/login.php}---this should
1598 take you to your @qq{my} page
1599 (@uref{https://savannah.gnu.org/my/}).
1603 Click on the @qq{My Groups} link to access the @qq{My Group
1604 Membership} page. From there, find the @qq{Request for Inclusion}
1605 box and search for @qq{LilyPond}. Among the search results, check
1606 the box labeled @qq{GNU LilyPond Music Typesetter} and write a
1607 brief (required) message for the Project Manager (@qq{Hey it's
1608 me!} should be fine).
1610 Note that you will not have commit access until the Project
1611 Manager activates your membership. Once your membership is
1612 activated, LilyPond should appear under the heading @qq{Groups I'm
1613 Contributor of} on your @qq{My Group Membership} page.
1617 Generate an SSH @q{rsa} key pair. Enter the following at the
1624 When prompted for a location to save the key, press <ENTER> to
1625 accept the default location (@file{~/.ssh/id_rsa}).
1627 Next you are asked to enter an optional passphrase. On most
1628 systems, if you use a passphrase, you will likely be prompted for
1629 it every time you use @command{git@tie{}push} or
1630 @command{git@tie{}pull}. You may prefer this since it can protect
1631 you from your own mistakes (like pushing when you mean to pull),
1632 though you may find it tedious to keep re-entering it.
1634 You can change/enable/disable your passphrase at any time with:
1637 ssh-keygen -f ~/.ssh/id_rsa -p
1640 Note that the GNOME desktop has a feature which stores your
1641 passphrase for you for an entire GNOME session. If you use a
1642 passphrase to @qq{protect you from yourself}, you will want to
1643 disable this feature, since you'll only be prompted once. Run the
1644 following command, then logout of GNOME and log back in:
1647 gconftool-2 --set -t bool \
1648 /apps/gnome-keyring/daemon-components/ssh false
1651 After setting up your passphrase, your private key is saved as
1652 @file{~/.ssh/id_rsa} and your public key is saved as
1653 @file{~/.ssh/id_rsa.pub}.
1657 Register your public SSH @q{rsa} key with Savannah. From the
1658 @qq{My Account Configuration} page, click on @qq{Edit SSH Keys},
1659 then paste the contents of your @file{~/.ssh/id_rsa.pub} file into
1660 one of the @qq{Authorized keys} text fields, and click
1663 Savannah should respond with something like:
1666 Success: Key #1 seen Keys registered
1671 Configure Git to use the SSH protocol (instead of the GIT
1672 protocol). From your local Git repository, enter:
1675 git config remote.origin.url \
1676 ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1680 replacing @var{user} with your Savannah username.
1684 After your membership has been activated and you've configured Git
1685 to use SSH, test the connection with:
1691 SSH should issue the following warning:
1694 The authenticity of host 'git.sv.gnu.org (140.186.70.72)' can't
1696 RSA key fingerprint is
1697 80:5a:b0:0c:ec:93:66:29:49:7e:04:2b:fd:ba:2c:d5.
1698 Are you sure you want to continue connecting (yes/no)?
1701 Make sure the RSA key fingerprint displayed matches the one above.
1702 If it doesn't, respond @qq{no} and check that you configured Git
1703 properly in the previous step. If it does match, respond
1704 @qq{yes}. SSH should then issue another warning:
1707 Warning: Permanently added 'git.sv.gnu.org,140.186.70.72' (RSA) to
1708 the list of known hosts.
1711 The list of known hosts is stored in the file
1712 @file{~/.ssh/known_hosts}.
1714 At this point, you are prompted for your passphrase if you have
1715 one, then Git will attempt a pull.
1717 If @command{git@tie{}pull@tie{}--verbose} fails, you should see
1718 error messages like these:
1721 Permission denied (publickey).
1722 fatal: The remote end hung up unexpectedly
1725 If you get the above error, you may have made a mistake when
1726 registering your SSH key at Savannah. If the key is properly
1727 registered, you probably just need to wait for the Savannah server
1728 to activate it. It usually takes a few minutes for the key to be
1729 active after registering it, but if it still doesn't work after an
1730 hour, ask for help on the mailing list.
1732 If @command{git@tie{}pull@tie{}--verbose} succeeds, the output
1733 will include a @q{From} line that shows @q{ssh} as the protocol:
1736 From ssh://git.sv.gnu.org/srv/git/lilypond
1739 If the protocol shown is not @q{ssh}, check that you configured
1740 Git properly in the previous step.
1744 Test your commit access with a dry run:
1746 @warning{Do not push directly to master; instead, push to staging.
1747 See @ref{Pushing to staging}.}
1750 git push --dry-run --verbose
1753 Note that recent versions of Git (Git 1.6.3 or later) will issue a
1754 big warning if the above command is used. The simplest solution
1755 is to tell Git to push all matching branches by default:
1758 git config push.default matching
1762 Then @code{git@tie{}push} should work as before. For more
1763 details, consult the @code{git@tie{}push} man page.
1767 Repeat the steps from generating an RSA key through to testing
1768 your commit access, for each machine from which you will be
1769 making commits, or you may simply copy the files from your
1770 local @file{~/.ssh} folder to the same folder on the other
1775 @subsubheading Technical details
1779 On Firefox, to view or remove the CAcert root certificate, go to:
1780 Edit > Preferences > Advanced > Encryption > View Certificates >
1781 Authorities > Certificate Name > Root CA > CA Cert Signing
1785 The @command{git@tie{}config} commands above should modify your
1786 local repository's @file{.git/config} file. These lines:
1790 url = git://git.sv.gnu.org/lilypond.git/
1794 should now be changed to:
1798 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1802 where @var{user} is your login name on Savannah.
1806 @command{git@tie{}config@tie{}push.default@tie{}matching} command
1807 should add these lines to @file{.git/config}:
1816 Encryption protocols, including ssh, generally do not permit packet
1817 fragmentation to avoid introducing a point of insecurity. This
1818 means that the maximum packet size must not exceed the smallest
1819 MTU (Maximum Transmission Unit) set in the routers along the path.
1820 This smallest MTU is determined by a procedure during call set-up
1821 which relies on the transmission over the path of ICMP packets.
1822 If any of the routers in the path block ICMP packets this mechanism
1823 fails, resulting in the possibility of packets being transmitted
1824 which exceed the MTU of one of the routers. If this happens the
1825 packet is discarded, causing the ssh session to hang, timeout or
1826 terminate with the error message
1829 ssh: connect to host <host ip addr> port 22: Bad file number
1830 fatal: The remote end hung up unexpectedly
1833 depending on precisely when in the proceedings the first large
1834 packet is transmitted. Most routers on the internet have MTU
1835 set to 1500, but routers installed in homes to connect via
1836 broadband may use a slightly smaller MTU for efficient transmission
1837 over ATM. If this problem is encountered a possible work-around is
1838 to set the MTU in the local router to 1500.
1841 @node Pushing to staging
1842 @subsection Pushing to staging
1844 Do not push directly to the git @code{master} branch. Instead,
1845 push to @code{staging}.
1847 You will not see your patch on @code{origin/master} until some
1848 automatic tests have been run. These tests are run every couple
1849 of hours; please wait at least 12 hours before wondering if your
1850 patch has been lost. Note that you can check the commits on
1851 @code{origin/staging} by looking at the git web interface on
1854 It may happen occasionally that the staging branch breaks automated
1855 testing. In this case the automatic move of staging material to
1856 master gets halted in order to avoid broken material entering master.
1857 This is a safety net. Please do not try breaking out from it by
1858 adding fixes on top of staging: in that case the whole sequence will
1859 end up in master after all, defeating the purpose of the system. The
1860 proper fix usually involves rewriting the staging branch and is best
1861 left to core developers after discussion on the developer list.
1863 @subsubheading If your work is in a patch file
1865 Assuming that your patch is in a file called
1866 @file{0001-my-patch.patch}, and you are currently on git master,
1870 git checkout staging
1872 git am 0001-my-patch.patch
1874 git push origin staging
1878 @warning{Do not skip the @command{gitk} step; a quick 5-second
1879 check of the visual history can save a great deal of frustration
1880 later on. You should only see that @command{staging} is only 1
1881 commit ahead of @code{origin/staging}.}
1883 @subsubheading If your work is in a branch
1885 If you are working on branches and your work in is
1886 @code{my_branch_name}, then do:
1889 git checkout staging
1891 git merge my_branch_name
1893 git push origin staging
1896 @warning{Do not skip the @command{gitk} step; a quick 5-second
1897 check of the visual history can save a great deal of frustration
1898 later on. You should see that @code{staging} is only ahead of
1899 @code{origin/staging} by the commits from your branch.}
1903 @node Git on Windows
1904 @section Git on Windows
1906 @warning{We heavily recommend that development be done with our
1907 virtual machine @ref{LilyDev}.}
1909 @c Some of this may duplicate stuff in other sections
1910 @c But it is probably best for windows users to have it all together
1911 @c If necessary, clear this up later -td
1913 TODO: Decide what to do with this... Pare it down? Move
1914 paragraphs next to analogous Unix instructions? -mp
1916 @subsection Background to nomenclature
1918 Git is a system for tracking the changes made to source files by a
1919 distributed set of editors. It is designed to work without a
1920 master repository, but we have chosen to have a master repository
1921 for LilyPond files. Editors hold a local copy of the master
1922 repository together with any changes they have made locally.
1923 Local changes are held in a local @q{branch}, of which there may
1924 be several, but these instructions assume you are using just one.
1925 The files visible in the local repository always correspond to
1926 those on the currently @q{checked out} local branch.
1928 Files are edited on a local branch, and in that state the changes
1929 are said to be @q{unstaged}. When editing is complete, the
1930 changes are moved to being @q{staged for commit}, and finally the
1931 changes are @q{committed} to the local branch. Once committed,
1932 the changes (called a @q{commit}) are given a unique 40-digit
1933 hexadecimal reference number called the @q{Committish} or @q{SHA1
1934 ID} which identifies the commit to Git. Such committed changes
1935 can be sent to the master repository by @q{pushing} them (if you
1936 have write permission) or by sending them by email to someone who
1937 has, either as a complete file or as a @q{diff} or @q{patch}
1938 (which send just the differences from the master repository).
1940 @subsection Installing git
1943 @uref{http://code.google.com/p/msysgit/downloads/list} (note, not
1944 msysGit, which is for Git developers and not PortableGit, which is
1945 not a full git installation) and install it.
1947 Note that most users will not need to install SSH. That is not
1948 required until you have been granted direct push permissions to
1949 the master git repository.
1951 Start Git by clicking on the desktop icon. This will bring up a
1952 command line bash shell. This may be unfamiliar to Windows users.
1953 If so, follow these instructions carefully. Commands are entered
1954 at a $ prompt and are terminated by keying a newline.
1956 @subsection Initialising Git
1958 Decide where you wish to place your local Git repository, creating
1959 the folders in Windows as necessary. Here we call the folder to
1960 contain the repository @code{[path]/Git}, but if you intend using
1961 Git for other projects a directory name like @code{lilypond-git}
1962 might be better. You will need to have space for around
1965 Start the Git bash shell by clicking on the desk-top icon
1966 installed with Git and type
1972 to position the shell at your new Git repository.
1974 Note: if [path] contains folders with names containing spaces use
1986 to initialize your Git repository.
1988 Then type (all on one line; the shell will wrap automatically)
1991 git remote add -ft master origin git://git.sv.gnu.org/lilypond.git
1994 to download the lilypond master files.
1996 @warning{Be patient! Even on a broadband connection this can take
1997 10 minutes or more. Wait for lots of [new tag] messages and the $
2000 We now need to generate a local copy of the downloaded files in a
2001 new local branch. Your local branch needs to have a name. It is
2002 usual to call it @q{master} and we shall do that here.
2007 git checkout -b master origin/master
2010 This creates a second branch called @q{master}. You will see two
2011 warnings (ignore these), and a message advising you that your
2012 local branch @q{master} has been set up to track the remote
2013 branch. You now have two branches, a local branch called
2014 @q{master}, and a tracking branch called @q{origin/master}, which
2015 is a shortened form of @q{remotes/origin/master}.
2017 Return to Windows Explorer and look in your Git repository. You
2018 should see lots of folders. For example, the LilyPond
2019 documentation can be found in [path]/Git/Documentation/.
2021 The Git bash shell is terminated by typing @code{exit} or by
2022 clicking on the usual Windows close-window widget.
2026 Almost all subsequent work will use the Git Graphical User
2027 Interface, which avoids having to type command line commands. To
2028 start Git GUI first start the Git bash shell by clicking on the
2029 desktop icon, and type
2036 The Git GUI will open in a new window. It contains four panels
2037 and 7 pull-down menus. At this stage do not use any of the
2038 commands under Branch, Commit, Merge or Remote. These will be
2041 The top panel on the left contains the names of files which you
2042 are in the process of editing (Unstaged Changes), and the lower
2043 panel on the left contains the names of files you have finished
2044 editing and have staged ready for committing (Staged Changes). At
2045 present, these panels will be empty as you have not yet made any
2046 changes to any file. After a file has been edited and saved the
2047 top panel on the right will display the differences between the
2048 edited file selected in one of the panels on the left and the last
2049 version committed on the current branch.
2051 The panel at bottom right is used to enter a descriptive message
2052 about the change before committing it.
2054 The Git GUI is terminated by entering CNTL-Q while it is the
2055 active window or by clicking on the usual Windows close-window
2058 @subsection Personalising your local git repository
2060 Open the Git GUI, click on
2066 and enter your name and email address in the left-hand (Git
2067 Repository) panel. Leave everything else unchanged and save it.
2069 Note that Windows users must leave the default setting for line
2070 endings unchanged. All files in a git repository must have lines
2071 terminated by just a LF, as this is required for Merge to work,
2072 but Windows files are terminated by CRLF by default. The git
2073 default setting causes the line endings of files in a Windows git
2074 repository to be flipped automatically between LF and CRLF as
2075 required. This enables files to be edited by any Windows editor
2076 without causing problems in the git repository.
2078 @subsection Checking out a branch
2080 At this stage you have two branches in your local repository,
2081 both identical. To see them click on
2087 You should have one local branch called @q{master} and one
2088 tracking branch called @q{origin/master}. The latter is your
2089 local copy of the @q{remotes/origin/master} branch in the master
2090 LilyPond repository. The local @q{master} branch is where you
2091 will make your local changes.
2093 When a particular branch is selected, i.e., checked out, the files
2094 visible in your repository are changed to reflect the state of the
2095 files on that branch.
2097 @subsection Updating files from @q{remote/origin/master}
2099 Before starting the editing of a file, ensure your local
2100 repository contains the latest version of the files in the remote
2101 repository by first clicking
2104 Remote -> Fetch from -> origin
2110 This will place the latest version of every file, including all
2111 the changes made by others, into the @q{origin/master} branch of
2112 the tracking branches in your git repository. You can see these
2113 files by checking out this branch, but you must @emph{never} edit
2114 any files while this branch is checked out. Check out your local
2115 @q{master} branch again.
2117 You then need to merge these fetched files into your local
2118 @q{master} branch by clicking on
2121 Merge -> Local Merge
2125 and if necessary select the local @q{master} branch.
2127 Note that a merge cannot be completed if you have made any local
2128 changes which have not yet been committed.
2130 This merge will update all the files in the @q{master} branch to
2131 reflect the current state of the @q{origin/master} branch. If any
2132 of the changes conflict with changes you have made yourself
2133 recently you will be notified of the conflict (see below).
2135 @subsection Editing files
2137 First ensure your @q{master} branch is checked out, then simply
2138 edit the files in your local Git repository with your favourite
2139 editor and save them back there. If any file contains non-ASCII
2140 characters ensure you save it in UTF-8 format. Git will detect
2141 any changes whenever you restart Git GUI and the file names will
2142 then be listed in the Unstaged Changes panel. Or you can click
2143 the Rescan button to refresh the panel contents at any time. You
2144 may break off and resume editing any time.
2146 The changes you have made may be displayed in diff form in the top
2147 right-hand panel of Git GUI by clicking on the file name shown in
2148 one of the left panels.
2150 When your editing is complete, move the files from being Unstaged
2151 to Staged by clicking the document symbol to the left of each
2152 name. If you change your mind it can be moved back by clicking on
2153 the ticked box to the left of the name.
2155 Finally the changes you have made may be committed to your
2156 @q{master} branch by entering a brief message in the Commit
2157 Message box and clicking the Commit button.
2159 If you wish to amend your changes after a commit has been made,
2160 the original version and the changes you made in that commit may
2161 be recovered by selecting
2164 Commit -> Amend Last Commit
2168 or by checking the Amend Last Commit radio button at bottom right.
2169 This will return the changes to the Staged state, so further
2170 editing made be carried out within that commit. This must only be
2171 done @emph{before} the changes have been Pushed or sent to your
2172 mentor for Pushing - after that it is too late and corrections
2173 have to be made as a separate commit.
2176 @subsection Sending changes to @q{remotes/origin/master}
2178 If you do not have write access to @q{remotes/origin/master} you
2179 will need to send your changes by email to someone who does.
2181 First you need to create a diff or patch file containing your
2182 changes. To create this, the file must first be committed. Then
2183 terminate the Git GUI. In the git bash shell first cd to your Git
2190 if necessary, then produce the patch with
2193 git format-patch origin
2196 This will create a patch file for all the locally committed files
2197 which differ from @q{origin/master}. The patch file can be found
2198 in [path]/Git and will have a name formed from the commit message.
2200 @subsection Resolving merge conflicts
2202 As soon as you have committed a changed file your local
2203 @code{master} branch has diverged from @code{origin/master}, and
2204 will remain diverged until your changes have been committed in
2205 @code{remotes/origin/master} and Fetched back into your
2206 @code{origin/master} branch. Similarly, if a new commit has been
2207 made to @code{remotes/origin/master} by someone else and Fetched,
2208 your local @code{master} branch is divergent. You can detect a
2209 divergent branch by clicking on
2212 Repository -> Visualise all branch history
2215 This opens up a very useful new window called @q{gitk}. Use this
2216 to browse all the commits made by yourself and others.
2218 If the diagram at top left of the resulting window does not show
2219 your @code{master} tag on the same node as the
2220 @code{remotes/origin/master} tag your branch has diverged from
2221 @code{origin/master}. This is quite normal if files you have
2222 modified yourself have not yet been Pushed to
2223 @code{remotes/origin/master} and Fetched, or if files modified and
2224 committed by others have been Fetched since you last Merged
2225 @code{origin/master} into your local @code{master} branch.
2227 If a file being merged from @code{origin/master} differs from one
2228 you have modified in a way that cannot be resolved automatically
2229 by git, Merge will report a Conflict which you must resolve by
2230 editing the file to create the version you wish to keep.
2232 This could happen if the person updating
2233 @code{remotes/origin/master} for you has added some changes of his
2234 own before committing your changes to
2235 @code{remotes/origin/master}, or if someone else has changed the
2236 same file since you last fetched the file from
2237 @code{remotes/origin/master}.
2239 Open the file in your editor and look for sections which are
2242 [to be completed when I next have a merge conflict to be sure I
2243 give the right instructions -td]
2246 @subsection Other actions
2248 The instructions above describe the simplest way of using git on
2249 Windows. Other git facilities which may usefully supplement these
2253 @item Using multiple local branches (Create, Rename, Delete)
2254 @item Resetting branches
2255 @item Cherry-picking commits
2256 @item Pushing commits to @w{remote/origin/master}
2257 @item Using gitk to review history
2260 Once familiarity with using git on Windows has been gained the
2261 standard git manuals can be used to learn about these.
2264 @node Repository directory structure
2265 @section Repository directory structure
2268 @c TODO: integrate the roadmap better
2269 @verbatiminclude ROADMAP
2272 @node Other Git documentation
2273 @section Other Git documentation
2277 Official git man pages:
2278 @uref{http://www.kernel.org/pub/software/scm/git/docs/}
2281 More in-depth tutorials: @uref{http://git-scm.com/documentation}
2284 Book about git: @uref{http://progit.org/,Pro Git}
2287 Github help: @uref{http://help.github.com/}
2288 (very highly recommended by Graham)