1 @c -*- coding: utf-8; mode: texinfo; -*-
4 @node Working with source code
5 @chapter Working with source code
7 New contributors should only read @ref{Using lily-git}. Please
8 ignore the rest of this chapter.
10 Advanced contributors will find the rest of this material quite
11 useful, particularly if they are working on major new features.
16 * Basic Git procedures::
17 * Advanced Git procedures::
19 * Repository directory structure::
20 * Other Git documentation::
24 @c if you change this node name, you'll need to change the @ref in
25 @c web/ and/or included/, along with all the translations.
27 @section Using lily-git
29 @command{lily-git.tcl} is a graphical tool to help you access and
30 share changes to the lilypond source code.
33 * Install and configuration of lily-git.tcl::
34 * Daily use of lily-git.tcl::
37 @node Install and configuration of lily-git.tcl
38 @unnumberedsubsec Install and configuration of @command{lily-git.tcl}
42 If you haven't already, download and install Git.
47 Lilybuntu users: git has already been installed for you.
49 @item Windows users: download the @code{.exe} file labeled
50 @qq{Full installer for official Git} from:
53 @uref{http://code.google.com/p/msysgit/downloads/list}
56 @item Other operating systems: either install @command{git} with
57 your package manager, or download it from the @qq{Binaries}
61 @uref{http://git-scm.com/download}
68 Download the @command{lily-git.tcl} script from:
70 @c don't change the cgit link below to gitweb; gitweb uses
71 @c long filenames like "scripts_auxiliar_lily-git.tcl"
74 @uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
78 To run the program from the command line, navigate to the
79 directory containing @command{lily-git.tcl} and enter:
86 Click on the @qq{Get source} button.
88 This will create a directory called @file{lilypond-git/} within
89 your home directory, and will download the source code into that
90 directory (around 55Mb). When the process is finished, the
91 @qq{Command output} window will display @qq{Done}, and the button
92 label will change to say @qq{Update source}.
95 Navigate to the @file{lilypond-git/} directory to view the source
96 files. You should now be able to modify the source files using
97 your normal text editor.
102 Advanced note: The @qq{Get source} button does not fetch the
103 entire history of the git repository, so utilities like
104 @command{gitk} will only be able to display the most recent
105 additions. As you continue to work with @command{lily-git.tcl}, the
106 @qq{Update source} button will take any new additions and add it
107 to whatever is currently in your repository's history.
111 @node Daily use of lily-git.tcl
112 @unnumberedsubsec Daily use of @command{lily-git.tcl}
114 @warning{Only work on one set of changes at once. Do not start
115 work on any new changes until your first set has been accepted.}
117 @subsubheading 1. Update source
119 At the beginning of each session of lilypond work, you should
120 click the @qq{Update source} button to get the latest changes to
123 @warning{In some rare and unfortunate circumstances, this will
124 result in a @emph{merge conflict}. If this occurs, follow the
125 instructions for @qq{Abort changes}, below. Your work will not be
129 @subsubheading 2a. New local commit
131 A single commit typically represents one logical set of related
132 changes (such as a bug-fix), and may incorporate changes to
133 multiple files at the same time.
135 When you're finished making the changes for a commit, click the
136 @qq{New local commit} button. This will open the @qq{Git Commit
137 Message} window. The message header is required, and the message
140 After entering a commit message, click @qq{OK} to finalize the
144 Advanced note: For more information regarding commits and commit
145 messages, see @ref{Commits and patches}.
149 @subsubheading 2b. Amend previous commit
151 You can go back and make changes to the most recent commit with
152 the @qq{Amend previous commit} button. This is useful if a
153 mistake is found after you have clicked the @qq{New local commit}
156 To amend the most recent commit, re-edit the source files as
157 needed and then click the @qq{Amend previous commit} button. The
158 earlier version of the commit is not saved, but is replaced by the
161 @warning{This does not update the patch @strong{files}; if you
162 have a patch file from an earlier version of the commit, you will
163 need to make another patch set when using this feature. The old
164 patch file will not be saved, but will be replaced by the new one
165 after you click on @qq{Make patch set}.}
168 @subsubheading 3. Make patch set
170 Before making a patch set from any commits, you should click the
171 @qq{Update source} button to make sure the commits are based on
172 the most recent remote snapshot.
174 When you click the @qq{Make patch set} button,
175 @command{lily-git.tcl} will produce patch files for any new
176 commits, saving them to the current directory. The command output
177 will display the name of the new patch files near the end of the
181 0001-CG-add-lily-git-instructions.patch
185 Send patch files to the appropriate place:
189 If you have a mentor, send it to them via email.
192 New contributors should send the patch attached to an email to
193 @email{frogs@@lilynet.net}. Please add @qq{[PATCH]} to the
197 Translators should send patches to
198 @email{translations@@lilynet.net}.
201 More experienced contributors should upload the patch for
202 web-based review. This requires additional software and use of
203 the command-line; see @ref{Uploading a patch for review}.
208 @subsubheading The @qq{Abort changes -- Reset to origin} button
210 @warning{Only use this if your local commit history gets
211 hopelessly confused!}
213 The button labeled @qq{Abort changes -- Reset to origin} will copy
214 all changed files to a subdirectory of @file{lilypond-git/} named
215 @file{aborted_edits/}, and will reset the repository to the
216 current state of the remote repository (at @code{git.sv.gnu.org}).
219 @node Starting with Git
220 @section Starting with Git
223 Using the Git program directly (as opposed to using the
224 @command{lily-git.tcl} GUI) allows you to have much greater control
225 over the contributing process. You should consider using Git if
226 you want to work on complex projects, or if you want to work on
227 multiple projects concurrently.
232 * Downloading remote branches::
237 @subsection Setting up
240 TODO: Remove this note if incorporating Windows instructions
241 throughout this section:
243 @warning{These instructions assume that you are using the
244 command-line version of Git 1.5 or higher. Windows users should
245 skip to @ref{Git on Windows}.}
249 * Initializing a repository::
255 @unnumberedsubsubsec Installing Git
258 If you are using a Unix-based machine, the easiest way to download
259 and install Git is through a package manager such as @command{rpm}
260 or @command{apt-get}---the installation is generally automatic.
261 The only required package is (usually) called @command{git-core},
262 although some of the auxiliary @command{git@var{*}} packages are
263 also useful (such as @command{gitk}).
265 Alternatively, you can visit the Git website
266 (@uref{http://git-scm.com/}) for downloadable binaries and
269 TODO: add Windows installation instructions (or @@ref@{Git on
273 @node Initializing a repository
274 @unnumberedsubsubsec Initializing a repository
277 Once Git is installed, you'll need to create a new directory where
278 your initial repository will be stored (the example below uses
279 @file{~/lilypond-git/}, where @code{~} represents your home
280 directory). Run @command{git@tie{}init} from within the new
281 directory to initialize an empty repository:
284 mkdir ~/lilypond-git/; cd ~/lilypond-git/
288 @subsubheading Technical details
290 This creates (within the @file{~/lilypond-git/} directory) a
291 subdirectory called @file{.git/}, which Git uses to keep track of
292 changes to the repository, among other things. Normally you don't
293 need to access it, but it's good to know it's there.
296 @node Configuring Git
297 @unnumberedsubsubsec Configuring Git
299 @warning{Throughout the rest of this manual, all command-line
300 input should be entered from the top directory of the Git
301 repository being discussed (eg. @file{~/lilypond-git/}). This is
302 referred to as a @emph{top source directory}.}
304 Before downloading a copy of the main LilyPond repository, you
305 should configure some basic settings with the
306 @command{git@tie{}config} command. Git allows you to set both
307 global and repository-specific options.
309 To configure settings that affect all repositories, use the
310 @command{--global} command line option. For example, the first
311 two options that you should always set are your @var{name} and
312 @var{email}, since Git needs these to keep track of commit
316 git config --global user.name "@var{John Smith}"
317 git config --global user.email @var{john@@example.com}
320 To configure Git to use colored output where possible, use:
323 git config --global color.ui auto
326 The text editor that opens when using @command{git@tie{}commit}
327 can also be changed. If none of your editor-related environment
328 variables are set ($GIT_EDITOR, $VISUAL, or $EDITOR), the default
329 editor is usually @command{vi} or @command{vim}. If you're not
330 familiar with either of these, you should probably change the
331 default to an editor that you know how to use. For example, to
332 change the default editor to @command{nano}, enter:
335 git config --global core.editor @var{nano}
338 TODO: Add instructions for changing the editor on Windows, which
339 is a little different, I think. -mp
341 @subsubheading Technical details
343 Git stores the information entered with
344 @command{git@tie{}config@tie{}--global} in the file
345 @file{.gitconfig}, located in your home directory. This file can
346 also be modified directly, without using
347 @command{git@tie{}config}. The @file{.gitconfig} file generated
348 by the above commands would look like this:
353 email = john@@example.com
360 Using the @command{git@tie{}config} command @emph{without} the
361 @command{--global} option configures repository-specific settings,
362 which are stored in the file @file{.git/config}. This file is
363 created when a repository is initialized (using
364 @command{git@tie{}init}), and by default contains these lines:
368 repositoryformatversion = 0
371 logallrefupdates = true
374 However, since different repository-specific options are
375 recommended for different development tasks, it is best to avoid
376 setting any now. Specific recommendations will be mentioned later
380 @node Downloading remote branches
381 @subsection Downloading remote branches
385 * Organization of remote branches::
386 * LilyPond repository sources::
387 * Downloading individual branches::
388 * Downloading all remote branches::
393 @node Organization of remote branches
394 @unnumberedsubsubsec Organization of remote branches
397 The main LilyPond repository is organized into @emph{branches} to
398 facilitate development. These are often called @emph{remote}
399 branches to distinguish them from @emph{local} branches you might
400 create yourself (see @ref{Using local branches}).
402 The @code{master} branch contains all the source files used to
403 build LilyPond, which includes the program itself (both stable and
404 development releases), the documentation (and its translations),
405 and the website. Generally, the @code{master} branch is expected
406 to compile successfully.
408 The @code{lilypond/translation} branch is a side branch that
409 allows translators to work without needing to worry about
410 compilation problems. Periodically, the Translation Meister
411 (after verifying that it doesn't break compilation), will
412 @emph{merge} this branch back into @code{master} to incorporate
413 recent translations. Similarly, the @code{master} branch is
414 usually merged into the @code{lilypond/translation} branch after
415 significant changes to the English documentation. See
416 @ref{Translating the documentation} for details.
419 @node LilyPond repository sources
420 @unnumberedsubsubsec LilyPond repository sources
423 The recommended source for downloading a copy of the main
427 git://git.sv.gnu.org/lilypond.git
430 However, if your internet router filters out connections using the
431 GIT protocol, or if you experience difficulty connecting via GIT,
432 you can try these other sources:
435 ssh://git.sv.gnu.org/srv/git/lilypond.git
436 http://git.sv.gnu.org/r/lilypond.git
439 The SSH protocol can only be used if your system is properly set
440 up to use it. Also, the HTTP protocol is slowest, so it should
441 only be used as a last resort.
444 @node Downloading individual branches
445 @unnumberedsubsubsec Downloading individual branches
448 Once you have initialized an empty Git repository on your system
449 (see @ref{Initializing a repository}), you can download a remote
450 branch into it. Make sure you know which branch you want to start
453 To download the @code{master} branch, enter the following:
456 git remote add -ft master -m master \
457 origin git://git.sv.gnu.org/lilypond.git/
460 To download the @code{lilypond/translation} branch, enter:
463 git remote add -ft lilypond/translation -m \
464 lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
467 The @command{git@tie{}remote@tie{}add} process could take up to
468 ten minutes, depending on the speed of your connection. The
469 output will be something like this:
473 remote: Counting objects: 235967, done.
474 remote: Compressing objects: 100% (42721/42721), done.
475 remote: Total 235967 (delta 195098), reused 233311 (delta 192772)
476 Receiving objects: 100% (235967/235967), 68.37 MiB | 479 KiB/s, done.
477 Resolving deltas: 100% (195098/195098), done.
478 From git://git.sv.gnu.org/lilypond
479 * [new branch] master -> origin/master
480 From git://git.sv.gnu.org/lilypond
481 * [new tag] flower/1.0.1 -> flower/1.0.1
482 * [new tag] flower/1.0.10 -> flower/1.0.10
484 * [new tag] release/2.9.6 -> release/2.9.6
485 * [new tag] release/2.9.7 -> release/2.9.7
488 When @command{git@tie{}remote@tie{}add} is finished, the remote
489 branch should be downloaded into your repository---though not yet
490 in a form that you can use. In order to browse the source code
491 files, you need to @emph{create} and @emph{checkout} your own
492 local branch. In this case, however, it is easier to have Git
493 create the branch automatically by using the @command{checkout}
494 command on a non-existent branch. Enter the following:
497 git checkout -b @var{branch} origin/@var{branch}
501 where @code{@var{branch}} is the name of your tracking branch,
502 either @code{master} or @code{lilypond/translation}.
504 Git will issue some warnings; this is normal:
507 warning: You appear to be on a branch yet to be born.
508 warning: Forcing checkout of origin/master.
509 Branch master set up to track remote branch master from origin.
513 By now the source files should be accessible---you should be able
514 to edit any files in the @file{lilypond-git/} directory using a
515 text editor of your choice. But don't start just yet! Before
516 editing any source files, learn how to keep your changes organized
517 and prevent problems later---read @ref{Basic Git procedures}.
519 @subsubheading Technical Details
521 The @command{git@tie{}remote@tie{}add} command should add some
522 lines to your local repository's @file{.git/config} file:
526 url = git://git.sv.gnu.org/lilypond.git/
527 fetch = +refs/heads/master:refs/remotes/origin/master
531 @node Downloading all remote branches
532 @unnumberedsubsubsec Downloading all remote branches
535 To download all remote branches at once, you can @command{clone}
536 the entire repository:
539 git clone git://git.sv.gnu.org/lilypond.git
544 @unnumberedsubsubsec Other branches
546 Most contributors will never need to touch the other branches. If
547 you wish to do so, you will need more familiarity with Git; please
548 see @ref{Other Git documentation}.
551 @item @code{dev/XYZ}:
552 These branches are for individual developers. They store code
553 which is not yet stable enough to be added to the @code{master}
556 @item @code{stable/XYZ}:
557 The branches are kept for archival reasons.
561 Another item of interest might be the Grand Unified Builder, our
562 cross-platform building tool. Since it is used by projects as
563 well, it is not stored in our gub repository. For more info, see
564 @uref{http://lilypond.org/gub}. The git location is
565 @uref{http://github.com/janneke/gub}.
568 @node Basic Git procedures
569 @section Basic Git procedures
573 * The Git contributor's cycle::
574 * Pulling and rebasing::
575 * Using local branches::
576 * Commits and patches::
580 @node The Git contributor's cycle
581 @subsection The Git contributor's cycle
584 Here is a simplified view of the contribution process on Git:
588 Update your local repository by @emph{pulling} the most recent
589 updates from the remote repository.
592 Edit source files within your local repository's @emph{working
596 @emph{Commit} the changes you've made to a local @emph{branch}.
599 Generate a @emph{patch} to share your changes with the developers.
603 @node Pulling and rebasing
604 @subsection Pulling and rebasing
607 When developers push new patches to the @code{git.sv.gnu.org}
608 repository, your local repository is @strong{not} automatically
609 updated. It is important to keep your repository up-to-date by
610 periodically @emph{pulling} the most recent @emph{commits} from
611 the remote branch. Developers expect patches to be as current as
612 possible, since outdated patches require extra work before they
615 Occasionally you may need to rework some of your own modifications
616 to match changes made to the remote branch (see @ref{Resolving
617 conflicts}), and it's considerably easier to rework things
618 incrementally. If you don't update your repository along the way,
619 you may have to spend a lot of time resolving branch conflicts and
620 reconfiguring much of the work you've already done.
622 Fortunately, Git is able to resolve certain types of branch
623 conflicts automatically with a process called @emph{rebasing}.
624 When rebasing, Git tries to modify your old commits so they appear
625 as new commits (based on the latest updates). For a more involved
626 explanation, see the @command{git-rebase} man page.
628 To pull without rebasing (recommended for translators), use the
632 git pull # recommended for translators
635 If you're tracking the remote @code{master} branch, you should add
636 the @code{-r} option (short for @code{--rebase}) to keep commits
637 on your local branch current:
640 git pull -r # use with caution when translating
643 If you don't edit translated documentation and don't want to type
644 @code{-r} every time, configure the master branch to rebase by
645 default with this command:
648 git config branch.master.rebase true
651 If pull fails because of a message like
654 error: Your local changes to 'Documentation/learning/tutorial.itely'
655 would be overwritten by merge. Aborting.
662 Documentation/learning/tutorial.itely: needs update
663 refusing to pull with rebase: your working tree is not up-to-date
667 it means that you have modified some files in you working tree
668 without committing changes (see @ref{Commits and patches}); you
669 can use the @command{git@tie{}stash} command to work around this:
672 git stash # save uncommitted changes
673 git pull -r # pull using rebase (translators omit "-r")
674 git stash pop # reapply previously saved changes
677 Note that @command{git@tie{}stash@tie{}pop} will try to apply a
678 patch, and this may create a conflict. If this happens, see
679 @ref{Resolving conflicts}.
681 TODO: I think the next paragraph is confusing. Perhaps prepare
682 the reader for new terms `committish' and `head'? -mp
684 @warning{translators and documentation editors, if you have
685 changed committishes in the head of translated files using commits
686 you have not yet pushed to @code{git.sv.gnu.org}, please do not
687 rebase. If you want to avoid wondering whether you should rebase
688 each time you pull, please always use committishes from master
689 and/or lilypond/translation branch on @code{git.sv.gnu.org}, which
690 in particular implies that you must push your changes to
691 documentation except committishes updates (possibly after having
692 rebased), then update the committishes and push them.}
694 TODO: when committishes automatic conditional update have been
695 tested and documented, append the following to the warning above:
696 Note that using update-committishes make target generally touches
699 @subsubheading Technical details
701 The @command{git@tie{}config} command mentioned above adds the
702 line @code{rebase = true} to the master branch in your local
703 repository's @file{.git/config} file:
708 merge = refs/heads/master
713 @node Using local branches
714 @subsection Using local branches
718 * Creating and removing branches::
719 * Listing branches and remotes::
720 * Checking out branches::
725 @node Creating and removing branches
726 @unnumberedsubsubsec Creating and removing branches
729 Local branches are useful when you're working on several different
730 projects concurrently. To create a new branch, enter:
733 git branch @var{name}
736 To delete a branch, enter:
739 git branch -d @var{name}
742 Git will ask you for confirmation if it sees that data would be
743 lost by deleting the branch. Use @code{-D} instead of @code{-d}
744 to bypass this. Note that you cannot delete a branch if it is
745 currently checked out.
748 @node Listing branches and remotes
749 @unnumberedsubsubsec Listing branches and remotes
751 You can get the exact path or URL of all remote branches by
758 To list Git branches on your local repositories, run
761 git branch # list local branches only
762 git branch -r # list remote branches
763 git branch -a # list all branches
767 @node Checking out branches
768 @unnumberedsubsubsec Checking out branches
770 To know the currently checked out branch, i.e. the branch whose
771 source files are present in your working tree, read the first line
779 The currently checked out branch is also marked with an asterisk
780 in the output of @command{git branch}.
782 You can check out another branch @code{@var{other_branch}}, i.e.
783 check out @code{@var{other_branch}} to the working tree, by
787 git checkout @var{other_branch}
790 Note that it is possible to check out another branch while having
791 uncommitted changes, but it is not recommended unless you know
792 what you are doing; it is recommended to run @command{git status}
793 to check this kind of issue before checking out another branch.
795 @node Merging branches
796 @unnumberedsubsubsec Merging branches
798 To merge branch @code{@var{foo}} into branch @code{@var{bar}},
799 i.e. to @qq{add} all changes made in branch @code{@var{foo}} to
800 branch @code{@var{bar}}, run
803 git checkout @var{bar}
807 If any conflict happens, see @ref{Resolving conflicts}.
809 There are common usage cases for merging: as a translator, you
810 will often want to merge @code{master} into
811 @code{lilypond/translation}; on the other hand, the Translations
812 meister wants to merge @code{lilypond/translation} into
813 @code{master} whenever he has checked that
814 @code{lilypond/translation} builds successfully.
817 @node Commits and patches
818 @subsection Commits and patches
822 * Understanding commits::
826 * Uploading a patch for review::
830 @node Understanding commits
831 @unnumberedsubsubsec Understanding commits
833 Technically, a @emph{commit} is a single point in the history of a
834 branch, but most developers use the term to mean a @emph{commit
835 object}, which stores information about a particular revision. A
836 single commit can record changes to multiple source files, and
837 typically represents one logical set of related changes (such as a
838 bug-fix). You can list the ten most recent commits in your
839 current branch with this command:
842 git log -10 --oneline
845 If you're using an older version of Git and get an @q{unrecognized
846 argument} error, use this instead:
849 git log -10 --pretty=oneline --abbrev-commit
852 More interactive lists of the commits on the remote @code{master}
853 branch are available at
854 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=shortlog} and
855 @uref{http://git.sv.gnu.org/cgit/lilypond.git/log/}.
859 @unnumberedsubsubsec Making commits
862 Once you have modified some source files in your working
863 directory, you can make a commit with the following procedure:
867 Make sure you've configured Git properly (see @ref{Configuring
868 Git}). Check that your changes meet the requirements described in
869 @ref{Code style} and/or @ref{Documentation policy}. For advanced
870 edits, you may also want to verify that the changes don't break
871 the compilation process.
874 Run the following command:
881 to make sure you're on the right branch, and to see which files
882 have been modified, added or removed, etc. You may need to tell
883 Git about any files you've added by running one of these:
886 git add @var{file} # add untracked @var{file} individually
887 git add . # add all untracked files in current directory
891 After @command{git@tie{}add}, run @command{git@tie{}status} again
892 to make sure you got everything. You may also need to modify
896 Preview the changes about to be committed (to make sure everything
904 The @code{HEAD} argument refers to the most recent commit on the
905 currently checked-out branch.
908 Generate the commit with:
915 The @code{-a} is short for @code{--all} which includes modified
916 and deleted files, but only those newly created files that have
917 previously been added.
922 @node Commit messages
923 @unnumberedsubsubsec Commit messages
926 When you run the @command{git@tie{}commit@tie{}-a} command, Git
927 automatically opens the default text editor so you can enter a
928 @emph{commit message}. If you find yourself in a foreign editing
929 environment, you're probably in @command{vi} or @command{vim}. If
930 you want to switch to an editor you're more familiar with, quit by
931 typing @code{:q!} and pressing @code{<Enter>}. See
932 @ref{Configuring Git} for instructions on changing the default
935 In any case, Git will open a text file for your commit message
936 that looks like this:
940 # Please enter the commit message for your changes. Lines starting
941 # with '#' will be ignored, and an empty message aborts the commit.
943 # Changes to be committed:
944 # (use "git reset HEAD <file>..." to unstage)
946 # modified: working.itexi
950 Your commit message should begin with a one-line summary
951 describing the change (no more than 50 characters long), and if
952 necessary a blank line followed by several lines giving the
955 @c $ git log -1 --pretty=medium 4d6f1e5
957 Doc: add Baerenreiter and Henle solo cello suites
959 Added comparison of solo cello suite engravings to new essay with
960 high-res images, fixed cropping on Finale example.
963 Commit messages often start with a short prefix describing the
964 general location of the changes. If a commit affects the
965 documentation in English (or in several languages simultaneously)
966 the commit message should be prefixed with @qq{Doc:@tie{}}. If
967 the commit affects only one of the translations, the commit
968 message should be prefixed with @qq{Doc-@var{**}:@tie{}}, where
969 @var{**} is the two-letter language code. Commits that affect the
970 website should use @qq{Web:@tie{}} for English, and
971 @qq{Web-@var{**}:@tie{}} for the other languages. Also, changes
972 to a single file are often prefixed with the name of the file
973 involved. Visit the links listed in @ref{Understanding commits}
978 @unnumberedsubsubsec Making patches
980 If you want to share your changes with other contributors and
981 developers, you need to generate @emph{patches} from your commits.
982 We prefer it if you follow the instructions in
983 @ref{Uploading a patch for review}. However, we present an
984 alternate method here.
986 You should always run @command{git@tie{}pull@tie{}-r} (translators
987 should leave off the @code{-r}) before doing this to ensure that
988 your patches are as current as possible.
990 Once you have made one or more commits in your local repository,
991 and pulled the most recent commits from the remote branch, you can
992 generate patches from your local commits with the command:
995 git format-patch origin
998 The @code{origin} argument refers to the remote tracking branch at
999 @code{git.sv.gnu.org}. This command generates a separate patch
1000 for each commit that's in the current branch but not in the remote
1001 branch. Patches are placed in the current working directory and
1002 will have names that look something like this:
1005 0001-Doc-Fix-typos.patch
1006 0002-Web-Remove-dead-links.patch
1010 Send an email (must be less than 64 KB) to
1011 @email{lilypond-devel@@gnu.org} briefly explaining your work, with
1012 the patch files attached. Translators should send patches to
1013 @email{translations@@lilynet.net}. After your patches are
1014 reviewed, the developers may push one or more of them to the main
1015 repository or discuss them with you.
1018 @node Uploading a patch for review
1019 @unnumberedsubsubsec Uploading a patch for review
1021 Any non-trivial change should be uploaded to our @qq{Rietveld}
1022 code review website:
1025 @uref{http://codereview.appspot.com/}
1028 @subsubheading Initial setup
1033 You must have a gmail account.
1036 Install @command{git-cl} by entering:
1039 git clone git://neugierig.org/git-cl.git
1043 Add the @file{git-cl/} directory to your PATH, or create a
1044 symbolic link to the @command{git-cl} and @command{upload.py}
1045 scripts in one of your PATH directories (such as
1050 Move into the top source directory and then configure
1051 @command{git cl}. If you do not understand any question, just
1052 answer with a newline (CR).
1055 cd $HOME/lilypond-git/
1059 The @qq{CC list} question should be answered with:
1062 lilypond-devel@@gnu.org
1067 @subsubheading Uploading patch set
1069 @warning{Unless you are familiar with branches, only work on one
1070 set of changes at once.}
1072 There are two methods, depending on your git setup.
1076 @strong{Master branch}: (easy option, and used in @command{lily-git.tcl})
1078 If you added your patch to @code{master}, then:
1082 git cl upload origin/master
1085 If you have git push ability, make sure that you @emph{remove}
1086 your patch (with @command{git rebase} or @command{git reset})
1087 before pushing other stuff.
1090 @strong{Separate branch}: (complicated option)
1092 Ensure your changes are committed in a separate branch, which
1093 should differ from the reference branch to be used by just the
1094 changes to be uploaded. If the reference branch is to be
1095 origin/master, ensure this is up-to-date. If necessary, use git
1096 rebase to rebase the branch containing the changes to the head of
1097 origin/master. Finally, check out branch with the changes and
1101 git cl upload <reference SHA1 ID>
1105 where <reference SHA1 ID> is the SHA1 ID of the commit to be used
1106 as a reference source for the patch. Generally, this will be the
1107 SHA1 ID of origin/master, and in that case the command:
1110 git cl upload origin/master
1118 After prompting for your Google email address and password, the
1119 patch set will be posted to Rietveld, and you will be given a URL
1122 @subsubheading Announcing your patch set
1124 You should then announce the patch by logging into the code review
1125 issue webpage and using @qq{Publish + Mail Comments} to add a
1126 (mostly bogus) comment to your issue. The text of your comment
1127 will be sent to our developer mailing list.
1129 @subsubheading Revisions
1131 As revisions are made in response to comments, successive patch sets
1132 for the same issue can be uploaded by reissuing the git-cl command
1133 with the modified branch checked out.
1135 Sometimes in response to comments on revisions, the best way to
1136 work may require creation of a new branch in git. In order to
1137 associate the new branch with an existing Rietveld issue,
1138 the following command can be used:
1141 git cl issue issue-number
1145 where @code{issue-number} is the number of the existing Rietveld
1148 @subsubheading Resetting git cl
1150 If @command{git cl} becomes confused, you can @qq{reset} it by
1158 @node Advanced Git procedures
1159 @section Advanced Git procedures
1162 @warning{This section is not necessary for normal contributors;
1163 these commands are presented for information for people interested
1164 in learning more about git.}
1166 It is possible to work with several branches on the same local Git
1167 repository; this is especially useful for translators who may have
1168 to deal with both @code{lilypond/translation} and a stable branch,
1169 e.g. @code{stable/2.12}.
1171 Some Git commands are introduced first, then a workflow with
1172 several Git branches of LilyPond source code is presented.
1176 * Advanced Git concepts::
1177 * Resolving conflicts::
1178 * Reverting all local changes::
1179 * Working with remote branches::
1181 * Applying remote patches::
1182 * Sending and receiving patches via email::
1187 @node Advanced Git concepts
1188 @subsection Advanced Git concepts
1191 A bit of Git vocabulary will be explained below. The following is
1192 only introductory; for a better understanding of Git concepts, you
1193 may wish to read @ref{Other Git documentation}.
1195 The @code{git@tie{}pull@tie{}origin} command above is just a
1196 shortcut for this command:
1199 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
1203 where @code{@var{branch}} is typically @code{master} or
1204 @code{lilypond/translation}; if you do not know or remember, see
1205 @ref{Downloading remote branches} to remember which commands you
1206 issued or which source code you wanted to get.
1208 A @emph{commit} is a set of changes made to the sources; it also
1209 includes the committish of the parent commit, the name and e-mail
1210 of the @emph{author} (the person who wrote the changes), the name
1211 and e-mail of the @emph{committer} (the person who brings these
1212 changes into the Git repository), and a commit message.
1214 A @emph{committish} is the SHA1 checksum of a commit, a number
1215 made of 40 hexadecimal digits, which acts as the internal unique
1216 identifier for this commit. To refer to a particular revision,
1217 don't use vague references like the (approximative) date, simply
1218 copy and paste the committish.
1220 A @emph{branch} is nothing more than a pointer to a particular
1221 commit, which is called the @emph{head} of the branch; when
1222 referring to a branch, one often actually thinks about its head
1223 and the ancestor commits of the head.
1225 Now we will explain the two last commands you used to get the
1226 source code from Git---see @ref{Downloading individual branches}.
1229 git remote add -ft @var{branch} -m @var{branch} \
1230 origin git://git.sv.gnu.org/lilypond.git/
1232 git checkout -b @var{branch} origin/@var{branch}
1235 The @command{git@tie{}remote} has created a branch called
1236 @code{origin/@var{branch}} in your local Git repository. As this
1237 branch is a copy of the remote branch web from git.sv.gnu.org
1238 LilyPond repository, it is called a @emph{remote branch}, and is
1239 meant to track the changes on the branch from git.sv.gnu.org: it
1240 will be updated every time you run
1241 @command{git@tie{}pull@tie{}origin} or
1242 @command{git@tie{}fetch@tie{}origin}.
1244 The @command{git@tie{}checkout} command has created a branch named
1245 @code{@var{branch}}. At the beginning, this branch is identical
1246 to @code{origin/@var{branch}}, but it will differ as soon as you
1247 make changes, e.g. adding newly translated pages or editing some
1248 documentation or code source file. Whenever you pull, you merge
1249 the changes from @code{origin/@var{branch}} and
1250 @code{@var{branch}} since the last pulling. If you do not have
1251 push (i.e. @qq{write}) access on git.sv.gnu.org, your
1252 @code{@var{branch}} will always differ from
1253 @code{origin/@var{branch}}. In this case, remember that other
1254 people working like you with the remote branch @code{@var{branch}}
1255 of git://git.sv.gnu.org/lilypond.git/ (called
1256 @code{origin/@var{branch}} on your local repository) know nothing
1257 about your own @code{@var{branch}}: this means that whenever you
1258 use a committish or make a patch, others expect you to take the
1259 latest commit of @code{origin/@var{branch}} as a reference.
1261 Finally, please remember to read the man page of every Git command
1262 you will find in this manual in case you want to discover
1263 alternate methods or just understand how it works.
1266 @node Resolving conflicts
1267 @subsection Resolving conflicts
1270 Occasionally an update may result in conflicts -- this happens
1271 when you and somebody else have modified the same part of the same
1272 file and git cannot figure out how to merge the two versions
1273 together. When this happens, you must manually merge the two
1276 If you need some documentation to understand and resolve
1277 conflicts, see paragraphs @emph{How conflicts are presented} and
1278 @emph{How to resolve conflicts} in @command{git merge} man page.
1280 If all else fails, you can follow the instructions in
1281 @ref{Reverting all local changes}. Be aware that this eliminates
1282 any changes you have made!
1285 @node Reverting all local changes
1286 @subsection Reverting all local changes
1288 Sometimes git will become hopelessly confused, and you just want
1289 to get back to a known, stable state. This command destroys any
1290 local changes you have made, but at least you get back to the
1291 current online version:
1294 git reset --hard origin/master
1298 @node Working with remote branches
1299 @subsection Working with remote branches
1302 @subsubheading Fetching new branches from git.sv.gnu.org
1304 To fetch and check out a new branch named @code{@var{branch}} on
1305 git.sv.gnu.org, run from top of the Git repository
1308 git config --add remote.origin.fetch \
1309 +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
1311 git checkout --track -b @var{branch} origin/@var{branch}
1314 After this, you can pull @code{@var{branch}} from git.sv.gnu.org
1321 Note that this command generally fetches all branches you added
1322 with @command{git@tie{}remote@tie{}add} (when you initialized the
1323 repository) or @command{git@tie{}config@tie{}--add}, i.e. it
1324 updates all remote branches from remote @code{origin}, then it
1325 merges the remote branch tracked by the current branch into the
1326 current branch. For example, if your current branch is
1327 @code{master}, @code{origin/master} will be merged into
1331 @subsubheading Local clones, or having several working trees
1333 If you play with several Git branches, e.g. @code{master},
1334 @code{lilypond/translation}, @code{stable/2.12}), you may want to
1335 have one source and build tree for each branch; this is possible
1336 with subdirectories of your local Git repository, used as local
1337 cloned subrepositories. To create a local clone for the branch
1338 named @code{@var{branch}}, run
1341 git checkout @var{branch}
1342 git clone -lsn . @var{subdir}
1347 Note that @code{@var{subdir}} must be a directory name which does
1348 not already exist. In @code{@var{subdir}}, you can use all Git
1349 commands to browse revisions history, commit and uncommit changes;
1350 to update the cloned subrepository with changes made on the main
1351 repository, cd into @code{@var{subdir}} and run
1352 @command{git@tie{}pull}; to send changes made on the subrepository
1353 back to the main repository, run @command{git@tie{}push} from
1354 @code{@var{subdir}}. Note that only one branch (the currently
1355 checked out branch) is created in the subrepository by default; it
1356 is possible to have several branches in a subrepository and do
1357 usual operations (checkout, merge, create, delete...) on these
1358 branches, but this possibility is not detailed here.
1360 When you push @code{@var{branch}} from @code{@var{subdir}} to the
1361 main repository, and @code{@var{branch}} is checked out in the
1362 main repository, you must save uncommitted changes (see
1363 @command{git@tie{}stash}) and do
1364 @command{git@tie{}reset@tie{}--hard} in the main repository in
1365 order to apply pushed changes in the working tree of the main
1373 The commands above don't only bring you the latest version of the
1374 sources, but also the full history of revisions (revisions, also
1375 called commits, are changes made to the sources), stored in the
1376 @file{.git} directory. You can browse this history with
1379 git log # only shows the logs (author, committish and commit message)
1380 git log -p # also shows diffs
1381 gitk # shows history graphically
1384 @warning{The @code{gitk} command may require a separate
1385 @code{gitk} package, available in the appropriate distribution's
1389 @node Applying remote patches
1390 @subsection Applying remote patches
1393 TODO: Explain how to determine if a patch was created with
1394 @code{git@tie{}format-patch}.
1396 Well-formed git patches created with @code{git@tie{}format-patch}
1397 should be committed with the following command:
1403 Patches created without @code{git@tie{}format-patch} can be
1404 applied in two steps. The first step is to apply the patch to the
1408 git apply @var{patch}
1412 The second step is to commit the changes and give credit to the
1413 author of the patch. This can be done with the following command:
1416 git commit -a --author="@var{John Smith} <@var{john@@example.com}>"
1420 @node Sending and receiving patches via email
1421 @subsection Sending and receiving patches via email
1424 The default @code{x-diff} MIME type associated with patch files
1425 (i.e., files whose name ends in @code{.patch}) means that the
1426 encoding of line endings may be changed from UNIX to DOS format
1427 when they are sent as attachments. Attempting to apply such an
1428 inadvertently altered patch will cause git to fail with a message
1429 about @q{whitespace errors}.
1431 The solution to such problems is surprisingly simple---just change
1432 the default file extension of patches generated by git to end in
1433 @code{.txt}, for example:
1436 git config format.suffix '.patch.txt'
1439 This should cause email programs to apply the correct base64
1440 encoding to attached patches.
1442 If you receive a patch with DOS instead of UNIX line-endings, it
1443 can be converted back using the @code{dos2unix} utility.
1445 Lots of useful information on email complications with patches is
1446 provided on the Wine wiki at
1447 @uref{http://wiki.winehq.org/GitWine}.
1451 @subsection Commit access
1454 Most contributors are not able to commit patches directly to the
1455 main repository---only members of the LilyPond development team
1456 have @emph{commit access}. If you are a contributor and are
1457 interested in joining the development team, contact the Project
1458 Manager through the mailing list
1459 (@email{lilypond-devel@@gnu.org}). Generally, only contributors
1460 who have already provided a number of patches which have been
1461 pushed to the main repository will be considered for membership.
1463 If you have been approved by the Project Manager, use the
1464 following procedure to obtain commit access:
1468 If you don't already have one, set up a Savannah user account at
1469 @uref{https://savannah.gnu.org/account/register.php}. If your web
1470 browser responds with an @qq{untrusted connection} message when
1471 you visit the link, follow the steps for including the CAcert root
1472 certificate in your browser, given at
1473 @uref{http://savannah.gnu.org/tls/tutorial/}.
1477 After registering, if you are not logged in automatically, login
1478 at @uref{https://savannah.gnu.org/account/login.php}---this should
1479 take you to your @qq{my} page
1480 (@uref{https://savannah.gnu.org/my/}).
1484 Click on the @qq{My Groups} link to access the @qq{My Group
1485 Membership} page. From there, find the @qq{Request for Inclusion}
1486 box and search for @qq{LilyPond}. Among the search results, check
1487 the box labeled @qq{GNU LilyPond Music Typesetter} and write a
1488 brief (required) message for the Project Manager (@qq{Hey it's
1489 me!} should be fine).
1491 Note that you will not have commit access until the Project
1492 Manager activates your membership. Once your membership is
1493 activated, LilyPond should appear under the heading @qq{Groups I'm
1494 Contributor of} on your @qq{My Group Membership} page.
1498 Generate an SSH @q{dsa} key pair. Enter the following at the
1505 When prompted for a location to save the key, press <ENTER> to
1506 accept the default location (@file{~/.ssh/id_dsa}).
1508 Next you are asked to enter an optional passphrase. On most
1509 systems, if you use a passphrase, you will likely be prompted for
1510 it every time you use @command{git@tie{}push} or
1511 @command{git@tie{}pull}. You may prefer this since it can protect
1512 you from your own mistakes (like pushing when you mean to pull),
1513 though you may find it tedious to keep re-entering it.
1515 You can change/enable/disable your passphrase at any time with:
1518 ssh-keygen -f ~/.ssh/id_dsa -p
1521 Note that the GNOME desktop has a feature which stores your
1522 passphrase for you for an entire GNOME session. If you use a
1523 passphrase to @qq{protect you from yourself}, you will want to
1524 disable this feature, since you'll only be prompted once. Run the
1525 following command, then logout of GNOME and log back in:
1528 gconftool-2 --set -t bool \
1529 /apps/gnome-keyring/daemon-components/ssh false
1532 After setting up your passphrase, your private key is saved as
1533 @file{~/.ssh/id_dsa} and your public key is saved as
1534 @file{~/.ssh/id_dsa.pub}.
1538 Register your public SSH @q{dsa} key with Savannah. From the
1539 @qq{My Account Configuration} page, click on @qq{Edit SSH Keys},
1540 then paste the contents of your @file{~/.ssh/id_dsa.pub} file into
1541 one of the @qq{Authorized keys} text fields, and click
1544 Savannah should respond with something like:
1547 Success: Key #1 seen Keys registered
1552 Configure Git to use the SSH protocol (instead of the GIT
1553 protocol). From your local Git repository, enter:
1556 git config remote.origin.url \
1557 ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1561 where @var{user} is your username on Savannah.
1565 After your membership has been activated and you've configured Git
1566 to use SSH, test the connection with:
1572 SSH should issue the following warning:
1575 The authenticity of host 'git.sv.gnu.org (140.186.70.72)' can't
1577 RSA key fingerprint is
1578 80:5a:b0:0c:ec:93:66:29:49:7e:04:2b:fd:ba:2c:d5.
1579 Are you sure you want to continue connecting (yes/no)?
1582 Make sure the RSA key fingerprint displayed matches the one above.
1583 If it doesn't, respond @qq{no} and check that you configured Git
1584 properly in the previous step. If it does match, respond
1585 @qq{yes}. SSH should then issue another warning:
1588 Warning: Permanently added 'git.sv.gnu.org,140.186.70.72' (RSA) to
1589 the list of known hosts.
1592 The list of known hosts is stored in the file
1593 @file{~/.ssh/known_hosts}.
1595 At this point, you are prompted for your passphrase if you have
1596 one, then Git will attempt a pull.
1598 If @command{git@tie{}pull@tie{}--verbose} fails, you should see
1599 error messages like these:
1602 Permission denied (publickey).
1603 fatal: The remote end hung up unexpectedly
1606 If you get the above error, you may have made a mistake when
1607 registering your SSH key at Savannah. If the key is properly
1608 registered, you probably just need to wait for the Savannah server
1609 to activate it. It usually takes a few minutes for the key to be
1610 active after registering it, but if it still doesn't work after an
1611 hour, ask for help on the mailing list.
1613 If @command{git@tie{}pull@tie{}--verbose} succeeds, the output
1614 will include a @q{From} line that shows @q{ssh} as the protocol:
1617 From ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond
1620 If the protocol shown is not @q{ssh}, check that you configured
1621 Git properly in the previous step.
1625 Test your commit access with a dry run:
1628 git push --dry-run --verbose
1631 Note that recent versions of Git (Git 1.6.3 or later) will issue a
1632 big warning if the above command is used. The simplest solution
1633 is to tell Git to push all matching branches by default:
1636 git config push.default matching
1640 Then @code{git@tie{}push} should work as before. For more
1641 details, consult the @code{git@tie{}push} man page.
1645 @subsubheading Technical details
1649 On Firefox, to view or remove the CAcert root certificate, go to:
1650 Edit > Preferences > Advanced > Encryption > View Certificates >
1651 Authorities > Certificate Name > Root CA > CA Cert Signing
1655 The @command{git@tie{}config} commands above should modify your
1656 local repository's @file{.git/config} file. These lines:
1660 url = git://git.sv.gnu.org/lilypond.git/
1664 should now be changed to:
1668 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1672 where @var{user} is your login name on Savannah.
1676 @command{git@tie{}config@tie{}push.default@tie{}matching} command
1677 should add these lines to @file{.git/config}:
1686 Encryption protocols, including ssh, generally do not permit packet
1687 fragmentation to avoid introducing a point of insecurity. This
1688 means that the maximum packet size must not exceed the smallest
1689 MTU (Maximum Transmission Unit) set in the routers along the path.
1690 This smallest MTU is determined by a procedure during call set-up
1691 which relies on the transmission over the path of ICMP packets.
1692 If any of the routers in the path block ICMP packets this mechanism
1693 fails, resulting in the possibility of packets being transmitted
1694 which exceed the MTU of one of the routers. If this happens the
1695 packet is discarded, causing the ssh session to hang, timeout or
1696 terminate with the error message
1699 ssh: connect to host <host ip addr> port 22: Bad file number
1700 fatal: The remote end hung up unexpectedly
1703 depending on precisely when in the proceedings the first large
1704 packet is transmitted. Most routers on the internet have MTU
1705 set to 1500, but routers installed in homes to connect via
1706 broadband may use a slightly smaller MTU for efficient transmission
1707 over ATM. If this problem is encountered a possible work-around is
1708 to set the MTU in the local router to 1500.
1710 @node Git on Windows
1711 @section Git on Windows
1713 @c Some of this may duplicate stuff in other sections
1714 @c But it is probably best for windows users to have it all together
1715 @c If necessary, clear this up later -td
1717 TODO: Decide what to do with this... Pare it down? Move
1718 paragraphs next to analogous Unix instructions? -mp
1720 @subsection Background to nomenclature
1722 Git is a system for tracking the changes made to source files by a
1723 distributed set of editors. It is designed to work without a
1724 master repository, but we have chosen to have a master repository
1725 for LilyPond files. Editors hold a local copy of the master
1726 repository together with any changes they have made locally.
1727 Local changes are held in a local @q{branch}, of which there may
1728 be several, but these instructions assume you are using just one.
1729 The files visible in the local repository always correspond to
1730 those on the currently @q{checked out} local branch.
1732 Files are edited on a local branch, and in that state the changes
1733 are said to be @q{unstaged}. When editing is complete, the
1734 changes are moved to being @q{staged for commit}, and finally the
1735 changes are @q{committed} to the local branch. Once committed,
1736 the changes (called a @q{commit}) are given a unique 40-digit
1737 hexadecimal reference number called the @q{Committish} or @q{SHA1
1738 ID} which identifies the commit to Git. Such committed changes
1739 can be sent to the master repository by @q{pushing} them (if you
1740 have write permission) or by sending them by email to someone who
1741 has, either as a complete file or as a @q{diff} or @q{patch}
1742 (which send just the differences from the master repository).
1744 @subsection Installing git
1747 @uref{http://code.google.com/p/msysgit/downloads/list} (note, not
1748 msysGit, which is for Git developers and not PortableGit, which is
1749 not a full git installation) and install it.
1751 Note that most users will not need to install SSH. That is not
1752 required until you have been granted direct push permissions to
1753 the master git repository.
1755 Start Git by clicking on the desktop icon. This will bring up a
1756 command line bash shell. This may be unfamiliar to Windows users.
1757 If so, follow these instructions carefully. Commands are entered
1758 at a $ prompt and are terminated by keying a newline.
1760 @subsection Initialising Git
1762 Decide where you wish to place your local Git repository, creating
1763 the folders in Windows as necessary. Here we call the folder to
1764 contain the repository @code{[path]/Git}, but if you intend using
1765 Git for other projects a directory name like @code{lilypond-git}
1766 might be better. You will need to have space for around
1769 Start the Git bash shell by clicking on the desk-top icon
1770 installed with Git and type
1776 to position the shell at your new Git repository.
1778 Note: if [path] contains folders with names containing spaces use
1790 to initialize your Git repository.
1792 Then type (all on one line; the shell will wrap automatically)
1795 git remote add -ft master origin git://git.sv.gnu.org/lilypond.git
1798 to download the lilypond master files.
1800 @warning{Be patient! Even on a broadband connection this can take
1801 10 minutes or more. Wait for lots of [new tag] messages and the $
1804 We now need to generate a local copy of the downloaded files in a
1805 new local branch. Your local branch needs to have a name. It is
1806 usual to call it @q{master} and we shall do that here.
1811 git checkout -b master origin/master
1814 This creates a second branch called @q{master}. You will see two
1815 warnings (ignore these), and a message advising you that your
1816 local branch @q{master} has been set up to track the remote
1817 branch. You now have two branches, a local branch called
1818 @q{master}, and a tracking branch called @q{origin/master}, which
1819 is a shortened form of @q{remotes/origin/master}.
1821 Return to Windows Explorer and look in your Git repository. You
1822 should see lots of folders. For example, the LilyPond
1823 documentation can be found in [path]/Git/Documentation/.
1825 The Git bash shell is terminated by typing @code{exit} or by
1826 clicking on the usual Windows close-window widget.
1830 Almost all subsequent work will use the Git Graphical User
1831 Interface, which avoids having to type command line commands. To
1832 start Git GUI first start the Git bash shell by clicking on the
1833 desktop icon, and type
1840 The Git GUI will open in a new window. It contains four panels
1841 and 7 pull-down menus. At this stage do not use any of the
1842 commands under Branch, Commit, Merge or Remote. These will be
1845 The top panel on the left contains the names of files which you
1846 are in the process of editing (Unstaged Changes), and the lower
1847 panel on the left contains the names of files you have finished
1848 editing and have staged ready for committing (Staged Changes). At
1849 present, these panels will be empty as you have not yet made any
1850 changes to any file. After a file has been edited and saved the
1851 top panel on the right will display the differences between the
1852 edited file selected in one of the panels on the left and the last
1853 version committed on the current branch.
1855 The panel at bottom right is used to enter a descriptive message
1856 about the change before committing it.
1858 The Git GUI is terminated by entering CNTL-Q while it is the
1859 active window or by clicking on the usual Windows close-window
1862 @subsection Personalising your local git repository
1864 Open the Git GUI, click on
1870 and enter your name and email address in the left-hand (Git
1871 Repository) panel. Leave everything else unchanged and save it.
1873 Note that Windows users must leave the default setting for line
1874 endings unchanged. All files in a git repository must have lines
1875 terminated by just a LF, as this is required for Merge to work,
1876 but Windows files are terminated by CRLF by default. The git
1877 default setting causes the line endings of files in a Windows git
1878 repository to be flipped automatically between LF and CRLF as
1879 required. This enables files to be edited by any Windows editor
1880 without causing problems in the git repository.
1882 @subsection Checking out a branch
1884 At this stage you have two branches in your local repository,
1885 both identical. To see them click on
1891 You should have one local branch called @q{master} and one
1892 tracking branch called @q{origin/master}. The latter is your
1893 local copy of the @q{remotes/origin/master} branch in the master
1894 LilyPond repository. The local @q{master} branch is where you
1895 will make your local changes.
1897 When a particular branch is selected, i.e., checked out, the files
1898 visible in your repository are changed to reflect the state of the
1899 files on that branch.
1901 @subsection Updating files from @q{remote/origin/master}
1903 Before starting the editing of a file, ensure your local
1904 repository contains the latest version of the files in the remote
1905 repository by first clicking
1908 Remote -> Fetch from -> origin
1914 This will place the latest version of every file, including all
1915 the changes made by others, into the @q{origin/master} branch of
1916 the tracking branches in your git repository. You can see these
1917 files by checking out this branch, but you must @emph{never} edit
1918 any files while this branch is checked out. Check out your local
1919 @q{master} branch again.
1921 You then need to merge these fetched files into your local
1922 @q{master} branch by clicking on
1925 Merge -> Local Merge
1929 and if necessary select the local @q{master} branch.
1931 Note that a merge cannot be completed if you have made any local
1932 changes which have not yet been committed.
1934 This merge will update all the files in the @q{master} branch to
1935 reflect the current state of the @q{origin/master} branch. If any
1936 of the changes conflict with changes you have made yourself
1937 recently you will be notified of the conflict (see below).
1939 @subsection Editing files
1941 First ensure your @q{master} branch is checked out, then simply
1942 edit the files in your local Git repository with your favourite
1943 editor and save them back there. If any file contains non-ASCII
1944 characters ensure you save it in UTF-8 format. Git will detect
1945 any changes whenever you restart Git GUI and the file names will
1946 then be listed in the Unstaged Changes panel. Or you can click
1947 the Rescan button to refresh the panel contents at any time. You
1948 may break off and resume editing any time.
1950 The changes you have made may be displayed in diff form in the top
1951 right-hand panel of Git GUI by clicking on the file name shown in
1952 one of the left panels.
1954 When your editing is complete, move the files from being Unstaged
1955 to Staged by clicking the document symbol to the left of each
1956 name. If you change your mind it can be moved back by clicking on
1957 the ticked box to the left of the name.
1959 Finally the changes you have made may be committed to your
1960 @q{master} branch by entering a brief message in the Commit
1961 Message box and clicking the Commit button.
1963 If you wish to amend your changes after a commit has been made,
1964 the original version and the changes you made in that commit may
1965 be recovered by selecting
1968 Commit -> Amend Last Commit
1972 or by checking the Amend Last Commit radio button at bottom right.
1973 This will return the changes to the Staged state, so further
1974 editing made be carried out within that commit. This must only be
1975 done @emph{before} the changes have been Pushed or sent to your
1976 mentor for Pushing - after that it is too late and corrections
1977 have to be made as a separate commit.
1980 @subsection Sending changes to @q{remotes/origin/master}
1982 If you do not have write access to @q{remotes/origin/master} you
1983 will need to send your changes by email to someone who does.
1985 First you need to create a diff or patch file containing your
1986 changes. To create this, the file must first be committed. Then
1987 terminate the Git GUI. In the git bash shell first cd to your Git
1994 if necessary, then produce the patch with
1997 git format-patch origin
2000 This will create a patch file for all the locally committed files
2001 which differ from @q{origin/master}. The patch file can be found
2002 in [path]/Git and will have a name formed from the commit message.
2004 @subsection Resolving merge conflicts
2006 As soon as you have committed a changed file your local
2007 @code{master} branch has diverged from @code{origin/master}, and
2008 will remain diverged until your changes have been committed in
2009 @code{remotes/origin/master} and Fetched back into your
2010 @code{origin/master} branch. Similarly, if a new commit has been
2011 made to @code{remotes/origin/master} by someone else and Fetched,
2012 your local @code{master} branch is divergent. You can detect a
2013 divergent branch by clicking on
2016 Repository -> Visualise all branch history
2019 This opens up a very useful new window called @q{gitk}. Use this
2020 to browse all the commits made by yourself and others.
2022 If the diagram at top left of the resulting window does not show
2023 your @code{master} tag on the same node as the
2024 @code{remotes/origin/master} tag your branch has diverged from
2025 @code{origin/master}. This is quite normal if files you have
2026 modified yourself have not yet been Pushed to
2027 @code{remotes/origin/master} and Fetched, or if files modified and
2028 committed by others have been Fetched since you last Merged
2029 @code{origin/master} into your local @code{master} branch.
2031 If a file being merged from @code{origin/master} differs from one
2032 you have modified in a way that cannot be resolved automatically
2033 by git, Merge will report a Conflict which you must resolve by
2034 editing the file to create the version you wish to keep.
2036 This could happen if the person updating
2037 @code{remotes/origin/master} for you has added some changes of his
2038 own before committing your changes to
2039 @code{remotes/origin/master}, or if someone else has changed the
2040 same file since you last fetched the file from
2041 @code{remotes/origin/master}.
2043 Open the file in your editor and look for sections which are
2046 [to be completed when I next have a merge conflict to be sure I
2047 give the right instructions -td]
2050 @subsection Other actions
2052 The instructions above describe the simplest way of using git on
2053 Windows. Other git facilities which may usefully supplement these
2057 @item Using multiple local branches (Create, Rename, Delete)
2058 @item Resetting branches
2059 @item Cherry-picking commits
2060 @item Pushing commits to @w{remote/origin/master}
2061 @item Using gitk to review history
2064 Once familiarity with using git on Windows has been gained the
2065 standard git manuals can be used to learn about these.
2068 @node Repository directory structure
2069 @section Repository directory structure
2072 @c TODO: integrate the roadmap better
2073 @verbatiminclude ROADMAP
2076 @node Other Git documentation
2077 @section Other Git documentation
2081 Official git man pages:
2082 @uref{http://www.kernel.org/pub/software/scm/git/docs/}
2085 More in-depth tutorials: @uref{http://git-scm.com/documentation}
2088 Book about git: @uref{http://progit.org/,Pro Git}