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{Using 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{Daily use of lily-git.tcl}.
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 * Downloading remote branches::
119 @subsection Setting up
121 @warning{These instructions assume that you are using the
122 command-line version of Git 1.5 or higher. Windows users should
123 skip to @ref{Git on Windows}.}
127 * Initializing a repository::
133 @unnumberedsubsubsec Installing Git
135 If you are using a Unix-based machine, the easiest way to download
136 and install Git is through a package manager such as @command{rpm}
137 or @command{apt-get} -- the installation is generally automatic.
138 The only required package is (usually) called @command{git-core},
139 although some of the auxiliary @command{git@var{*}} packages are
140 also useful (such as @command{gitk}).
142 Alternatively, you can visit the Git website
143 (@uref{http://git-scm.com/}) for downloadable binaries and
147 @node Initializing a repository
148 @unnumberedsubsubsec Initializing a repository
150 Once Git is installed, get a copy of the source code:
153 git clone git://git.sv.gnu.org/lilypond.git ~/lilypond-git
156 The above command will put the it in @file{~/lilypond-git}, where
157 @code{~} represents your home directory.
159 @subsubheading Technical details
161 This creates (within the @file{~/lilypond-git/} directory) a
162 subdirectory called @file{.git/}, which Git uses to keep track of
163 changes to the repository, among other things. Normally you don't
164 need to access it, but it's good to know it's there.
167 @node Configuring Git
168 @unnumberedsubsubsec Configuring Git
170 @warning{Throughout the rest of this manual, all command-line
171 input should be entered from the top directory of the Git
172 repository being discussed (eg. @file{~/lilypond-git/}). This is
173 referred to as the @emph{top source directory}.}
175 Before working with the copy of the main LilyPond repository, you
176 should configure some basic settings with the
177 @command{git@tie{}config} command. Git allows you to set both
178 global and repository-specific options.
180 To configure settings that affect all repositories, use the
181 @option{--global} command line option. For example, the first
182 two options that you should always set are your @var{name} and
183 @var{email}, since Git needs these to keep track of commit
187 git config --global user.name "@var{John Smith}"
188 git config --global user.email @var{john@@example.com}
191 To configure Git to use colored output where possible, use:
194 git config --global color.ui auto
197 The text editor that opens when using @command{git@tie{}commit}
198 can also be changed. If none of your editor-related environment
199 variables are set ($GIT_EDITOR, $VISUAL, or $EDITOR), the default
200 editor is usually @command{vi} or @command{vim}. If you're not
201 familiar with either of these, you should probably change the
202 default to an editor that you know how to use. For example, to
203 change the default editor to @command{nano}, enter:
206 git config --global core.editor @var{nano}
209 @subsubheading Technical details
211 Git stores the information entered with
212 @command{git@tie{}config@tie{}--global} in the file
213 @file{.gitconfig}, located in your home directory. This file can
214 also be modified directly, without using
215 @command{git@tie{}config}. The @file{.gitconfig} file generated
216 by the above commands would look like this:
221 email = john@@example.com
228 Using the @command{git@tie{}config} command @emph{without} the
229 @option{--global} option configures repository-specific settings,
230 which are stored in the file @file{.git/config}. This file is
231 created when a repository is initialized (using
232 @command{git@tie{}init}), and by default contains these lines:
236 repositoryformatversion = 0
239 logallrefupdates = true
242 However, since different repository-specific options are
243 recommended for different development tasks, it is best to avoid
244 setting any now. Specific recommendations will be mentioned later
248 @node Downloading remote branches
249 @subsection Downloading remote branches
253 * Organization of remote branches::
254 * LilyPond repository sources::
255 * Downloading individual branches::
256 * Downloading all remote branches::
261 @node Organization of remote branches
262 @unnumberedsubsubsec Organization of remote branches
265 The main LilyPond repository is organized into @emph{branches} to
266 facilitate development. These are often called @emph{remote}
267 branches to distinguish them from @emph{local} branches you might
268 create yourself (see @ref{Using local branches}).
270 The @code{master} branch contains all the source files used to
271 build LilyPond, which includes the program itself (both stable and
272 development releases), the documentation (and its translations),
273 and the website. Generally, the @code{master} branch is expected
274 to compile successfully.
276 The @code{lilypond/translation} branch is a side branch that
277 allows translators to work without needing to worry about
278 compilation problems. Periodically, the Translation Meister
279 (after verifying that it doesn't break compilation), will
280 @emph{merge} this branch back into @code{master} to incorporate
281 recent translations. Similarly, the @code{master} branch is
282 usually merged into the @code{lilypond/translation} branch after
283 significant changes to the English documentation. See
284 @ref{Translating the documentation} for details.
287 @node LilyPond repository sources
288 @unnumberedsubsubsec LilyPond repository sources
291 The recommended source for downloading a copy of the main
295 git://git.sv.gnu.org/lilypond.git
298 However, if your internet router filters out connections using the
299 GIT protocol, or if you experience difficulty connecting via GIT,
300 you can try these other sources:
303 ssh://git.sv.gnu.org/srv/git/lilypond.git
304 http://git.sv.gnu.org/r/lilypond.git
307 The SSH protocol can only be used if your system is properly set
308 up to use it. Also, the HTTP protocol is slowest, so it should
309 only be used as a last resort.
312 @node Downloading individual branches
313 @unnumberedsubsubsec Downloading individual branches
316 Once you have initialized an empty Git repository on your system
317 (see @ref{Initializing a repository}), you can download a remote
318 branch into it. Make sure you know which branch you want to start
321 To download the @code{master} branch, enter the following:
324 git remote add -ft master -m master \
325 origin git://git.sv.gnu.org/lilypond.git/
328 To download the @code{lilypond/translation} branch, enter:
331 git remote add -ft lilypond/translation -m \
332 lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
335 The @command{git@tie{}remote@tie{}add} process could take up to
336 ten minutes, depending on the speed of your connection. The
337 output will be something like this:
341 remote: Counting objects: 235967, done.
342 remote: Compressing objects: 100% (42721/42721), done.
343 remote: Total 235967 (delta 195098), reused 233311 (delta 192772)
344 Receiving objects: 100% (235967/235967), 68.37 MiB | 479 KiB/s, done.
345 Resolving deltas: 100% (195098/195098), done.
346 From git://git.sv.gnu.org/lilypond
347 * [new branch] master -> origin/master
348 From git://git.sv.gnu.org/lilypond
349 * [new tag] flower/1.0.1 -> flower/1.0.1
350 * [new tag] flower/1.0.10 -> flower/1.0.10
352 * [new tag] release/2.9.6 -> release/2.9.6
353 * [new tag] release/2.9.7 -> release/2.9.7
356 When @command{git@tie{}remote@tie{}add} is finished, the remote
357 branch should be downloaded into your repository---though not yet
358 in a form that you can use. In order to browse the source code
359 files, you need to @emph{create} and @emph{checkout} your own
360 local branch. In this case, however, it is easier to have Git
361 create the branch automatically by using the @command{checkout}
362 command on a non-existent branch. Enter the following:
365 git checkout -b @var{branch} origin/@var{branch}
369 where @code{@var{branch}} is the name of your tracking branch,
370 either @code{master} or @code{lilypond/translation}.
372 Git will issue some warnings; this is normal:
375 warning: You appear to be on a branch yet to be born.
376 warning: Forcing checkout of origin/master.
377 Branch master set up to track remote branch master from origin.
381 By now the source files should be accessible---you should be able
382 to edit any files in the @file{lilypond-git/} directory using a
383 text editor of your choice. But don't start just yet! Before
384 editing any source files, learn how to keep your changes organized
385 and prevent problems later---read @ref{Basic Git procedures}.
387 @subsubheading Technical Details
389 The @command{git@tie{}remote@tie{}add} command should add some
390 lines to your local repository's @file{.git/config} file:
394 url = git://git.sv.gnu.org/lilypond.git/
395 fetch = +refs/heads/master:refs/remotes/origin/master
399 @node Downloading all remote branches
400 @unnumberedsubsubsec Downloading all remote branches
403 To download all remote branches at once, you can @command{clone}
404 the entire repository:
407 git clone git://git.sv.gnu.org/lilypond.git
412 @unnumberedsubsubsec Other branches
414 Most contributors will never need to touch the other branches. If
415 you wish to do so, you will need more familiarity with Git; please
416 see @ref{Other Git documentation}.
419 @item @code{dev/XYZ}:
420 These branches are for individual developers. They store code
421 which is not yet stable enough to be added to the @code{master}
424 @item @code{stable/XYZ}:
425 The branches are kept for archival reasons.
429 Another item of interest might be the Grand Unified Builder, our
430 cross-platform building tool. Since it is used by projects as
431 well, it is not stored in our gub repository. For more info, see
432 @uref{http://lilypond.org/gub}. The git location is
433 @uref{http://github.com/janneke/gub}.
436 @node Basic Git procedures
437 @section Basic Git procedures
441 * The Git contributor's cycle::
442 * Pulling and rebasing::
443 * Using local branches::
444 * Commits and patches::
448 @node The Git contributor's cycle
449 @subsection The Git contributor's cycle
452 Here is a simplified view of the contribution process on Git:
456 Update your local repository by @emph{pulling} the most recent
457 updates from the remote repository.
460 Edit source files within your local repository's @emph{working
464 @emph{Commit} the changes you've made to a local @emph{branch}.
467 Generate a @emph{patch} to share your changes with the developers.
471 @node Pulling and rebasing
472 @subsection Pulling and rebasing
475 When developers push new patches to the @code{git.sv.gnu.org}
476 repository, your local repository is @strong{not} automatically
477 updated. It is important to keep your repository up-to-date by
478 periodically @emph{pulling} the most recent @emph{commits} from
479 the remote branch. Developers expect patches to be as current as
480 possible, since outdated patches require extra work before they
483 Occasionally you may need to rework some of your own modifications
484 to match changes made to the remote branch (see @ref{Resolving
485 conflicts}), and it's considerably easier to rework things
486 incrementally. If you don't update your repository along the way,
487 you may have to spend a lot of time resolving branch conflicts and
488 reconfiguring much of the work you've already done.
490 Fortunately, Git is able to resolve certain types of branch
491 conflicts automatically with a process called @emph{rebasing}.
492 When rebasing, Git tries to modify your old commits so they appear
493 as new commits (based on the latest updates). For a more involved
494 explanation, see the @command{git-rebase} man page.
496 To pull without rebasing (recommended for translators), use the
500 git pull # recommended for translators
503 If you're tracking the remote @code{master} branch, you should add
504 the @option{-r} option (short for @option{--rebase}) to keep commits
505 on your local branch current:
508 git pull -r # use with caution when translating
511 If you don't edit translated documentation and don't want to type
512 @option{-r} every time, configure the master branch to rebase by
513 default with this command:
516 git config branch.master.rebase true
519 If pull fails because of a message like
522 error: Your local changes to 'Documentation/learning/tutorial.itely'
523 would be overwritten by merge. Aborting.
530 Documentation/learning/tutorial.itely: needs update
531 refusing to pull with rebase: your working tree is not up-to-date
535 it means that you have modified some files in you working tree
536 without committing changes (see @ref{Commits and patches}); you
537 can use the @command{git@tie{}stash} command to work around this:
540 git stash # save uncommitted changes
541 git pull -r # pull using rebase (translators omit "-r")
542 git stash pop # reapply previously saved changes
545 Note that @command{git@tie{}stash@tie{}pop} will try to apply a
546 patch, and this may create a conflict. If this happens, see
547 @ref{Resolving conflicts}.
549 TODO: I think the next paragraph is confusing. Perhaps prepare
550 the reader for new terms `committish' and `head'? -mp
552 @warning{translators and documentation editors, if you have
553 changed committishes in the head of translated files using commits
554 you have not yet pushed to @code{git.sv.gnu.org}, please do not
555 rebase. If you want to avoid wondering whether you should rebase
556 each time you pull, please always use committishes from master
557 and/or lilypond/translation branch on @code{git.sv.gnu.org}, which
558 in particular implies that you must push your changes to
559 documentation except committishes updates (possibly after having
560 rebased), then update the committishes and push them.}
562 TODO: when committishes automatic conditional update have been
563 tested and documented, append the following to the warning above:
564 Note that using update-committishes make target generally touches
567 @subsubheading Technical details
569 The @command{git@tie{}config} command mentioned above adds the
570 line @code{rebase = true} to the master branch in your local
571 repository's @file{.git/config} file:
576 merge = refs/heads/master
581 @node Using local branches
582 @subsection Using local branches
586 * Creating and removing branches::
587 * Listing branches and remotes::
588 * Checking out branches::
593 @node Creating and removing branches
594 @unnumberedsubsubsec Creating and removing branches
597 Local branches are useful when you're working on several different
598 projects concurrently. To create a new branch, enter:
601 git branch @var{name}
604 To delete a branch, enter:
607 git branch -d @var{name}
610 Git will ask you for confirmation if it sees that data would be
611 lost by deleting the branch. Use @option{-D} instead of @option{-d}
612 to bypass this. Note that you cannot delete a branch if it is
613 currently checked out.
616 @node Listing branches and remotes
617 @unnumberedsubsubsec Listing branches and remotes
619 You can get the exact path or URL of all remote branches by
626 To list Git branches on your local repositories, run
629 git branch # list local branches only
630 git branch -r # list remote branches
631 git branch -a # list all branches
635 @node Checking out branches
636 @unnumberedsubsubsec Checking out branches
638 To know the currently checked out branch, i.e. the branch whose
639 source files are present in your working tree, read the first line
647 The currently checked out branch is also marked with an asterisk
648 in the output of @command{git branch}.
650 You can check out another branch @code{@var{other_branch}}, i.e.
651 check out @code{@var{other_branch}} to the working tree, by
655 git checkout @var{other_branch}
658 Note that it is possible to check out another branch while having
659 uncommitted changes, but it is not recommended unless you know
660 what you are doing; it is recommended to run @command{git status}
661 to check this kind of issue before checking out another branch.
663 @node Merging branches
664 @unnumberedsubsubsec Merging branches
666 To merge branch @code{@var{foo}} into branch @code{@var{bar}},
667 i.e. to @qq{add} all changes made in branch @code{@var{foo}} to
668 branch @code{@var{bar}}, run
671 git checkout @var{bar}
675 If any conflict happens, see @ref{Resolving conflicts}.
677 There are common usage cases for merging: as a translator, you
678 will often want to merge @code{master} into
679 @code{lilypond/translation}; on the other hand, the Translations
680 meister wants to merge @code{lilypond/translation} into
681 @code{master} whenever he has checked that
682 @code{lilypond/translation} builds successfully.
685 @node Commits and patches
686 @subsection Commits and patches
690 * Understanding commits::
694 * Uploading a patch for review::
698 @node Understanding commits
699 @unnumberedsubsubsec Understanding commits
701 Technically, a @emph{commit} is a single point in the history of a
702 branch, but most developers use the term to mean a @emph{commit
703 object}, which stores information about a particular revision. A
704 single commit can record changes to multiple source files, and
705 typically represents one logical set of related changes (such as a
706 bug-fix). You can list the ten most recent commits in your
707 current branch with this command:
710 git log -10 --oneline
713 If you're using an older version of Git and get an @q{unrecognized
714 argument} error, use this instead:
717 git log -10 --pretty=oneline --abbrev-commit
720 More interactive lists of the commits on the remote @code{master}
721 branch are available at
722 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=shortlog} and
723 @uref{http://git.sv.gnu.org/cgit/lilypond.git/log/}.
727 @unnumberedsubsubsec Making commits
730 Once you have modified some source files in your working
731 directory, you can make a commit with the following procedure:
735 Make sure you've configured Git properly (see @ref{Configuring
736 Git}). Check that your changes meet the requirements described in
737 @ref{Code style} and/or @ref{Documentation policy}. For advanced
738 edits, you may also want to verify that the changes don't break
739 the compilation process.
742 Run the following command:
749 to make sure you're on the right branch, and to see which files
750 have been modified, added or removed, etc. You may need to tell
751 Git about any files you've added by running one of these:
754 git add @var{file} # add untracked @var{file} individually
755 git add . # add all untracked files in current directory
759 After @command{git@tie{}add}, run @command{git@tie{}status} again
760 to make sure you got everything. You may also need to modify
764 Preview the changes about to be committed (to make sure everything
772 The @code{HEAD} argument refers to the most recent commit on the
773 currently checked-out branch.
776 Generate the commit with:
783 The @option{-a} is short for @option{--all} which includes modified
784 and deleted files, but only those newly created files that have
785 previously been added.
790 @node Commit messages
791 @unnumberedsubsubsec Commit messages
794 When you run the @command{git@tie{}commit@tie{}-a} command, Git
795 automatically opens the default text editor so you can enter a
796 @emph{commit message}. If you find yourself in a foreign editing
797 environment, you're probably in @command{vi} or @command{vim}. If
798 you want to switch to an editor you're more familiar with, quit by
799 typing @code{:q!} and pressing @code{<Enter>}. See
800 @ref{Configuring Git} for instructions on changing the default
803 In any case, Git will open a text file for your commit message
804 that looks like this:
808 # Please enter the commit message for your changes. Lines starting
809 # with '#' will be ignored, and an empty message aborts the commit.
811 # Changes to be committed:
812 # (use "git reset HEAD <file>..." to unstage)
814 # modified: working.itexi
818 Your commit message should begin with a one-line summary
819 describing the change (no more than 50 characters long), and if
820 necessary a blank line followed by several lines giving the
823 @c $ git log -1 --pretty=medium 4d6f1e5
825 Doc: add Baerenreiter and Henle solo cello suites
827 Added comparison of solo cello suite engravings to new essay with
828 high-res images, fixed cropping on Finale example.
831 Commit messages often start with a short prefix describing the
832 general location of the changes. If a commit affects the
833 documentation in English (or in several languages simultaneously)
834 the commit message should be prefixed with @qq{Doc:@tie{}}. If
835 the commit affects only one of the translations, the commit
836 message should be prefixed with @qq{Doc-@var{**}:@tie{}}, where
837 @var{**} is the two-letter language code. Commits that affect the
838 website should use @qq{Web:@tie{}} for English, and
839 @qq{Web-@var{**}:@tie{}} for the other languages. Also, changes
840 to a single file are often prefixed with the name of the file
841 involved. Visit the links listed in @ref{Understanding commits}
846 @unnumberedsubsubsec Making patches
848 If you want to share your changes with other contributors and
849 developers, you need to generate @emph{patches} from your commits.
850 We prefer it if you follow the instructions in
851 @ref{Uploading a patch for review}. However, we present an
852 alternate method here.
854 You should always run @command{git@tie{}pull@tie{}-r} (translators
855 should leave off the @option{-r}) before doing this to ensure that
856 your patches are as current as possible.
858 Once you have made one or more commits in your local repository,
859 and pulled the most recent commits from the remote branch, you can
860 generate patches from your local commits with the command:
863 git format-patch origin
866 The @code{origin} argument refers to the remote tracking branch at
867 @code{git.sv.gnu.org}. This command generates a separate patch
868 for each commit that's in the current branch but not in the remote
869 branch. Patches are placed in the current working directory and
870 will have names that look something like this:
873 0001-Doc-Fix-typos.patch
874 0002-Web-Remove-dead-links.patch
878 Send an email (must be less than 64 KB) to
879 @email{lilypond-devel@@gnu.org} briefly explaining your work, with
880 the patch files attached. Translators should send patches to
881 @email{translations@@lilynet.net}. After your patches are
882 reviewed, the developers may push one or more of them to the main
883 repository or discuss them with you.
886 @node Uploading a patch for review
887 @unnumberedsubsubsec Uploading a patch for review
889 Any non-trivial change should be uploaded to our @qq{Rietveld}
893 @uref{http://codereview.appspot.com/}
896 @subsubheading @command{git-cl} install
898 LilyDev users should skip over these @q{install} instructions.
903 Install @command{git-cl} by entering:
906 git clone https://github.com/gperciva/git-cl.git
909 If that command fails for some reason, try this instead:
912 git clone git://github.com/gperciva/git-cl.git
916 Add the @file{git-cl/} directory to your PATH,
917 or create a symbolic link to the @command{git-cl}
918 and @command{upload.py} scripts in one of your PATH
919 directories (such as @file{$HOME/bin}).
921 In Ubuntu (and Lilydev), you can add directories to PATH
922 by adding this line to a hidden file @file{.bashrc},
923 located in your home directory:
926 PATH=~/type-here-directory-containing-git-cl:"$@{PATH@}"
931 @subsubheading @command{git-cl} configuration
933 LilyDev users should perform these @q{configuration} instructions.
937 You must have a google account; please create one if you do not
940 Note that a google account does not need to be a gmail account; you can
941 use any email address for your google account when you sign up.
944 Move into the top source directory and then configure @command{git
945 cl} with the following commands. If you do not understand any
946 question, just answer with a newline (CR).
949 cd $HOME/lilypond-git/
953 The @qq{CC list} question should be answered with:
956 lilypond-devel@@gnu.org
961 @subsubheading Uploading patch set
963 @warning{Unless you are familiar with branches, only work on one
964 set of changes at once.}
966 There are two methods, depending on your git setup.
970 @strong{Master branch}: (easy option, and used in @command{lily-git.tcl})
972 If you added your patch to @code{master}, then:
976 git cl upload origin/master
979 If you have git push ability, make sure that you @emph{remove}
980 your patch (with @command{git rebase} or @command{git reset})
981 before pushing other stuff.
983 @c don't make this one an @example; we don't want to make it easy
984 @c for people to use this accidently
985 Notifications of patches are automatically added to our issue
986 tracker to reduce the chance of patches getting lost. To suppress
987 this (not recommended), add the @code{-n / --no-code-issue}
991 @strong{Separate branch}: (complicated option)
993 Ensure your changes are committed in a separate branch, which
994 should differ from the reference branch to be used by just the
995 changes to be uploaded. If the reference branch is to be
996 origin/master, ensure this is up-to-date. If necessary, use git
997 rebase to rebase the branch containing the changes to the head of
998 origin/master. Finally, check out branch with the changes and
1002 git cl upload <reference SHA1 ID>
1006 where <reference SHA1 ID> is the SHA1 ID of the commit to be used
1007 as a reference source for the patch. Generally, this will be the
1008 SHA1 ID of origin/master, and in that case the command:
1011 git cl upload origin/master
1019 After prompting for your Google email address and password, the
1020 patch set will be posted to Rietveld, and you will be given a URL
1023 @warning{Some installations of git-cl fail when uploading a patch
1024 with certain filename extensions. If this happens, it can
1025 generally be fixed by editing the list of exceptions at top of
1028 @subsubheading Announcing your patch set
1030 You should then announce the patch by logging into the code review
1031 issue webpage and using @qq{Publish + Mail Comments} to add a
1032 (mostly bogus) comment to your issue. The text of your comment
1033 will be sent to our developer mailing list.
1035 @warning{There is no automatic notification of a new patch; you
1036 must add a comment yourself.}
1038 @subsubheading Revisions
1040 As revisions are made in response to comments, successive patch sets
1041 for the same issue can be uploaded by reissuing the git-cl command
1042 with the modified branch checked out.
1044 Sometimes in response to comments on revisions, the best way to
1045 work may require creation of a new branch in git. In order to
1046 associate the new branch with an existing Rietveld issue,
1047 the following command can be used:
1050 git cl issue issue-number
1054 where @code{issue-number} is the number of the existing Rietveld
1057 @subsubheading Resetting git cl
1059 If @command{git cl} becomes confused, you can @qq{reset} it by
1066 @subsubheading Wait for a countdown
1068 Your patch will be available for reviews for the next few hours or
1069 days. Three times a week, patches with no known problems are
1070 gathered into a @qq{patch countdown} and their status changed to
1071 @code{patch-countdown}. The countdown is a 48-hour waiting period
1072 in which any final reviews or complaints should be made.
1074 During the countdown, your patch may be set to
1075 @code{patch-needs_work}, indicating that you should fix something
1076 (or at least discuss why the patch needs no modification). If no
1077 problems are found, the patch will be set to @code{patch-push}.
1079 Once a patch has @code{patch-push}, it should be sent to your
1080 mentor for uploading. If you have git push ability, look at
1081 @ref{Pushing to staging}.
1084 @node Advanced Git procedures
1085 @section Advanced Git procedures
1088 @warning{This section is not necessary for normal contributors;
1089 these commands are presented for information for people interested
1090 in learning more about git.}
1092 It is possible to work with several branches on the same local Git
1093 repository; this is especially useful for translators who may have
1094 to deal with both @code{lilypond/translation} and a stable branch,
1095 e.g. @code{stable/2.12}.
1097 Some Git commands are introduced first, then a workflow with
1098 several Git branches of LilyPond source code is presented.
1102 * Advanced Git concepts::
1103 * Resolving conflicts::
1104 * Reverting all local changes::
1105 * Working with remote branches::
1107 * Applying remote patches::
1108 * Sending and receiving patches via email::
1109 * Cleaning up multiple patches::
1111 * Pushing to staging::
1115 @node Advanced Git concepts
1116 @subsection Advanced Git concepts
1119 A bit of Git vocabulary will be explained below. The following is
1120 only introductory; for a better understanding of Git concepts, you
1121 may wish to read @ref{Other Git documentation}.
1123 The @code{git@tie{}pull@tie{}origin} command above is just a
1124 shortcut for this command:
1127 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
1131 where @code{@var{branch}} is typically @code{master} or
1132 @code{lilypond/translation}; if you do not know or remember, see
1133 @ref{Downloading remote branches} to remember which commands you
1134 issued or which source code you wanted to get.
1136 A @emph{commit} is a set of changes made to the sources; it also
1137 includes the committish of the parent commit, the name and e-mail
1138 of the @emph{author} (the person who wrote the changes), the name
1139 and e-mail of the @emph{committer} (the person who brings these
1140 changes into the Git repository), and a commit message.
1142 A @emph{committish} is the SHA1 checksum of a commit, a number
1143 made of 40 hexadecimal digits, which acts as the internal unique
1144 identifier for this commit. To refer to a particular revision,
1145 don't use vague references like the (approximative) date, simply
1146 copy and paste the committish.
1148 A @emph{branch} is nothing more than a pointer to a particular
1149 commit, which is called the @emph{head} of the branch; when
1150 referring to a branch, one often actually thinks about its head
1151 and the ancestor commits of the head.
1153 Now we will explain the two last commands you used to get the
1154 source code from Git---see @ref{Downloading individual branches}.
1157 git remote add -ft @var{branch} -m @var{branch} \
1158 origin git://git.sv.gnu.org/lilypond.git/
1160 git checkout -b @var{branch} origin/@var{branch}
1163 The @command{git@tie{}remote} has created a branch called
1164 @code{origin/@var{branch}} in your local Git repository. As this
1165 branch is a copy of the remote branch web from git.sv.gnu.org
1166 LilyPond repository, it is called a @emph{remote branch}, and is
1167 meant to track the changes on the branch from git.sv.gnu.org: it
1168 will be updated every time you run
1169 @command{git@tie{}pull@tie{}origin} or
1170 @command{git@tie{}fetch@tie{}origin}.
1172 The @command{git@tie{}checkout} command has created a branch named
1173 @code{@var{branch}}. At the beginning, this branch is identical
1174 to @code{origin/@var{branch}}, but it will differ as soon as you
1175 make changes, e.g. adding newly translated pages or editing some
1176 documentation or code source file. Whenever you pull, you merge
1177 the changes from @code{origin/@var{branch}} and
1178 @code{@var{branch}} since the last pulling. If you do not have
1179 push (i.e. @qq{write}) access on git.sv.gnu.org, your
1180 @code{@var{branch}} will always differ from
1181 @code{origin/@var{branch}}. In this case, remember that other
1182 people working like you with the remote branch @code{@var{branch}}
1183 of git://git.sv.gnu.org/lilypond.git/ (called
1184 @code{origin/@var{branch}} on your local repository) know nothing
1185 about your own @code{@var{branch}}: this means that whenever you
1186 use a committish or make a patch, others expect you to take the
1187 latest commit of @code{origin/@var{branch}} as a reference.
1189 Finally, please remember to read the man page of every Git command
1190 you will find in this manual in case you want to discover
1191 alternate methods or just understand how it works.
1194 @node Resolving conflicts
1195 @subsection Resolving conflicts
1198 Occasionally an update may result in conflicts -- this happens
1199 when you and somebody else have modified the same part of the same
1200 file and git cannot figure out how to merge the two versions
1201 together. When this happens, you must manually merge the two
1204 If you need some documentation to understand and resolve
1205 conflicts, see paragraphs @emph{How conflicts are presented} and
1206 @emph{How to resolve conflicts} in @command{git merge} man page.
1208 If all else fails, you can follow the instructions in
1209 @ref{Reverting all local changes}. Be aware that this eliminates
1210 any changes you have made!
1213 @node Reverting all local changes
1214 @subsection Reverting all local changes
1216 Sometimes git will become hopelessly confused, and you just want
1217 to get back to a known, stable state. This command destroys any
1218 local changes you have made in the currently checked-out branch,
1219 but at least you get back to the current online version:
1222 git reset --hard origin/master
1226 @node Working with remote branches
1227 @subsection Working with remote branches
1230 @subsubheading Fetching new branches from git.sv.gnu.org
1232 To fetch and check out a new branch named @code{@var{branch}} on
1233 git.sv.gnu.org, run from top of the Git repository
1236 git config --add remote.origin.fetch \
1237 +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
1239 git checkout --track -b @var{branch} origin/@var{branch}
1242 After this, you can pull @code{@var{branch}} from git.sv.gnu.org
1249 Note that this command generally fetches all branches you added
1250 with @command{git@tie{}remote@tie{}add} (when you initialized the
1251 repository) or @command{git@tie{}config@tie{}--add}, i.e. it
1252 updates all remote branches from remote @code{origin}, then it
1253 merges the remote branch tracked by the current branch into the
1254 current branch. For example, if your current branch is
1255 @code{master}, @code{origin/master} will be merged into
1259 @subsubheading Local clones, or having several working trees
1261 If you play with several Git branches, e.g. @code{master},
1262 @code{lilypond/translation}, @code{stable/2.12}), you may want to
1263 have one source and build tree for each branch; this is possible
1264 with subdirectories of your local Git repository, used as local
1265 cloned subrepositories. To create a local clone for the branch
1266 named @code{@var{branch}}, run
1269 git checkout @var{branch}
1270 git clone -lsn . @var{subdir}
1275 Note that @code{@var{subdir}} must be a directory name which does
1276 not already exist. In @code{@var{subdir}}, you can use all Git
1277 commands to browse revisions history, commit and uncommit changes;
1278 to update the cloned subrepository with changes made on the main
1279 repository, cd into @code{@var{subdir}} and run
1280 @command{git@tie{}pull}; to send changes made on the subrepository
1281 back to the main repository, run @command{git@tie{}push} from
1282 @code{@var{subdir}}. Note that only one branch (the currently
1283 checked out branch) is created in the subrepository by default; it
1284 is possible to have several branches in a subrepository and do
1285 usual operations (checkout, merge, create, delete...) on these
1286 branches, but this possibility is not detailed here.
1288 When you push @code{@var{branch}} from @code{@var{subdir}} to the
1289 main repository, and @code{@var{branch}} is checked out in the
1290 main repository, you must save uncommitted changes (see
1291 @command{git@tie{}stash}) and do
1292 @command{git@tie{}reset@tie{}--hard} in the main repository in
1293 order to apply pushed changes in the working tree of the main
1301 The commands above don't only bring you the latest version of the
1302 sources, but also the full history of revisions (revisions, also
1303 called commits, are changes made to the sources), stored in the
1304 @file{.git} directory. You can browse this history with
1307 git log # only shows the logs (author, committish and commit message)
1308 git log -p # also shows diffs
1309 gitk # shows history graphically
1312 @warning{The @code{gitk} command may require a separate
1313 @code{gitk} package, available in the appropriate distribution's
1317 @node Applying remote patches
1318 @subsection Applying remote patches
1321 TODO: Explain how to determine if a patch was created with
1322 @code{git@tie{}format-patch}.
1324 Well-formed git patches created with @code{git@tie{}format-patch}
1325 should be committed with the following command:
1331 Patches created without @code{git@tie{}format-patch} can be
1332 applied in two steps. The first step is to apply the patch to the
1336 git apply @var{patch}
1340 The second step is to commit the changes and give credit to the
1341 author of the patch. This can be done with the following command:
1344 git commit -a --author="@var{John Smith} <@var{john@@example.com}>"
1348 @node Sending and receiving patches via email
1349 @subsection Sending and receiving patches via email
1352 The default @code{x-diff} MIME type associated with patch files
1353 (i.e., files whose name ends in @code{.patch}) means that the
1354 encoding of line endings may be changed from UNIX to DOS format
1355 when they are sent as attachments. Attempting to apply such an
1356 inadvertently altered patch will cause git to fail with a message
1357 about @q{whitespace errors}.
1359 The solution to such problems is surprisingly simple---just change
1360 the default file extension of patches generated by git to end in
1361 @code{.txt}, for example:
1364 git config format.suffix '.patch.txt'
1367 This should cause email programs to apply the correct base64
1368 encoding to attached patches.
1370 If you receive a patch with DOS instead of UNIX line-endings, it
1371 can be converted back using the @code{dos2unix} utility.
1373 Lots of useful information on email complications with patches is
1374 provided on the Wine wiki at
1375 @uref{http://wiki.winehq.org/GitWine}.
1378 @node Cleaning up multiple patches
1379 @subsection Cleaning up multiple patches
1381 If you have been developing on your own branch for a while, you
1382 may have more commmits than is really sensible. To revise your
1383 work and condense commits, use:
1386 git rebase origin/master
1387 git rebase -i origin/master
1390 @warning{Be a bit cautious -- if you completely remove commits
1391 during the interactive session, you will... err... completely
1392 remove those commits.}
1396 @subsection Commit access
1398 Most contributors are not able to commit patches directly to the
1399 main repository---only members of the LilyPond development team
1400 have @emph{commit access}. If you are a contributor and are
1401 interested in joining the development team, contact the Project
1402 Manager through the mailing list
1403 (@email{lilypond-devel@@gnu.org}). Generally, only contributors
1404 who have already provided a number of patches which have been
1405 pushed to the main repository will be considered for membership.
1407 If you have been approved by the Project Manager, use the
1408 following procedure to obtain commit access:
1412 If you don't already have one, set up a Savannah user account at
1413 @uref{https://savannah.gnu.org/account/register.php}. If your web
1414 browser responds with an @qq{untrusted connection} message when
1415 you visit the link, follow the steps for including the CAcert root
1416 certificate in your browser, given at
1417 @uref{http://savannah.gnu.org/tls/tutorial/}.
1419 @warning{Savannah will silently put your username in lower-case --
1420 do not try to use capital letters.}
1424 After registering, if you are not logged in automatically, login
1425 at @uref{https://savannah.gnu.org/account/login.php}---this should
1426 take you to your @qq{my} page
1427 (@uref{https://savannah.gnu.org/my/}).
1431 Click on the @qq{My Groups} link to access the @qq{My Group
1432 Membership} page. From there, find the @qq{Request for Inclusion}
1433 box and search for @qq{LilyPond}. Among the search results, check
1434 the box labeled @qq{GNU LilyPond Music Typesetter} and write a
1435 brief (required) message for the Project Manager (@qq{Hey it's
1436 me!} should be fine).
1438 Note that you will not have commit access until the Project
1439 Manager activates your membership. Once your membership is
1440 activated, LilyPond should appear under the heading @qq{Groups I'm
1441 Contributor of} on your @qq{My Group Membership} page.
1445 Generate an SSH @q{rsa} key pair. Enter the following at the
1452 When prompted for a location to save the key, press <ENTER> to
1453 accept the default location (@file{~/.ssh/id_rsa}).
1455 Next you are asked to enter an optional passphrase. On most
1456 systems, if you use a passphrase, you will likely be prompted for
1457 it every time you use @command{git@tie{}push} or
1458 @command{git@tie{}pull}. You may prefer this since it can protect
1459 you from your own mistakes (like pushing when you mean to pull),
1460 though you may find it tedious to keep re-entering it.
1462 You can change/enable/disable your passphrase at any time with:
1465 ssh-keygen -f ~/.ssh/id_rsa -p
1468 Note that the GNOME desktop has a feature which stores your
1469 passphrase for you for an entire GNOME session. If you use a
1470 passphrase to @qq{protect you from yourself}, you will want to
1471 disable this feature, since you'll only be prompted once. Run the
1472 following command, then logout of GNOME and log back in:
1475 gconftool-2 --set -t bool \
1476 /apps/gnome-keyring/daemon-components/ssh false
1479 After setting up your passphrase, your private key is saved as
1480 @file{~/.ssh/id_rsa} and your public key is saved as
1481 @file{~/.ssh/id_rsa.pub}.
1485 Register your public SSH @q{rsa} key with Savannah. From the
1486 @qq{My Account Configuration} page, click on @qq{Edit SSH Keys},
1487 then paste the contents of your @file{~/.ssh/id_rsa.pub} file into
1488 one of the @qq{Authorized keys} text fields, and click
1491 Savannah should respond with something like:
1494 Success: Key #1 seen Keys registered
1499 Configure Git to use the SSH protocol (instead of the GIT
1500 protocol). From your local Git repository, enter:
1503 git config remote.origin.url \
1504 ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1508 replacing @var{user} with your Savannah username.
1512 After your membership has been activated and you've configured Git
1513 to use SSH, test the connection with:
1519 SSH should issue the following warning:
1522 The authenticity of host 'git.sv.gnu.org (140.186.70.72)' can't
1524 RSA key fingerprint is
1525 80:5a:b0:0c:ec:93:66:29:49:7e:04:2b:fd:ba:2c:d5.
1526 Are you sure you want to continue connecting (yes/no)?
1529 Make sure the RSA key fingerprint displayed matches the one above.
1530 If it doesn't, respond @qq{no} and check that you configured Git
1531 properly in the previous step. If it does match, respond
1532 @qq{yes}. SSH should then issue another warning:
1535 Warning: Permanently added 'git.sv.gnu.org,140.186.70.72' (RSA) to
1536 the list of known hosts.
1539 The list of known hosts is stored in the file
1540 @file{~/.ssh/known_hosts}.
1542 At this point, you are prompted for your passphrase if you have
1543 one, then Git will attempt a pull.
1545 If @command{git@tie{}pull@tie{}--verbose} fails, you should see
1546 error messages like these:
1549 Permission denied (publickey).
1550 fatal: The remote end hung up unexpectedly
1553 If you get the above error, you may have made a mistake when
1554 registering your SSH key at Savannah. If the key is properly
1555 registered, you probably just need to wait for the Savannah server
1556 to activate it. It usually takes a few minutes for the key to be
1557 active after registering it, but if it still doesn't work after an
1558 hour, ask for help on the mailing list.
1560 If @command{git@tie{}pull@tie{}--verbose} succeeds, the output
1561 will include a @q{From} line that shows @q{ssh} as the protocol:
1564 From ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond
1567 If the protocol shown is not @q{ssh}, check that you configured
1568 Git properly in the previous step.
1572 Test your commit access with a dry run:
1574 @warning{Do not push directly to master; instead, push to staging.
1575 See @ref{Pushing to staging}.}
1578 git push --dry-run --verbose
1581 Note that recent versions of Git (Git 1.6.3 or later) will issue a
1582 big warning if the above command is used. The simplest solution
1583 is to tell Git to push all matching branches by default:
1586 git config push.default matching
1590 Then @code{git@tie{}push} should work as before. For more
1591 details, consult the @code{git@tie{}push} man page.
1595 Repeat the steps from generating an RSA key through to testing
1596 your commit access, for each machine from which you will be
1597 making commits, or you may simply copy the files from your
1598 local @file{~/.ssh} folder to the same folder on the other
1603 @subsubheading Technical details
1607 On Firefox, to view or remove the CAcert root certificate, go to:
1608 Edit > Preferences > Advanced > Encryption > View Certificates >
1609 Authorities > Certificate Name > Root CA > CA Cert Signing
1613 The @command{git@tie{}config} commands above should modify your
1614 local repository's @file{.git/config} file. These lines:
1618 url = git://git.sv.gnu.org/lilypond.git/
1622 should now be changed to:
1626 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1630 where @var{user} is your login name on Savannah.
1634 @command{git@tie{}config@tie{}push.default@tie{}matching} command
1635 should add these lines to @file{.git/config}:
1644 Encryption protocols, including ssh, generally do not permit packet
1645 fragmentation to avoid introducing a point of insecurity. This
1646 means that the maximum packet size must not exceed the smallest
1647 MTU (Maximum Transmission Unit) set in the routers along the path.
1648 This smallest MTU is determined by a procedure during call set-up
1649 which relies on the transmission over the path of ICMP packets.
1650 If any of the routers in the path block ICMP packets this mechanism
1651 fails, resulting in the possibility of packets being transmitted
1652 which exceed the MTU of one of the routers. If this happens the
1653 packet is discarded, causing the ssh session to hang, timeout or
1654 terminate with the error message
1657 ssh: connect to host <host ip addr> port 22: Bad file number
1658 fatal: The remote end hung up unexpectedly
1661 depending on precisely when in the proceedings the first large
1662 packet is transmitted. Most routers on the internet have MTU
1663 set to 1500, but routers installed in homes to connect via
1664 broadband may use a slightly smaller MTU for efficient transmission
1665 over ATM. If this problem is encountered a possible work-around is
1666 to set the MTU in the local router to 1500.
1669 @node Pushing to staging
1670 @subsection Pushing to staging
1672 Do not push directly to the git @code{master} branch. Instead,
1673 push to @code{staging}.
1675 You will not see your patch on @code{origin/master} until some
1676 automatic tests have been run. These tests are run every couple
1677 of hours; please wait at least 12 hours before wondering if your
1678 patch has been lost. Note that you can check the commits on
1679 @code{origin/staging} by looking at the git web interface on
1682 @subsubheading If your work is in a patch file
1684 Assuming that your patch is in a file called
1685 @file{0001-my-patch.patch}, and you are currently on git master,
1689 git checkout staging
1691 git am 0001-my-patch.patch
1693 git push origin staging
1697 @warning{Do not skip the @command{gitk} step; a quick 5-second
1698 check of the visual history can save a great deal of frustration
1699 later on. You should only see that @command{staging} is only 1
1700 commit ahead of @code{origin/staging}.}
1702 @subsubheading If your work is in a branch
1704 If you are working on branches and your work in is
1705 @code{my_branch_name}, then do:
1708 git checkout staging
1710 git merge my_branch_name
1712 git push origin staging
1715 @warning{Do not skip the @command{gitk} step; a quick 5-second
1716 check of the visual history can save a great deal of frustration
1717 later on. You should see that @code{staging} is only ahead of
1718 @code{origin/staging} by the commits from your branch.}
1722 @node Git on Windows
1723 @section Git on Windows
1725 @warning{We heavily recommend that development be done with our
1726 virtual machine @ref{Lilydev}.}
1728 @c Some of this may duplicate stuff in other sections
1729 @c But it is probably best for windows users to have it all together
1730 @c If necessary, clear this up later -td
1732 TODO: Decide what to do with this... Pare it down? Move
1733 paragraphs next to analogous Unix instructions? -mp
1735 @subsection Background to nomenclature
1737 Git is a system for tracking the changes made to source files by a
1738 distributed set of editors. It is designed to work without a
1739 master repository, but we have chosen to have a master repository
1740 for LilyPond files. Editors hold a local copy of the master
1741 repository together with any changes they have made locally.
1742 Local changes are held in a local @q{branch}, of which there may
1743 be several, but these instructions assume you are using just one.
1744 The files visible in the local repository always correspond to
1745 those on the currently @q{checked out} local branch.
1747 Files are edited on a local branch, and in that state the changes
1748 are said to be @q{unstaged}. When editing is complete, the
1749 changes are moved to being @q{staged for commit}, and finally the
1750 changes are @q{committed} to the local branch. Once committed,
1751 the changes (called a @q{commit}) are given a unique 40-digit
1752 hexadecimal reference number called the @q{Committish} or @q{SHA1
1753 ID} which identifies the commit to Git. Such committed changes
1754 can be sent to the master repository by @q{pushing} them (if you
1755 have write permission) or by sending them by email to someone who
1756 has, either as a complete file or as a @q{diff} or @q{patch}
1757 (which send just the differences from the master repository).
1759 @subsection Installing git
1762 @uref{http://code.google.com/p/msysgit/downloads/list} (note, not
1763 msysGit, which is for Git developers and not PortableGit, which is
1764 not a full git installation) and install it.
1766 Note that most users will not need to install SSH. That is not
1767 required until you have been granted direct push permissions to
1768 the master git repository.
1770 Start Git by clicking on the desktop icon. This will bring up a
1771 command line bash shell. This may be unfamiliar to Windows users.
1772 If so, follow these instructions carefully. Commands are entered
1773 at a $ prompt and are terminated by keying a newline.
1775 @subsection Initialising Git
1777 Decide where you wish to place your local Git repository, creating
1778 the folders in Windows as necessary. Here we call the folder to
1779 contain the repository @code{[path]/Git}, but if you intend using
1780 Git for other projects a directory name like @code{lilypond-git}
1781 might be better. You will need to have space for around
1784 Start the Git bash shell by clicking on the desk-top icon
1785 installed with Git and type
1791 to position the shell at your new Git repository.
1793 Note: if [path] contains folders with names containing spaces use
1805 to initialize your Git repository.
1807 Then type (all on one line; the shell will wrap automatically)
1810 git remote add -ft master origin git://git.sv.gnu.org/lilypond.git
1813 to download the lilypond master files.
1815 @warning{Be patient! Even on a broadband connection this can take
1816 10 minutes or more. Wait for lots of [new tag] messages and the $
1819 We now need to generate a local copy of the downloaded files in a
1820 new local branch. Your local branch needs to have a name. It is
1821 usual to call it @q{master} and we shall do that here.
1826 git checkout -b master origin/master
1829 This creates a second branch called @q{master}. You will see two
1830 warnings (ignore these), and a message advising you that your
1831 local branch @q{master} has been set up to track the remote
1832 branch. You now have two branches, a local branch called
1833 @q{master}, and a tracking branch called @q{origin/master}, which
1834 is a shortened form of @q{remotes/origin/master}.
1836 Return to Windows Explorer and look in your Git repository. You
1837 should see lots of folders. For example, the LilyPond
1838 documentation can be found in [path]/Git/Documentation/.
1840 The Git bash shell is terminated by typing @code{exit} or by
1841 clicking on the usual Windows close-window widget.
1845 Almost all subsequent work will use the Git Graphical User
1846 Interface, which avoids having to type command line commands. To
1847 start Git GUI first start the Git bash shell by clicking on the
1848 desktop icon, and type
1855 The Git GUI will open in a new window. It contains four panels
1856 and 7 pull-down menus. At this stage do not use any of the
1857 commands under Branch, Commit, Merge or Remote. These will be
1860 The top panel on the left contains the names of files which you
1861 are in the process of editing (Unstaged Changes), and the lower
1862 panel on the left contains the names of files you have finished
1863 editing and have staged ready for committing (Staged Changes). At
1864 present, these panels will be empty as you have not yet made any
1865 changes to any file. After a file has been edited and saved the
1866 top panel on the right will display the differences between the
1867 edited file selected in one of the panels on the left and the last
1868 version committed on the current branch.
1870 The panel at bottom right is used to enter a descriptive message
1871 about the change before committing it.
1873 The Git GUI is terminated by entering CNTL-Q while it is the
1874 active window or by clicking on the usual Windows close-window
1877 @subsection Personalising your local git repository
1879 Open the Git GUI, click on
1885 and enter your name and email address in the left-hand (Git
1886 Repository) panel. Leave everything else unchanged and save it.
1888 Note that Windows users must leave the default setting for line
1889 endings unchanged. All files in a git repository must have lines
1890 terminated by just a LF, as this is required for Merge to work,
1891 but Windows files are terminated by CRLF by default. The git
1892 default setting causes the line endings of files in a Windows git
1893 repository to be flipped automatically between LF and CRLF as
1894 required. This enables files to be edited by any Windows editor
1895 without causing problems in the git repository.
1897 @subsection Checking out a branch
1899 At this stage you have two branches in your local repository,
1900 both identical. To see them click on
1906 You should have one local branch called @q{master} and one
1907 tracking branch called @q{origin/master}. The latter is your
1908 local copy of the @q{remotes/origin/master} branch in the master
1909 LilyPond repository. The local @q{master} branch is where you
1910 will make your local changes.
1912 When a particular branch is selected, i.e., checked out, the files
1913 visible in your repository are changed to reflect the state of the
1914 files on that branch.
1916 @subsection Updating files from @q{remote/origin/master}
1918 Before starting the editing of a file, ensure your local
1919 repository contains the latest version of the files in the remote
1920 repository by first clicking
1923 Remote -> Fetch from -> origin
1929 This will place the latest version of every file, including all
1930 the changes made by others, into the @q{origin/master} branch of
1931 the tracking branches in your git repository. You can see these
1932 files by checking out this branch, but you must @emph{never} edit
1933 any files while this branch is checked out. Check out your local
1934 @q{master} branch again.
1936 You then need to merge these fetched files into your local
1937 @q{master} branch by clicking on
1940 Merge -> Local Merge
1944 and if necessary select the local @q{master} branch.
1946 Note that a merge cannot be completed if you have made any local
1947 changes which have not yet been committed.
1949 This merge will update all the files in the @q{master} branch to
1950 reflect the current state of the @q{origin/master} branch. If any
1951 of the changes conflict with changes you have made yourself
1952 recently you will be notified of the conflict (see below).
1954 @subsection Editing files
1956 First ensure your @q{master} branch is checked out, then simply
1957 edit the files in your local Git repository with your favourite
1958 editor and save them back there. If any file contains non-ASCII
1959 characters ensure you save it in UTF-8 format. Git will detect
1960 any changes whenever you restart Git GUI and the file names will
1961 then be listed in the Unstaged Changes panel. Or you can click
1962 the Rescan button to refresh the panel contents at any time. You
1963 may break off and resume editing any time.
1965 The changes you have made may be displayed in diff form in the top
1966 right-hand panel of Git GUI by clicking on the file name shown in
1967 one of the left panels.
1969 When your editing is complete, move the files from being Unstaged
1970 to Staged by clicking the document symbol to the left of each
1971 name. If you change your mind it can be moved back by clicking on
1972 the ticked box to the left of the name.
1974 Finally the changes you have made may be committed to your
1975 @q{master} branch by entering a brief message in the Commit
1976 Message box and clicking the Commit button.
1978 If you wish to amend your changes after a commit has been made,
1979 the original version and the changes you made in that commit may
1980 be recovered by selecting
1983 Commit -> Amend Last Commit
1987 or by checking the Amend Last Commit radio button at bottom right.
1988 This will return the changes to the Staged state, so further
1989 editing made be carried out within that commit. This must only be
1990 done @emph{before} the changes have been Pushed or sent to your
1991 mentor for Pushing - after that it is too late and corrections
1992 have to be made as a separate commit.
1995 @subsection Sending changes to @q{remotes/origin/master}
1997 If you do not have write access to @q{remotes/origin/master} you
1998 will need to send your changes by email to someone who does.
2000 First you need to create a diff or patch file containing your
2001 changes. To create this, the file must first be committed. Then
2002 terminate the Git GUI. In the git bash shell first cd to your Git
2009 if necessary, then produce the patch with
2012 git format-patch origin
2015 This will create a patch file for all the locally committed files
2016 which differ from @q{origin/master}. The patch file can be found
2017 in [path]/Git and will have a name formed from the commit message.
2019 @subsection Resolving merge conflicts
2021 As soon as you have committed a changed file your local
2022 @code{master} branch has diverged from @code{origin/master}, and
2023 will remain diverged until your changes have been committed in
2024 @code{remotes/origin/master} and Fetched back into your
2025 @code{origin/master} branch. Similarly, if a new commit has been
2026 made to @code{remotes/origin/master} by someone else and Fetched,
2027 your local @code{master} branch is divergent. You can detect a
2028 divergent branch by clicking on
2031 Repository -> Visualise all branch history
2034 This opens up a very useful new window called @q{gitk}. Use this
2035 to browse all the commits made by yourself and others.
2037 If the diagram at top left of the resulting window does not show
2038 your @code{master} tag on the same node as the
2039 @code{remotes/origin/master} tag your branch has diverged from
2040 @code{origin/master}. This is quite normal if files you have
2041 modified yourself have not yet been Pushed to
2042 @code{remotes/origin/master} and Fetched, or if files modified and
2043 committed by others have been Fetched since you last Merged
2044 @code{origin/master} into your local @code{master} branch.
2046 If a file being merged from @code{origin/master} differs from one
2047 you have modified in a way that cannot be resolved automatically
2048 by git, Merge will report a Conflict which you must resolve by
2049 editing the file to create the version you wish to keep.
2051 This could happen if the person updating
2052 @code{remotes/origin/master} for you has added some changes of his
2053 own before committing your changes to
2054 @code{remotes/origin/master}, or if someone else has changed the
2055 same file since you last fetched the file from
2056 @code{remotes/origin/master}.
2058 Open the file in your editor and look for sections which are
2061 [to be completed when I next have a merge conflict to be sure I
2062 give the right instructions -td]
2065 @subsection Other actions
2067 The instructions above describe the simplest way of using git on
2068 Windows. Other git facilities which may usefully supplement these
2072 @item Using multiple local branches (Create, Rename, Delete)
2073 @item Resetting branches
2074 @item Cherry-picking commits
2075 @item Pushing commits to @w{remote/origin/master}
2076 @item Using gitk to review history
2079 Once familiarity with using git on Windows has been gained the
2080 standard git manuals can be used to learn about these.
2083 @node Repository directory structure
2084 @section Repository directory structure
2087 @c TODO: integrate the roadmap better
2088 @verbatiminclude ROADMAP
2091 @node Other Git documentation
2092 @section Other Git documentation
2096 Official git man pages:
2097 @uref{http://www.kernel.org/pub/software/scm/git/docs/}
2100 More in-depth tutorials: @uref{http://git-scm.com/documentation}
2103 Book about git: @uref{http://progit.org/,Pro Git}