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.5 or higher. Windows users should
125 skip to @ref{Git on Windows}.}
129 * Initializing a repository::
135 @unnumberedsubsubsec Installing Git
137 If you are using a Unix-based machine, the easiest way to download
138 and install Git is through a package manager such as @command{rpm}
139 or @command{apt-get} -- the installation is generally automatic.
140 The only required package is (usually) called @command{git-core},
141 although some of the auxiliary @command{git@var{*}} packages are
142 also useful (such as @command{gitk}).
144 Alternatively, you can visit the Git website
145 (@uref{http://git-scm.com/}) for downloadable binaries and
149 @node Initializing a repository
150 @unnumberedsubsubsec Initializing a repository
152 Once Git is installed, get a copy of the source code:
155 git clone git://git.sv.gnu.org/lilypond.git ~/lilypond-git
158 The above command will put the it in @file{~/lilypond-git}, where
159 @code{~} represents your home directory.
161 @subsubheading Technical details
163 This creates (within the @file{$LILYPOND_GIT} directory) a
164 subdirectory called @file{.git/}, which Git uses to keep track of
165 changes to the repository, among other things. Normally you don't
166 need to access it, but it's good to know it's there.
169 @node Configuring Git
170 @unnumberedsubsubsec Configuring Git
172 @warning{Throughout the rest of this manual, all command-line
173 input should be entered from the top directory of the Git
174 repository being discussed (eg. @file{$LILYPOND_GIT}). This is
175 referred to as the @emph{top source directory}.}
177 Before working with the copy of the main LilyPond repository, you
178 should configure some basic settings with the
179 @command{git@tie{}config} command. Git allows you to set both
180 global and repository-specific options.
182 To configure settings that affect all repositories, use the
183 @option{--global} command line option. For example, the first
184 two options that you should always set are your @var{name} and
185 @var{email}, since Git needs these to keep track of commit
189 git config --global user.name "@var{John Smith}"
190 git config --global user.email @var{john@@example.com}
193 To configure Git to use colored output where possible, use:
196 git config --global color.ui auto
199 The text editor that opens when using @command{git@tie{}commit}
200 can also be changed. If none of your editor-related environment
201 variables are set ($GIT_EDITOR, $VISUAL, or $EDITOR), the default
202 editor is usually @command{vi} or @command{vim}. If you're not
203 familiar with either of these, you should probably change the
204 default to an editor that you know how to use. For example, to
205 change the default editor to @command{nano}, enter:
208 git config --global core.editor @var{nano}
211 Finally, and in some ways most importantly, let's make sure that
212 we know what branch we're on. If you're not using LilyDev, add
213 this to your @file{~/.bashrc}:
216 export PS1="\u@\h \w\$(__git_ps1)$ "
219 You may need to install the additional @code{bash-completion}
220 package, but it is definitely worth it. After installation
221 you must log out, and then log back in again to enable it.
224 @subsubheading Technical details
226 Git stores the information entered with
227 @command{git@tie{}config@tie{}--global} in the file
228 @file{.gitconfig}, located in your home directory. This file can
229 also be modified directly, without using
230 @command{git@tie{}config}. The @file{.gitconfig} file generated
231 by the above commands would look like this:
236 email = john@@example.com
243 Using the @command{git@tie{}config} command @emph{without} the
244 @option{--global} option configures repository-specific settings,
245 which are stored in the file @file{.git/config}. This file is
246 created when a repository is initialized (using
247 @command{git@tie{}init}), and by default contains these lines:
251 repositoryformatversion = 0
254 logallrefupdates = true
257 However, since different repository-specific options are
258 recommended for different development tasks, it is best to avoid
259 setting any now. Specific recommendations will be mentioned later
263 @node Git for the impatient
264 @subsection Git for the impatient
266 @advanced{The intent of this subsection is to get you working on lilypond as
267 soon as possible. If you want to learn about git, go read
268 @ref{Other Git documentation}.
270 Also, these instructions are designed to eliminate the most common
271 problems we have found in using git. If you already know git and
272 have a different way of working, great! Feel free to ignore the
273 advice in this subsection.}
276 Ok, so you've been using @command{lily-git.tcl} for a while, but
277 it's time to take the next step. Since our review process delays
278 patches by 60-120 hours, and you want to be able to work on other
279 stuff while your previous work is getting reviewed, you're going
280 to use @strong{branches}.
282 You can think of a branch as being a separate copy of the source
283 code. But don't worry about it.
285 @subsubheading Start work: make a new branch
287 Let's pretend you want to add a section to the Contributor's Guide
288 about using branches.
290 Start by updating the repository, then making a new branch. Call
291 the branch anything you want as long as the name starts with
292 @code{dev/}. Branch names that don't begin with @code{dev/} are
293 reserved for special things in lilypond.
297 git pull -r origin master
301 @subsubheading Switch to that branch
303 Nothing has happened to the files yet. Let's change into the new
304 branch. You can think of this as @qq{loading a file}, although in
305 this case it's really @qq{loading a directory and subdirectories
312 Your prompt now shows you that you're on the other branch:
315 gperciva@@LilyDev:~/lilypond-git (dev/cg)$
318 To be able to manage multiple lilypond issues at once, you'll need to switch
319 branches. You should have each lilypond issue on a separate branch.
320 Switching branches is easy:
324 git checkout origin/staging
325 git checkout origin/release/unstable
329 Branches that begin with @code{origin/} are part of the remote repository,
330 rather than your local repository, so when you check them out you get a
331 temporary local branch. You should never make changes directly on a
332 branch beginning with @code{origin/}. You get changes into the remote
333 repository by making them in local branches, and then pushing them to
334 @code{origin/staging} as described below.
336 @subsubheading Make your changes
338 Edit files, then commit them.
345 Remember how I said that switching to a branch was like
346 @qq{loading a directory}? Well, you've just @qq{saved a
347 directory}, so that you can @qq{load} it later.
349 @advanced{If you have used @command{cvs} or @command{svn}, you may
350 be very confused: those programs use @qq{commit} to mean
351 @qq{upload my changes to the shared source repository}.
352 Unfortunately, just to be different, @w{@command{git commit}}
353 means @qq{save my changes to the files}.}
355 When you create a new file, you need to add it to git, then commit it:
358 git add input/regression/avoid-crash-on-condition.ly
363 Edit more files. Commit them again. Edit yet more files, commit
364 them again. Go eat dinner. Switch to @code{master} so you can
365 play with the latest changes from other developers. Switch back
366 to your branch and edit some more. Commit those changes.
368 At this stage, don't worry about how many commits you have.
371 @subsubheading Save commits to external files
373 Branches are nerve-wracking until you get used to them. You can
374 save your hard work as individual @file{.patch} files. Be sure to
375 commit your changes first.
379 git format-patch master
382 I personally have between 4 and 20 of those files saved in a
383 special folder at any point in time. Git experts might laugh as
384 that behavior, but I feel a @emph{lot} better knowing that I've
388 @subsubheading Prepare your branch for review
390 After committing, you can update your branch with the latest master:
395 git pull -r origin master
401 Due to the speed of lilypond development, sometimes
402 @code{master} has changed so much that your branch can no
403 longer be applied to it. In that happens, you will have a merge
404 conflict. Stop for a moment to either cry or have a stiff drink,
405 then proceed to @ref{Merge conflicts}.
408 @subsubheading Upload your branch
410 Finally, you're finished your changes. Time to upload for review.
411 Make sure that you're on your branch, then upload:
419 @subsubheading Wait for reviews
421 While you're waiting for a countdown and reviews, go back to
422 master, make a @code{dev/doc-beams} branch, and start adding doc
423 suggestions from issue 12345 from the tracker. Or make a
424 @code{dev/page-breaks} and fix bug in page breaking. Or whatever.
425 Don't worry, your @code{dev/cg} is safe.
428 @subsubheading Combining commits (optional unless you have broken commits)
430 Does the history of your branch look good?
436 If you have a lot of commits on your branch, you might want to
437 combine some of them. Alternately, you may like your commits, but
438 want to edit the commit messages.
444 Follow instructions on the screen.
446 @warning{This step gives you the power to completely lose your
447 work. Make a backup of your commits by saving them to
448 @file{.patch} files before playing with this. If you do lose
449 your work, don't despair. You can get it back by using @code{git reflog}.
450 The use of @code{git reflog} is not covered here.}
452 @warning{If any of the commits on your branch represent partial work that will
453 not pass @var{make && make doc}, you @strong{must} squash these
454 commits into a working commit. Otherwise, your push will break staging
455 and will not be able to be merged to master. In general, you will
456 be safer to have one commit per push.}
459 @subsubheading Push to staging
461 When you've got the coveted @code{Patch-push} status, time to
466 git rebase origin/staging dev/cg~0
470 @warning{Do not skip the @command{gitk} step; a quick 5-second
471 check of the visual history can save a great deal of frustration
472 later on. You should see a set of your commits that are ahead of
473 @code{origin/staging}, with no label for the top commit -- only a
476 @warning{If @code{origin/staging} and @code{origin/master} are the
477 same commit, your branch (@code{dev/cg} in the example) will also
478 be at the top of the @code{gitk} tree. This is normal.}
480 If everything looks good, push it:
483 git push origin HEAD:staging
486 Then change back to your working branch:
492 @warning{It is a best practice to avoid rebasing any of your branches
493 to @code{origin/staging}. If @code{origin/staging} is broken, it
494 will be deleted and rebuilt. If you have rebased one of your branches
495 to @code{origin/staging}, the broken commits can end up in your branch.
496 The commands given above do the rebase on a temporary branch, and avoid
497 changing your working branch.}
500 @subsubheading Delete your branch (safe)
502 After a few hours, if there's nothing wrong with your branch, it
503 should be automatically moved to @code{origin/master}. Update,
504 then try removing your branch:
508 git pull -r origin master
512 The last command will fail if the contents of @code{dev/cg} are
513 not present in @code{origin/master}.
516 @subsubheading Delete your branch (UNSAFE)
518 @c don't give explicit commands here -- this is too dangerous to copy and paste
519 Sometimes everything goes wrong. If you want to remove a branch even though
520 it will cause your work to be lost (that is, if the contents of @code{dev/cg}
521 are @strong{not} present in master), follow the instructions in @qq{Delete
522 your branch (safe)}, but replace the @code{-d} on the final line with
526 @node Other repositories
527 @subsection Other repositories
529 We have a few other code repositories.
533 * Grand Unified Builder (GUB)::
535 * yet more repositories::
539 @unnumberedsubsubsec lilypond-extra
541 There is a separate repository for general administrative scripts,
542 as well as pictures and media files for the website. People
543 interested in working on the website should download this
544 repository, and set their @code{$LILYPOND_WEB_MEDIA_GIT}
545 environment variable to point to that repository.
548 @uref{https://github.com/gperciva/lilypond-extra}
551 To configure an environment variable in bash (the default for most
552 GNU/Linux distributions),
555 export LILYPOND_WEB_MEDIA_GIT=$HOME/dir/of/lilypond-extra/
558 Be aware that @code{lilypond-extra} is the definitive source for some binary
559 files - in particular PDF versions of papers concerning LilyPond. To add
560 further PDFs of this sort, all that is necessary is to add the PDF to
561 @code{lilypond-extra} and then add a reference to it in the documentation. The
562 file will then be copied to the website when @code{make website} is run.
564 However, pictures that are also used in the documentation build are mastered in
565 the main git repository. If any of these is changed, it should be updated in
566 git, and then the updates copied to @code{lilypond-extra}.
568 @node Grand Unified Builder (GUB)
569 @unnumberedsubsubsec Grand Unified Builder (GUB)
571 Another item of interest might be the Grand Unified Builder, our
572 cross-platform building tool. Since it is used by other projects as
573 well, it is not stored in our gub repository. For more info, see
574 @uref{http://lilypond.org/gub}.
576 There are two locations for this repository: the version being used to
577 build lilypond, which is at
580 @uref{http://github.com/gperciva/gub}
583 and the original version by Jan Nieuwenhuizen, kept at
586 @uref{http://github.com/janneke/gub}
591 @unnumberedsubsubsec LilyPad
593 Our binary releases on MacOS X and Windows contain a lightweight
596 To make any modifications the Windows editor, you will need to do the
601 Clone the git repository from @code{https://github.com/gperciva/lilypad}
604 Make changes to the source, and check it compiles. In a Windows environment
605 @code{MinGW} provides both a @code{Git} installation and a @code{gcc}
606 compiler. This can be obtained from @code{http://www.mingw.org/}
609 Update the version which is contained in the @file{rsrc.rc}. Check
613 Commit the changes with an informative commit message.
616 Push the changes to github. You will need to use syntax similiar to this:
619 git push https://UserName@@github.com/gperciva/lilypad.git
622 You will need to have push access to the git repository for this to be
626 Make a tarball of the source code to be used by GUB by pulling the updated
627 repository from GitHub. Ensure that the tarball has the correct Version
631 Copy the tarball to @code{http://lilypond.org/download/gub-sources/lilypad/}.
632 You will need to have SSH access to @code{lilypond.org}. If you do not, contact
633 the Release Manager via the lilypond-devel mailing list.
636 Update GUB to make it use the new tarball by editing
637 @file{gub/specs/lilypad.py} and changing the @code{source =} line to point to
641 Push this updated @file{lilypad.py} version to the GUB repository on GitHub.
644 Test the changes with a new GUB compile.
648 @node yet more repositories
649 @unnumberedsubsubsec yet more repositories
651 There are a few other repositories floating around, which will
652 hopefully be documented in the near future.
655 @node Downloading remote branches
656 @subsection Downloading remote branches
658 @warning{contains obsolete + misleading info}
661 * Organization of remote branches::
662 * LilyPond repository sources::
663 * Downloading individual branches::
664 * Downloading all remote branches::
669 @node Organization of remote branches
670 @unnumberedsubsubsec Organization of remote branches
673 The main LilyPond repository is organized into @emph{branches} to
674 facilitate development. These are often called @emph{remote}
675 branches to distinguish them from @emph{local} branches you might
676 create yourself (see @ref{Using local branches}).
678 The @code{master} branch contains all the source files used to
679 build LilyPond, which includes the program itself (both stable and
680 development releases), the documentation (and its translations),
681 and the website. Generally, the @code{master} branch is expected
682 to compile successfully.
684 The @code{translation} branch is a side branch that
685 allows translators to work without needing to worry about
686 compilation problems. Periodically, the Translation Meister
687 (after verifying that it doesn't break compilation), will
688 @emph{merge} this branch into @code{staging} to incorporate
689 recent translations. Similarly, the @code{master} branch is
690 usually merged into the @code{translation} branch after
691 significant changes to the English documentation. See
692 @ref{Translating the documentation} for details.
695 @node LilyPond repository sources
696 @unnumberedsubsubsec LilyPond repository sources
699 The recommended source for downloading a copy of the main
703 git://git.sv.gnu.org/lilypond.git
706 However, if your internet router filters out connections using the
707 GIT protocol, or if you experience difficulty connecting via GIT,
708 you can try these other sources:
711 ssh://git.sv.gnu.org/srv/git/lilypond.git
712 http://git.sv.gnu.org/r/lilypond.git
715 The SSH protocol can only be used if your system is properly set
716 up to use it. Also, the HTTP protocol is slowest, so it should
717 only be used as a last resort.
720 @node Downloading individual branches
721 @unnumberedsubsubsec Downloading individual branches
723 @warning{obsolete, should be deleted!}
726 Once you have initialized an empty Git repository on your system
727 (see @ref{Initializing a repository}), you can download a remote
728 branch into it. Make sure you know which branch you want to start
731 To download the @code{master} branch, enter the following:
734 git remote add -ft master -m master \
735 origin git://git.sv.gnu.org/lilypond.git/
738 To download the @code{translation} branch, enter:
741 git remote add -ft translation -m \
742 translation origin git://git.sv.gnu.org/lilypond.git/
745 The @command{git@tie{}remote@tie{}add} process could take up to
746 ten minutes, depending on the speed of your connection. The
747 output will be something like this:
751 remote: Counting objects: 235967, done.
752 remote: Compressing objects: 100% (42721/42721), done.
753 remote: Total 235967 (delta 195098), reused 233311 (delta 192772)
754 Receiving objects: 100% (235967/235967), 68.37 MiB | 479 KiB/s, done.
755 Resolving deltas: 100% (195098/195098), done.
756 From git://git.sv.gnu.org/lilypond
757 * [new branch] master -> origin/master
758 From git://git.sv.gnu.org/lilypond
759 * [new tag] flower/1.0.1 -> flower/1.0.1
760 * [new tag] flower/1.0.10 -> flower/1.0.10
762 * [new tag] release/2.9.6 -> release/2.9.6
763 * [new tag] release/2.9.7 -> release/2.9.7
766 When @command{git@tie{}remote@tie{}add} is finished, the remote
767 branch should be downloaded into your repository---though not yet
768 in a form that you can use. In order to browse the source code
769 files, you need to @emph{create} and @emph{checkout} your own
770 local branch. In this case, however, it is easier to have Git
771 create the branch automatically by using the @command{checkout}
772 command on a non-existent branch. Enter the following:
775 git checkout -b @var{branch} origin/@var{branch}
779 where @code{@var{branch}} is the name of your tracking branch,
780 either @code{master} or @code{translation}.
782 Git will issue some warnings; this is normal:
785 warning: You appear to be on a branch yet to be born.
786 warning: Forcing checkout of origin/master.
787 Branch master set up to track remote branch master from origin.
791 By now the source files should be accessible---you should be able
792 to edit any files in the @file{$LILYPOND_GIT} directory using a
793 text editor of your choice. But don't start just yet! Before
794 editing any source files, learn how to keep your changes organized
795 and prevent problems later---read @ref{Basic Git procedures}.
797 @subsubheading Technical Details
799 The @command{git@tie{}remote@tie{}add} command should add some
800 lines to your local repository's @file{.git/config} file:
804 url = git://git.sv.gnu.org/lilypond.git/
805 fetch = +refs/heads/master:refs/remotes/origin/master
809 @node Downloading all remote branches
810 @unnumberedsubsubsec Downloading all remote branches
813 To download all remote branches at once, you can @command{clone}
814 the entire repository:
817 git clone git://git.sv.gnu.org/lilypond.git
822 @unnumberedsubsubsec Other branches
824 Most contributors will never need to touch the other branches. If
825 you wish to do so, you will need more familiarity with Git; please
826 see @ref{Other Git documentation}.
829 @item @code{dev/XYZ}:
830 These branches are for individual developers. They store code
831 which is not yet stable enough to be added to the @code{master}
834 @item @code{stable/XYZ}:
835 The branches are kept for archival reasons.
837 @item @code{archive/XYZ}:
838 The branches are kept for archival reasons.
843 @node Basic Git procedures
844 @section Basic Git procedures
848 * The Git contributor's cycle::
849 * Pulling and rebasing::
850 * Using local branches::
851 * Commits and patches::
855 @node The Git contributor's cycle
856 @subsection The Git contributor's cycle
859 Here is a simplified view of the contribution process on Git:
863 Update your local repository by @emph{pulling} the most recent
864 updates from the remote repository.
867 Edit source files within your local repository's @emph{working
871 @emph{Commit} the changes you've made to a local @emph{branch}.
874 Generate a @emph{patch} to share your changes with the developers.
878 @node Pulling and rebasing
879 @subsection Pulling and rebasing
882 When developers push new patches to the @code{git.sv.gnu.org}
883 repository, your local repository is @strong{not} automatically
884 updated. It is important to keep your repository up-to-date by
885 periodically @emph{pulling} the most recent @emph{commits} from
886 the remote branch. Developers expect patches to be as current as
887 possible, since outdated patches require extra work before they
890 Occasionally you may need to rework some of your own modifications
891 to match changes made to the remote branch (see @ref{Resolving
892 conflicts}), and it's considerably easier to rework things
893 incrementally. If you don't update your repository along the way,
894 you may have to spend a lot of time resolving branch conflicts and
895 reconfiguring much of the work you've already done.
897 Fortunately, Git is able to resolve certain types of branch
898 conflicts automatically with a process called @emph{rebasing}.
899 When rebasing, Git tries to modify your old commits so they appear
900 as new commits (based on the latest updates). For a more involved
901 explanation, see the @command{git-rebase} man page.
903 To pull without rebasing (recommended for translators), use the
907 git pull # recommended for translators
910 If you're tracking the remote @code{master} branch, you should add
911 the @option{-r} option (short for @option{--rebase}) to keep commits
912 on your local branch current:
915 git pull -r # use with caution when translating
918 If you don't edit translated documentation and don't want to type
919 @option{-r} every time, configure the master branch to rebase by
920 default with this command:
923 git config branch.master.rebase true
926 If pull fails because of a message like
929 error: Your local changes to 'Documentation/learning/tutorial.itely'
930 would be overwritten by merge. Aborting.
937 Documentation/learning/tutorial.itely: needs update
938 refusing to pull with rebase: your working tree is not up-to-date
942 it means that you have modified some files in you working tree
943 without committing changes (see @ref{Commits and patches}); you
944 can use the @command{git@tie{}stash} command to work around this:
947 git stash # save uncommitted changes
948 git pull -r # pull using rebase (translators omit "-r")
949 git stash pop # reapply previously saved changes
952 Note that @command{git@tie{}stash@tie{}pop} will try to apply a
953 patch, and this may create a conflict. If this happens, see
954 @ref{Resolving conflicts}.
956 TODO: I think the next paragraph is confusing. Perhaps prepare
957 the reader for new terms `committish' and `head'? -mp
959 @warning{translators and documentation editors, if you have
960 changed committishes in the head of translated files using commits
961 you have not yet pushed to @code{git.sv.gnu.org}, please do not
962 rebase. If you want to avoid wondering whether you should rebase
963 each time you pull, please always use committishes from master
964 and/or translation branch on @code{git.sv.gnu.org}, which
965 in particular implies that you must push your changes to
966 documentation except committishes updates (possibly after having
967 rebased), then update the committishes and push them.}
969 TODO: when committishes automatic conditional update have been
970 tested and documented, append the following to the warning above:
971 Note that using update-committishes make target generally touches
974 @subsubheading Technical details
976 The @command{git@tie{}config} command mentioned above adds the
977 line @code{rebase = true} to the master branch in your local
978 repository's @file{.git/config} file:
983 merge = refs/heads/master
988 @node Using local branches
989 @subsection Using local branches
993 * Creating and removing branches::
994 * Listing branches and remotes::
995 * Checking out branches::
1000 @node Creating and removing branches
1001 @unnumberedsubsubsec Creating and removing branches
1004 Local branches are useful when you're working on several different
1005 projects concurrently. To create a new branch, enter:
1008 git branch @var{name}
1011 To delete a branch, enter:
1014 git branch -d @var{name}
1017 Git will ask you for confirmation if it sees that data would be
1018 lost by deleting the branch. Use @option{-D} instead of @option{-d}
1019 to bypass this. Note that you cannot delete a branch if it is
1020 currently checked out.
1023 @node Listing branches and remotes
1024 @unnumberedsubsubsec Listing branches and remotes
1026 You can get the exact path or URL of all remote branches by
1033 To list Git branches on your local repositories, run
1036 git branch # list local branches only
1037 git branch -r # list remote branches
1038 git branch -a # list all branches
1042 @node Checking out branches
1043 @unnumberedsubsubsec Checking out branches
1045 To know the currently checked out branch, i.e. the branch whose
1046 source files are present in your working tree, read the first line
1054 The currently checked out branch is also marked with an asterisk
1055 in the output of @command{git branch}.
1057 You can check out another branch @code{@var{other_branch}}, i.e.
1058 check out @code{@var{other_branch}} to the working tree, by
1062 git checkout @var{other_branch}
1065 Note that it is possible to check out another branch while having
1066 uncommitted changes, but it is not recommended unless you know
1067 what you are doing; it is recommended to run @command{git status}
1068 to check this kind of issue before checking out another branch.
1070 @node Merging branches
1071 @unnumberedsubsubsec Merging branches
1073 To merge branch @code{@var{foo}} into branch @code{@var{bar}},
1074 i.e. to @qq{add} all changes made in branch @code{@var{foo}} to
1075 branch @code{@var{bar}}, run
1078 git checkout @var{bar}
1082 If any conflict happens, see @ref{Resolving conflicts}.
1084 There are common usage cases for merging: as a translator, you will
1085 often want the Translations meister to merge @code{master} into
1086 @code{translation}; on the other hand, the Translations meister wants
1087 to merge @code{translation} into @code{staging} whenever he has
1088 checked that @code{translation} builds successfully.
1091 @node Commits and patches
1092 @subsection Commits and patches
1096 * Understanding commits::
1100 * Uploading a patch for review::
1104 @node Understanding commits
1105 @unnumberedsubsubsec Understanding commits
1107 Technically, a @emph{commit} is a single point in the history of a
1108 branch, but most developers use the term to mean a @emph{commit
1109 object}, which stores information about a particular revision. A
1110 single commit can record changes to multiple source files, and
1111 typically represents one logical set of related changes (such as a
1112 bug-fix). You can list the ten most recent commits in your
1113 current branch with this command:
1116 git log -10 --oneline
1119 If you're using an older version of Git and get an @q{unrecognized
1120 argument} error, use this instead:
1123 git log -10 --pretty=oneline --abbrev-commit
1126 More interactive lists of the commits on the remote @code{master}
1127 branch are available at
1128 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=shortlog} and
1129 @uref{http://git.sv.gnu.org/cgit/lilypond.git/log/}.
1132 @node Making commits
1133 @unnumberedsubsubsec Making commits
1136 Once you have modified some source files in your working
1137 directory, you can make a commit with the following procedure:
1141 Make sure you've configured Git properly (see @ref{Configuring
1142 Git}). Check that your changes meet the requirements described in
1143 @ref{Code style} and/or @ref{Documentation policy}. For advanced
1144 edits, you may also want to verify that the changes don't break
1145 the compilation process.
1148 Run the following command:
1155 to make sure you're on the right branch, and to see which files
1156 have been modified, added or removed, etc. You may need to tell
1157 Git about any files you've added by running one of these:
1160 git add @var{file} # add untracked @var{file} individually
1161 git add . # add all untracked files in current directory
1165 After @command{git@tie{}add}, run @command{git@tie{}status} again
1166 to make sure you got everything. You may also need to modify
1170 Preview the changes about to be committed (to make sure everything
1178 The @code{HEAD} argument refers to the most recent commit on the
1179 currently checked-out branch.
1182 Generate the commit with:
1189 The @option{-a} is short for @option{--all} which includes modified
1190 and deleted files, but only those newly created files that have
1191 previously been added.
1196 @node Commit messages
1197 @unnumberedsubsubsec Commit messages
1200 When you run the @command{git@tie{}commit@tie{}-a} command, Git
1201 automatically opens the default text editor so you can enter a
1202 @emph{commit message}. If you find yourself in a foreign editing
1203 environment, you're probably in @command{vi} or @command{vim}. If
1204 you want to switch to an editor you're more familiar with, quit by
1205 typing @code{:q!} and pressing @code{<Enter>}. See
1206 @ref{Configuring Git} for instructions on changing the default
1209 In any case, Git will open a text file for your commit message
1210 that looks like this:
1214 # Please enter the commit message for your changes. Lines starting
1215 # with '#' will be ignored, and an empty message aborts the commit.
1217 # Changes to be committed:
1218 # (use "git reset HEAD <file>..." to unstage)
1220 # modified: working.itexi
1224 Your commit message should begin with a one-line summary
1225 describing the change (no more than 50 characters long), and if
1226 necessary a blank line followed by several lines giving the
1229 @c $ git log -1 --pretty=medium 4d6f1e5
1231 Doc: add Baerenreiter and Henle solo cello suites
1233 Added comparison of solo cello suite engravings to new essay with
1234 high-res images, fixed cropping on Finale example.
1237 Commit messages often start with a short prefix describing the
1238 general location of the changes. If a commit affects the
1239 documentation in English (or in several languages simultaneously)
1240 the commit message should be prefixed with @qq{Doc:@tie{}}. If
1241 the commit affects only one of the translations, the commit
1242 message should be prefixed with @qq{Doc-@var{**}:@tie{}}, where
1243 @var{**} is the two-letter language code. Commits that affect the
1244 website should use @qq{Web:@tie{}} for English, and
1245 @qq{Web-@var{**}:@tie{}} for the other languages. Also, changes
1246 to a single file are often prefixed with the name of the file
1247 involved. Visit the links listed in @ref{Understanding commits}
1251 @node Making patches
1252 @unnumberedsubsubsec Making patches
1254 If you want to share your changes with other contributors and
1255 developers, you need to generate @emph{patches} from your commits.
1256 We prefer it if you follow the instructions in
1257 @ref{Uploading a patch for review}. However, we present an
1258 alternate method here.
1260 You should always run @command{git@tie{}pull@tie{}-r} (translators
1261 should leave off the @option{-r}) before doing this to ensure that
1262 your patches are as current as possible.
1264 Once you have made one or more commits in your local repository,
1265 and pulled the most recent commits from the remote branch, you can
1266 generate patches from your local commits with the command:
1269 git format-patch origin
1272 The @code{origin} argument refers to the remote tracking branch at
1273 @code{git.sv.gnu.org}. This command generates a separate patch
1274 for each commit that's in the current branch but not in the remote
1275 branch. Patches are placed in the current working directory and
1276 will have names that look something like this:
1279 0001-Doc-Fix-typos.patch
1280 0002-Web-Remove-dead-links.patch
1284 Send an email (must be less than 64 KB) to
1285 @email{lilypond-devel@@gnu.org} briefly explaining your work, with
1286 the patch files attached. Translators should send patches to
1287 @email{translations@@lilynet.net}. After your patches are
1288 reviewed, the developers may push one or more of them to the main
1289 repository or discuss them with you.
1292 @node Uploading a patch for review
1293 @unnumberedsubsubsec Uploading a patch for review
1295 Any non-trivial change should be uploaded to our @qq{Rietveld}
1296 code review website:
1299 @uref{http://codereview.appspot.com/}
1302 @subsubheading @command{git-cl} install
1304 LilyDev users should skip over these @q{install} instructions.
1309 Install @command{git-cl} by entering:
1312 git clone https://github.com/gperciva/git-cl.git
1315 If that command fails for some reason, try this instead:
1318 git clone git://github.com/gperciva/git-cl.git
1322 Add the @file{git-cl/} directory to your PATH,
1323 or create a symbolic link to the @command{git-cl}
1324 and @command{upload.py} scripts in one of your PATH
1325 directories (such as @file{$HOME/bin}).
1327 In GNU/Linux you can add directories to PATH
1328 by adding this line to a hidden file @file{.bashrc},
1329 located in your home directory:
1332 PATH=~/type-here-directory-containing-git-cl:"$@{PATH@}"
1337 @subsubheading @command{git-cl} configuration
1339 LilyDev users should perform these @q{configuration} instructions.
1343 You must own a Google account login; please create one if you do not
1347 Note that a google account does not need to be a Gmail account; you can
1348 use @emph{any} email address for your google account when you sign up.
1350 @warning{In order for @code{git-cl} to work as expected, your Google
1351 Account Settings must have the @q{Access for less secure apps} set to
1352 @q{Allowed}. This is normally the default setting.}
1355 Move into the top source directory and then configure
1356 @command{git-cl} with the following commands:
1363 For the @qq{Rietveld server} question, the default value
1364 (@qq{codereview.appspot.com}) should be accepted by
1365 answering with a newline (CR).
1367 The @qq{CC list} question should be answered with:
1370 lilypond-devel@@gnu.org
1373 The @qq{Tree status URL} value should be left blank. So should
1374 the @qq{ViewVC URL} value, since it is used by @command{git-cl
1375 dcommit} which is only for repositories which use @command{git
1376 svn} (LilyPond doesn't).
1380 @subsubheading Uploading patch set
1382 This section assumes that you have already configured the
1383 @command{git-cl} @q{helper-script}. See @ref{git-cl}.
1385 @warning{Unless you are familiar with branches, only work on one
1386 set of changes at once.}
1388 There are two methods, depending on your git setup.
1392 @strong{Master branch}: (easy option)
1394 If you added your patch to @code{master}, then:
1398 git-cl upload origin/master
1401 @c Mention staging here?
1402 If you have git push ability, make sure that you @emph{remove}
1403 your patch (with @command{git rebase} or @command{git reset})
1404 before pushing other stuff.
1406 @c don't make this one an @example; we don't want to make it easy
1407 @c for people to use this accidently
1408 Notifications of patches are automatically added to our issue
1409 tracker to reduce the chance of patches getting lost. To suppress
1410 this (not recommended), add the @code{-n / --no-code-issue}
1414 @strong{Separate branch}: (complicated option)
1416 Ensure your changes are committed in a separate branch, which should
1417 differ from the reference branch to be used (usually
1418 @code{origin/master}) by just the changes to be uploaded. Checkout the
1419 branch with the changes:
1422 git checkout some-branch-with-changes
1425 If the reference branch is to be @code{origin/master}, ensure that the
1426 branch containing the changes is up-to-date with it. Use
1427 @command{git rebase} or @command{git pull -r} to rebase the branch to
1428 the head of @code{origin/master}. For example:
1431 git pull -r origin master
1434 Finally, start the upload by entering:
1437 git-cl upload <reference SHA1 ID>
1441 where <reference SHA1 ID> is the SHA1 ID of the commit to be used
1442 as a reference source for the patch. Generally, this will be the
1443 SHA1 ID of origin/master, and in that case the command:
1446 git-cl upload origin/master
1454 First you will see a terminal editor where you can edit the
1455 message that will accompany your patch. @command{git-cl} will
1456 respect the @env{EDITOR} environment variable if defined,
1457 otherwise it will use @command{vi} as the default editor.
1459 After prompting for your Google email address and password, the
1460 patch set will be posted to Rietveld, and you will be given a URL
1463 @warning{Some installations of git-cl fail when uploading a patch
1464 with certain filename extensions. If this happens, it can
1465 generally be fixed by editing the list of exceptions at top of
1468 @subsubheading Announcing your patch set
1470 You should then announce the patch by logging into the code review
1471 issue webpage and using @qq{Publish + Mail Comments} to add a
1472 (mostly bogus) comment to your issue. The text of your comment
1473 will be sent to our developer mailing list.
1475 @warning{There is no automatic notification of a new patch; you
1476 must add a comment yourself.}
1478 @subsubheading Revisions
1480 As revisions are made in response to comments, successive patch sets
1481 for the same issue can be uploaded by reissuing the git-cl command
1482 with the modified branch checked out.
1484 Sometimes in response to comments on revisions, the best way to
1485 work may require creation of a new branch in git. In order to
1486 associate the new branch with an existing Rietveld issue,
1487 the following command can be used:
1490 git-cl issue issue-number
1494 where @code{issue-number} is the number of the existing Rietveld
1497 @subsubheading Resetting git-cl
1499 If @command{git-cl} becomes confused, you can @qq{reset} it by
1506 @subsubheading Wait for a countdown
1508 Your patch will be available for reviews for the next few hours or
1509 days. Three times a week, patches with no known problems are
1510 gathered into a @qq{patch countdown} and their status changed to
1511 @code{patch-countdown}. The countdown is a 48-hour waiting period
1512 in which any final reviews or complaints should be made.
1514 During the countdown, your patch may be set to
1515 @code{patch-needs_work}, indicating that you should fix something
1516 (or at least discuss why the patch needs no modification). If no
1517 problems are found, the patch will be set to @code{patch-push}.
1519 Once a patch has @code{patch-push}, it should be sent to your
1520 mentor for uploading. If you have git push ability, look at
1521 @ref{Pushing to staging}.
1524 @node Advanced Git procedures
1525 @section Advanced Git procedures
1528 @warning{This section is not necessary for normal contributors;
1529 these commands are presented for information for people interested
1530 in learning more about git.}
1532 It is possible to work with several branches on the same local Git
1533 repository; this is especially useful for translators who may have
1534 to deal with both @code{translation} and a stable branch,
1535 e.g. @code{stable/2.12}.
1537 Some Git commands are introduced first, then a workflow with
1538 several Git branches of LilyPond source code is presented.
1543 * Advanced Git concepts::
1544 * Resolving conflicts::
1545 * Reverting all local changes::
1546 * Working with remote branches::
1548 * Applying remote patches::
1549 * Sending and receiving patches via email::
1550 * Cleaning up multiple patches::
1552 * Pushing to staging::
1556 @node Merge conflicts
1557 @subsection Merge conflicts
1559 To be filled in later, and/or moved to a different section. I
1560 just wanted to make sure that I had a stub ready somewhere.
1563 @node Advanced Git concepts
1564 @subsection Advanced Git concepts
1567 A bit of Git vocabulary will be explained below. The following is
1568 only introductory; for a better understanding of Git concepts, you
1569 may wish to read @ref{Other Git documentation}.
1571 The @code{git@tie{}pull@tie{}origin} command above is just a
1572 shortcut for this command:
1575 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
1579 where @code{@var{branch}} is typically @code{master} or
1580 @code{translation}; if you do not know or remember, see
1581 @ref{Downloading remote branches} to remember which commands you
1582 issued or which source code you wanted to get.
1584 A @emph{commit} is a set of changes made to the sources; it also
1585 includes the committish of the parent commit, the name and e-mail
1586 of the @emph{author} (the person who wrote the changes), the name
1587 and e-mail of the @emph{committer} (the person who brings these
1588 changes into the Git repository), and a commit message.
1590 A @emph{committish} is the SHA1 checksum of a commit, a number
1591 made of 40 hexadecimal digits, which acts as the internal unique
1592 identifier for this commit. To refer to a particular revision,
1593 don't use vague references like the (approximative) date, simply
1594 copy and paste the committish.
1596 A @emph{branch} is nothing more than a pointer to a particular
1597 commit, which is called the @emph{head} of the branch; when
1598 referring to a branch, one often actually thinks about its head
1599 and the ancestor commits of the head.
1601 Now we will explain the two last commands you used to get the
1602 source code from Git---see @ref{Downloading individual branches}.
1605 git remote add -ft @var{branch} -m @var{branch} \
1606 origin git://git.sv.gnu.org/lilypond.git/
1608 git checkout -b @var{branch} origin/@var{branch}
1611 The @command{git@tie{}remote} has created a branch called
1612 @code{origin/@var{branch}} in your local Git repository. As this
1613 branch is a copy of the remote branch web from git.sv.gnu.org
1614 LilyPond repository, it is called a @emph{remote branch}, and is
1615 meant to track the changes on the branch from git.sv.gnu.org: it
1616 will be updated every time you run
1617 @command{git@tie{}pull@tie{}origin} or
1618 @command{git@tie{}fetch@tie{}origin}.
1620 The @command{git@tie{}checkout} command has created a branch named
1621 @code{@var{branch}}. At the beginning, this branch is identical
1622 to @code{origin/@var{branch}}, but it will differ as soon as you
1623 make changes, e.g. adding newly translated pages or editing some
1624 documentation or code source file. Whenever you pull, you merge
1625 the changes from @code{origin/@var{branch}} and
1626 @code{@var{branch}} since the last pulling. If you do not have
1627 push (i.e. @qq{write}) access on git.sv.gnu.org, your
1628 @code{@var{branch}} will always differ from
1629 @code{origin/@var{branch}}. In this case, remember that other
1630 people working like you with the remote branch @code{@var{branch}}
1631 of git://git.sv.gnu.org/lilypond.git/ (called
1632 @code{origin/@var{branch}} on your local repository) know nothing
1633 about your own @code{@var{branch}}: this means that whenever you
1634 use a committish or make a patch, others expect you to take the
1635 latest commit of @code{origin/@var{branch}} as a reference.
1637 Finally, please remember to read the man page of every Git command
1638 you will find in this manual in case you want to discover
1639 alternate methods or just understand how it works.
1642 @node Resolving conflicts
1643 @subsection Resolving conflicts
1646 Occasionally an update may result in conflicts -- this happens
1647 when you and somebody else have modified the same part of the same
1648 file and git cannot figure out how to merge the two versions
1649 together. When this happens, you must manually merge the two
1652 If you need some documentation to understand and resolve
1653 conflicts, see paragraphs @emph{How conflicts are presented} and
1654 @emph{How to resolve conflicts} in @command{git merge} man page.
1656 If all else fails, you can follow the instructions in
1657 @ref{Reverting all local changes}. Be aware that this eliminates
1658 any changes you have made!
1661 @node Reverting all local changes
1662 @subsection Reverting all local changes
1664 Sometimes git will become hopelessly confused, and you just want
1665 to get back to a known, stable state. This command destroys any
1666 local changes you have made in the currently checked-out branch,
1667 but at least you get back to the current online version:
1670 git reset --hard origin/master
1674 @node Working with remote branches
1675 @subsection Working with remote branches
1678 @subsubheading Fetching new branches from git.sv.gnu.org
1680 To fetch and check out a new branch named @code{@var{branch}} on
1681 git.sv.gnu.org, run from top of the Git repository
1684 git config --add remote.origin.fetch \
1685 +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
1687 git checkout --track -b @var{branch} origin/@var{branch}
1690 After this, you can pull @code{@var{branch}} from git.sv.gnu.org
1697 Note that this command generally fetches all branches you added
1698 with @command{git@tie{}remote@tie{}add} (when you initialized the
1699 repository) or @command{git@tie{}config@tie{}--add}, i.e. it
1700 updates all remote branches from remote @code{origin}, then it
1701 merges the remote branch tracked by the current branch into the
1702 current branch. For example, if your current branch is
1703 @code{master}, @code{origin/master} will be merged into
1707 @subsubheading Local clones, or having several working trees
1709 If you play with several Git branches, e.g. @code{master},
1710 @code{translation}, @code{stable/2.12}), you may want to
1711 have one source and build tree for each branch; this is possible
1712 with subdirectories of your local Git repository, used as local
1713 cloned subrepositories. To create a local clone for the branch
1714 named @code{@var{branch}}, run
1717 git checkout @var{branch}
1718 git clone -lsn . @var{subdir}
1723 Note that @code{@var{subdir}} must be a directory name which does
1724 not already exist. In @code{@var{subdir}}, you can use all Git
1725 commands to browse revisions history, commit and uncommit changes;
1726 to update the cloned subrepository with changes made on the main
1727 repository, cd into @code{@var{subdir}} and run
1728 @command{git@tie{}pull}; to send changes made on the subrepository
1729 back to the main repository, run @command{git@tie{}push} from
1730 @code{@var{subdir}}. Note that only one branch (the currently
1731 checked out branch) is created in the subrepository by default; it
1732 is possible to have several branches in a subrepository and do
1733 usual operations (checkout, merge, create, delete...) on these
1734 branches, but this possibility is not detailed here.
1736 When you push @code{@var{branch}} from @code{@var{subdir}} to the
1737 main repository, and @code{@var{branch}} is checked out in the
1738 main repository, you must save uncommitted changes (see
1739 @command{git@tie{}stash}) and do
1740 @command{git@tie{}reset@tie{}--hard} in the main repository in
1741 order to apply pushed changes in the working tree of the main
1749 The commands above don't only bring you the latest version of the
1750 sources, but also the full history of revisions (revisions, also
1751 called commits, are changes made to the sources), stored in the
1752 @file{.git} directory. You can browse this history with
1755 git log # only shows the logs (author, committish and commit message)
1756 git log -p # also shows diffs
1757 gitk # shows history graphically
1760 @warning{The @code{gitk} command may require a separate
1761 @code{gitk} package, available in the appropriate distribution's
1765 @node Applying remote patches
1766 @subsection Applying remote patches
1769 TODO: Explain how to determine if a patch was created with
1770 @code{git@tie{}format-patch}.
1772 Well-formed git patches created with @code{git@tie{}format-patch}
1773 should be committed with the following command:
1779 Patches created without @code{git@tie{}format-patch} can be
1780 applied in two steps. The first step is to apply the patch to the
1781 working tree and the index:
1784 git apply --index @var{patch}
1788 The second step is to commit the changes and give credit to the
1789 author of the patch. This can be done with the following command:
1792 git commit --author="@var{John Smith} <@var{john@@example.com}>"
1795 Please note that using the @code{--index} option for patching is quite
1796 important here and @emph{cannot} reliably be replaced by using the
1797 @code{-a} option when committing: that would only commit files from the
1798 working tree that are already registered with git, so every file that
1799 the patch actually @emph{adds}, like a regtest for a fixed bug, would
1800 get lost. For the same reason, you should not use the git-independent
1801 @samp{patch} program for applying patches.
1803 @node Sending and receiving patches via email
1804 @subsection Sending and receiving patches via email
1807 The default @code{x-diff} MIME type associated with patch files
1808 (i.e., files whose name ends in @code{.patch}) means that the
1809 encoding of line endings may be changed from UNIX to DOS format
1810 when they are sent as attachments. Attempting to apply such an
1811 inadvertently altered patch will cause git to fail with a message
1812 about @q{whitespace errors}.
1814 The solution to such problems is surprisingly simple---just change
1815 the default file extension of patches generated by git to end in
1816 @code{.txt}, for example:
1819 git config format.suffix '.patch.txt'
1822 This should cause email programs to apply the correct base64
1823 encoding to attached patches.
1825 If you receive a patch with DOS instead of UNIX line-endings, it
1826 can be converted back using the @code{dos2unix} utility.
1828 Lots of useful information on email complications with patches is
1829 provided on the Wine wiki at
1830 @uref{http://wiki.winehq.org/GitWine}.
1833 @node Cleaning up multiple patches
1834 @subsection Cleaning up multiple patches
1836 If you have been developing on your own branch for a while, you
1837 may have more commmits than is really sensible. To revise your
1838 work and condense commits, use:
1841 git rebase origin/master
1842 git rebase -i origin/master
1845 @warning{Be a bit cautious -- if you completely remove commits
1846 during the interactive session, you will... err... completely
1847 remove those commits.}
1851 @subsection Commit access
1853 Most contributors are not able to commit patches directly to the
1854 main repository---only members of the LilyPond development team
1855 have @emph{commit access}. If you are a contributor and are
1856 interested in joining the development team, contact the Project
1857 Manager through the mailing list
1858 (@email{lilypond-devel@@gnu.org}). Generally, only contributors
1859 who have already provided a number of patches which have been
1860 pushed to the main repository will be considered for membership.
1862 If you have been approved by the Project Manager, use the
1863 following procedure to obtain commit access:
1867 If you don't already have one, set up a Savannah user account at
1868 @uref{https://savannah.gnu.org/account/register.php}. If your web
1869 browser responds with an @qq{untrusted connection} message when
1870 you visit the link, follow the steps for including the CAcert root
1871 certificate in your browser, given at
1872 @uref{http://savannah.gnu.org/tls/tutorial/}.
1874 @warning{Savannah will silently put your username in lower-case --
1875 do not try to use capital letters.}
1879 After registering, if you are not logged in automatically, login
1880 at @uref{https://savannah.gnu.org/account/login.php}---this should
1881 take you to your @qq{my} page
1882 (@uref{https://savannah.gnu.org/my/}).
1886 Click on the @qq{My Groups} link to access the @qq{My Group
1887 Membership} page. From there, find the @qq{Request for Inclusion}
1888 box and search for @qq{LilyPond}. Among the search results, check
1889 the box labeled @qq{GNU LilyPond Music Typesetter} and write a
1890 brief (required) message for the Project Manager (@qq{Hey it's
1891 me!} should be fine).
1893 Note that you will not have commit access until the Project
1894 Manager activates your membership. Once your membership is
1895 activated, LilyPond should appear under the heading @qq{Groups I'm
1896 Contributor of} on your @qq{My Group Membership} page.
1900 Generate an SSH @q{rsa} key pair. Enter the following at the
1907 When prompted for a location to save the key, press <ENTER> to
1908 accept the default location (@file{~/.ssh/id_rsa}).
1910 Next you are asked to enter an optional passphrase. On most
1911 systems, if you use a passphrase, you will likely be prompted for
1912 it every time you use @command{git@tie{}push} or
1913 @command{git@tie{}pull}. You may prefer this since it can protect
1914 you from your own mistakes (like pushing when you mean to pull),
1915 though you may find it tedious to keep re-entering it.
1917 You can change/enable/disable your passphrase at any time with:
1920 ssh-keygen -f ~/.ssh/id_rsa -p
1923 Note that the GNOME desktop has a feature which stores your
1924 passphrase for you for an entire GNOME session. If you use a
1925 passphrase to @qq{protect you from yourself}, you will want to
1926 disable this feature, since you'll only be prompted once. Run the
1927 following command, then logout of GNOME and log back in:
1930 gconftool-2 --set -t bool \
1931 /apps/gnome-keyring/daemon-components/ssh false
1934 After setting up your passphrase, your private key is saved as
1935 @file{~/.ssh/id_rsa} and your public key is saved as
1936 @file{~/.ssh/id_rsa.pub}.
1940 Register your public SSH @q{rsa} key with Savannah. From the
1941 @qq{My Account Configuration} page, click on @qq{Edit SSH Keys},
1942 then paste the contents of your @file{~/.ssh/id_rsa.pub} file into
1943 one of the @qq{Authorized keys} text fields, and click
1946 Savannah should respond with something like:
1949 Success: Key #1 seen Keys registered
1954 Configure Git to use the SSH protocol (instead of the GIT
1955 protocol). From your local Git repository, enter:
1958 git config remote.origin.url \
1959 ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1963 replacing @var{user} with your Savannah username.
1967 After your membership has been activated and you've configured Git
1968 to use SSH, test the connection with:
1974 SSH should issue the following warning:
1977 The authenticity of host 'git.sv.gnu.org (140.186.70.72)' can't
1979 RSA key fingerprint is
1980 80:5a:b0:0c:ec:93:66:29:49:7e:04:2b:fd:ba:2c:d5.
1981 Are you sure you want to continue connecting (yes/no)?
1984 Make sure the RSA key fingerprint displayed matches the one above.
1985 If it doesn't, respond @qq{no} and check that you configured Git
1986 properly in the previous step. If it does match, respond
1987 @qq{yes}. SSH should then issue another warning:
1990 Warning: Permanently added 'git.sv.gnu.org,140.186.70.72' (RSA) to
1991 the list of known hosts.
1994 The list of known hosts is stored in the file
1995 @file{~/.ssh/known_hosts}.
1997 At this point, you are prompted for your passphrase if you have
1998 one, then Git will attempt a pull.
2000 If @command{git@tie{}pull@tie{}--verbose} fails, you should see
2001 error messages like these:
2004 Permission denied (publickey).
2005 fatal: The remote end hung up unexpectedly
2008 If you get the above error, you may have made a mistake when
2009 registering your SSH key at Savannah. If the key is properly
2010 registered, you probably just need to wait for the Savannah server
2011 to activate it. It usually takes a few minutes for the key to be
2012 active after registering it, but if it still doesn't work after an
2013 hour, ask for help on the mailing list.
2015 If @command{git@tie{}pull@tie{}--verbose} succeeds, the output
2016 will include a @q{From} line that shows @q{ssh} as the protocol:
2019 From ssh://git.sv.gnu.org/srv/git/lilypond
2022 If the protocol shown is not @q{ssh}, check that you configured
2023 Git properly in the previous step.
2027 Test your commit access with a dry run:
2029 @warning{Do not push directly to master; instead, push to staging.
2030 See @ref{Pushing to staging}.}
2033 git push --dry-run --verbose
2036 Note that recent versions of Git (Git 1.6.3 or later) will issue a
2037 big warning if the above command is used. The simplest solution
2038 is to tell Git to push all matching branches by default:
2041 git config push.default matching
2045 Then @code{git@tie{}push} should work as before. For more
2046 details, consult the @code{git@tie{}push} man page.
2050 Repeat the steps from generating an RSA key through to testing
2051 your commit access, for each machine from which you will be
2052 making commits, or you may simply copy the files from your
2053 local @file{~/.ssh} folder to the same folder on the other
2058 @subsubheading Technical details
2062 On Firefox, to view or remove the CAcert root certificate, go to:
2063 Edit > Preferences > Advanced > Encryption > View Certificates >
2064 Authorities > Certificate Name > Root CA > CA Cert Signing
2068 The @command{git@tie{}config} commands above should modify your
2069 local repository's @file{.git/config} file. These lines:
2073 url = git://git.sv.gnu.org/lilypond.git/
2077 should now be changed to:
2081 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
2085 where @var{user} is your login name on Savannah.
2089 @command{git@tie{}config@tie{}push.default@tie{}matching} command
2090 should add these lines to @file{.git/config}:
2099 Encryption protocols, including ssh, generally do not permit packet
2100 fragmentation to avoid introducing a point of insecurity. This
2101 means that the maximum packet size must not exceed the smallest
2102 MTU (Maximum Transmission Unit) set in the routers along the path.
2103 This smallest MTU is determined by a procedure during call set-up
2104 which relies on the transmission over the path of ICMP packets.
2105 If any of the routers in the path block ICMP packets this mechanism
2106 fails, resulting in the possibility of packets being transmitted
2107 which exceed the MTU of one of the routers. If this happens the
2108 packet is discarded, causing the ssh session to hang, timeout or
2109 terminate with the error message
2112 ssh: connect to host <host ip addr> port 22: Bad file number
2113 fatal: The remote end hung up unexpectedly
2116 depending on precisely when in the proceedings the first large
2117 packet is transmitted. Most routers on the internet have MTU
2118 set to 1500, but routers installed in homes to connect via
2119 broadband may use a slightly smaller MTU for efficient transmission
2120 over ATM. If this problem is encountered a possible work-around is
2121 to set the MTU in the local router to 1500.
2124 @node Pushing to staging
2125 @subsection Pushing to staging
2127 Do not push directly to the git @code{master} branch. Instead,
2128 push to @code{staging}.
2130 You will not see your patch on @code{origin/master} until some
2131 automatic tests have been run. These tests are run every couple
2132 of hours; please wait at least 12 hours before wondering if your
2133 patch has been lost. Note that you can check the commits on
2134 @code{origin/staging} by looking at the git web interface on
2137 It may happen occasionally that the staging branch breaks automated
2138 testing. In this case the automatic move of staging material to
2139 master gets halted in order to avoid broken material entering master.
2140 This is a safety net. Please do not try breaking out from it by
2141 adding fixes on top of staging: in that case the whole sequence will
2142 end up in master after all, defeating the purpose of the system. The
2143 proper fix usually involves rewriting the staging branch and is best
2144 left to core developers after discussion on the developer list.
2146 @subsubheading If your work is in a patch file
2148 Assuming that your patch is in a file called
2149 @file{0001-my-patch.patch}, and you are currently on git master,
2153 git checkout staging
2155 git am 0001-my-patch.patch
2157 git push origin staging
2161 @warning{Do not skip the @command{gitk} step; a quick 5-second
2162 check of the visual history can save a great deal of frustration
2163 later on. You should only see that @command{staging} is only 1
2164 commit ahead of @code{origin/staging}.}
2166 @subsubheading If your work is in a branch
2168 If you are working on branches and your work in is
2169 @code{my_branch_name}, then do:
2172 git checkout staging
2174 git merge my_branch_name
2176 git push origin staging
2179 @warning{Do not skip the @command{gitk} step; a quick 5-second
2180 check of the visual history can save a great deal of frustration
2181 later on. You should see that @code{staging} is only ahead of
2182 @code{origin/staging} by the commits from your branch.}
2186 @node Git on Windows
2187 @section Git on Windows
2189 @warning{We heavily recommend that development be done with our
2190 virtual machine @ref{LilyDev}.}
2192 @c Some of this may duplicate stuff in other sections
2193 @c But it is probably best for windows users to have it all together
2194 @c If necessary, clear this up later -td
2196 TODO: Decide what to do with this... Pare it down? Move
2197 paragraphs next to analogous Unix instructions? -mp
2199 @subsection Background to nomenclature
2201 Git is a system for tracking the changes made to source files by a
2202 distributed set of editors. It is designed to work without a
2203 master repository, but we have chosen to have a master repository
2204 for LilyPond files. Editors hold a local copy of the master
2205 repository together with any changes they have made locally.
2206 Local changes are held in a local @q{branch}, of which there may
2207 be several, but these instructions assume you are using just one.
2208 The files visible in the local repository always correspond to
2209 those on the currently @q{checked out} local branch.
2211 Files are edited on a local branch, and in that state the changes
2212 are said to be @q{unstaged}. When editing is complete, the
2213 changes are moved to being @q{staged for commit}, and finally the
2214 changes are @q{committed} to the local branch. Once committed,
2215 the changes (called a @q{commit}) are given a unique 40-digit
2216 hexadecimal reference number called the @q{Committish} or @q{SHA1
2217 ID} which identifies the commit to Git. Such committed changes
2218 can be sent to the master repository by @q{pushing} them (if you
2219 have write permission) or by sending them by email to someone who
2220 has, either as a complete file or as a @q{diff} or @q{patch}
2221 (which send just the differences from the master repository).
2223 @subsection Installing git
2226 @uref{http://code.google.com/p/msysgit/downloads/list} (note, not
2227 msysGit, which is for Git developers and not PortableGit, which is
2228 not a full git installation) and install it.
2230 Note that most users will not need to install SSH. That is not
2231 required until you have been granted direct push permissions to
2232 the master git repository.
2234 Start Git by clicking on the desktop icon. This will bring up a
2235 command line bash shell. This may be unfamiliar to Windows users.
2236 If so, follow these instructions carefully. Commands are entered
2237 at a $ prompt and are terminated by keying a newline.
2239 @subsection Initialising Git
2241 Decide where you wish to place your local Git repository, creating
2242 the folders in Windows as necessary. Here we call the folder to
2243 contain the repository @code{[path]/Git}, but if you intend using
2244 Git for other projects a directory name like @code{lilypond-git}
2245 might be better. You will need to have space for around
2248 Start the Git bash shell by clicking on the desk-top icon
2249 installed with Git and type
2255 to position the shell at your new Git repository.
2257 Note: if [path] contains folders with names containing spaces use
2269 to initialize your Git repository.
2271 Then type (all on one line; the shell will wrap automatically)
2274 git remote add -ft master origin git://git.sv.gnu.org/lilypond.git
2277 to download the lilypond master files.
2279 @warning{Be patient! Even on a broadband connection this can take
2280 10 minutes or more. Wait for lots of [new tag] messages and the $
2283 We now need to generate a local copy of the downloaded files in a
2284 new local branch. Your local branch needs to have a name. It is
2285 usual to call it @q{master} and we shall do that here.
2290 git checkout -b master origin/master
2293 This creates a second branch called @q{master}. You will see two
2294 warnings (ignore these), and a message advising you that your
2295 local branch @q{master} has been set up to track the remote
2296 branch. You now have two branches, a local branch called
2297 @q{master}, and a tracking branch called @q{origin/master}, which
2298 is a shortened form of @q{remotes/origin/master}.
2300 Return to Windows Explorer and look in your Git repository. You
2301 should see lots of folders. For example, the LilyPond
2302 documentation can be found in [path]/Git/Documentation/.
2304 The Git bash shell is terminated by typing @code{exit} or by
2305 clicking on the usual Windows close-window widget.
2309 Almost all subsequent work will use the Git Graphical User
2310 Interface, which avoids having to type command line commands. To
2311 start Git GUI first start the Git bash shell by clicking on the
2312 desktop icon, and type
2319 The Git GUI will open in a new window. It contains four panels
2320 and 7 pull-down menus. At this stage do not use any of the
2321 commands under Branch, Commit, Merge or Remote. These will be
2324 The top panel on the left contains the names of files which you
2325 are in the process of editing (Unstaged Changes), and the lower
2326 panel on the left contains the names of files you have finished
2327 editing and have staged ready for committing (Staged Changes). At
2328 present, these panels will be empty as you have not yet made any
2329 changes to any file. After a file has been edited and saved the
2330 top panel on the right will display the differences between the
2331 edited file selected in one of the panels on the left and the last
2332 version committed on the current branch.
2334 The panel at bottom right is used to enter a descriptive message
2335 about the change before committing it.
2337 The Git GUI is terminated by entering CNTL-Q while it is the
2338 active window or by clicking on the usual Windows close-window
2341 @subsection Personalising your local git repository
2343 Open the Git GUI, click on
2349 and enter your name and email address in the left-hand (Git
2350 Repository) panel. Leave everything else unchanged and save it.
2352 Note that Windows users must leave the default setting for line
2353 endings unchanged. All files in a git repository must have lines
2354 terminated by just a LF, as this is required for Merge to work,
2355 but Windows files are terminated by CRLF by default. The git
2356 default setting causes the line endings of files in a Windows git
2357 repository to be flipped automatically between LF and CRLF as
2358 required. This enables files to be edited by any Windows editor
2359 without causing problems in the git repository.
2361 @subsection Checking out a branch
2363 At this stage you have two branches in your local repository,
2364 both identical. To see them click on
2370 You should have one local branch called @q{master} and one
2371 tracking branch called @q{origin/master}. The latter is your
2372 local copy of the @q{remotes/origin/master} branch in the master
2373 LilyPond repository. The local @q{master} branch is where you
2374 will make your local changes.
2376 When a particular branch is selected, i.e., checked out, the files
2377 visible in your repository are changed to reflect the state of the
2378 files on that branch.
2380 @subsection Updating files from @q{remote/origin/master}
2382 Before starting the editing of a file, ensure your local
2383 repository contains the latest version of the files in the remote
2384 repository by first clicking
2387 Remote -> Fetch from -> origin
2393 This will place the latest version of every file, including all
2394 the changes made by others, into the @q{origin/master} branch of
2395 the tracking branches in your git repository. You can see these
2396 files by checking out this branch, but you must @emph{never} edit
2397 any files while this branch is checked out. Check out your local
2398 @q{master} branch again.
2400 You then need to merge these fetched files into your local
2401 @q{master} branch by clicking on
2404 Merge -> Local Merge
2408 and if necessary select the local @q{master} branch.
2410 Note that a merge cannot be completed if you have made any local
2411 changes which have not yet been committed.
2413 This merge will update all the files in the @q{master} branch to
2414 reflect the current state of the @q{origin/master} branch. If any
2415 of the changes conflict with changes you have made yourself
2416 recently you will be notified of the conflict (see below).
2418 @subsection Editing files
2420 First ensure your @q{master} branch is checked out, then simply
2421 edit the files in your local Git repository with your favourite
2422 editor and save them back there. If any file contains non-ASCII
2423 characters ensure you save it in UTF-8 format. Git will detect
2424 any changes whenever you restart Git GUI and the file names will
2425 then be listed in the Unstaged Changes panel. Or you can click
2426 the Rescan button to refresh the panel contents at any time. You
2427 may break off and resume editing any time.
2429 The changes you have made may be displayed in diff form in the top
2430 right-hand panel of Git GUI by clicking on the file name shown in
2431 one of the left panels.
2433 When your editing is complete, move the files from being Unstaged
2434 to Staged by clicking the document symbol to the left of each
2435 name. If you change your mind it can be moved back by clicking on
2436 the ticked box to the left of the name.
2438 Finally the changes you have made may be committed to your
2439 @q{master} branch by entering a brief message in the Commit
2440 Message box and clicking the Commit button.
2442 If you wish to amend your changes after a commit has been made,
2443 the original version and the changes you made in that commit may
2444 be recovered by selecting
2447 Commit -> Amend Last Commit
2451 or by checking the Amend Last Commit radio button at bottom right.
2452 This will return the changes to the Staged state, so further
2453 editing made be carried out within that commit. This must only be
2454 done @emph{before} the changes have been Pushed or sent to your
2455 mentor for Pushing - after that it is too late and corrections
2456 have to be made as a separate commit.
2459 @subsection Sending changes to @q{remotes/origin/master}
2461 If you do not have write access to @q{remotes/origin/master} you
2462 will need to send your changes by email to someone who does.
2464 First you need to create a diff or patch file containing your
2465 changes. To create this, the file must first be committed. Then
2466 terminate the Git GUI. In the git bash shell first cd to your Git
2473 if necessary, then produce the patch with
2476 git format-patch origin
2479 This will create a patch file for all the locally committed files
2480 which differ from @q{origin/master}. The patch file can be found
2481 in [path]/Git and will have a name formed from the commit message.
2483 @subsection Resolving merge conflicts
2485 As soon as you have committed a changed file your local
2486 @code{master} branch has diverged from @code{origin/master}, and
2487 will remain diverged until your changes have been committed in
2488 @code{remotes/origin/master} and Fetched back into your
2489 @code{origin/master} branch. Similarly, if a new commit has been
2490 made to @code{remotes/origin/master} by someone else and Fetched,
2491 your local @code{master} branch is divergent. You can detect a
2492 divergent branch by clicking on
2495 Repository -> Visualise all branch history
2498 This opens up a very useful new window called @q{gitk}. Use this
2499 to browse all the commits made by yourself and others.
2501 If the diagram at top left of the resulting window does not show
2502 your @code{master} tag on the same node as the
2503 @code{remotes/origin/master} tag your branch has diverged from
2504 @code{origin/master}. This is quite normal if files you have
2505 modified yourself have not yet been Pushed to
2506 @code{remotes/origin/master} and Fetched, or if files modified and
2507 committed by others have been Fetched since you last Merged
2508 @code{origin/master} into your local @code{master} branch.
2510 If a file being merged from @code{origin/master} differs from one
2511 you have modified in a way that cannot be resolved automatically
2512 by git, Merge will report a Conflict which you must resolve by
2513 editing the file to create the version you wish to keep.
2515 This could happen if the person updating
2516 @code{remotes/origin/master} for you has added some changes of his
2517 own before committing your changes to
2518 @code{remotes/origin/master}, or if someone else has changed the
2519 same file since you last fetched the file from
2520 @code{remotes/origin/master}.
2522 Open the file in your editor and look for sections which are
2525 [to be completed when I next have a merge conflict to be sure I
2526 give the right instructions -td]
2529 @subsection Other actions
2531 The instructions above describe the simplest way of using git on
2532 Windows. Other git facilities which may usefully supplement these
2536 @item Using multiple local branches (Create, Rename, Delete)
2537 @item Resetting branches
2538 @item Cherry-picking commits
2539 @item Pushing commits to @w{remote/origin/master}
2540 @item Using gitk to review history
2543 Once familiarity with using git on Windows has been gained the
2544 standard git manuals can be used to learn about these.
2547 @node Repository directory structure
2548 @section Repository directory structure
2551 @c TODO: integrate the roadmap better
2552 @verbatiminclude ROADMAP
2555 @node Other Git documentation
2556 @section Other Git documentation
2560 Official git man pages:
2561 @uref{http://www.kernel.org/pub/software/scm/git/docs/}
2564 More in-depth tutorials: @uref{http://git-scm.com/documentation}
2567 Book about git: @uref{http://progit.org/,Pro Git}
2570 Github help: @uref{http://help.github.com/}
2571 (very highly recommended by Graham)