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}
40 @subsubheading Lilybuntu
44 @code{lily-git.tcl} has already been install for you. Simply type
53 Click on the @qq{Get source} button.
55 This will create a directory called @file{lilypond-git/} within
56 your home directory, and will download the source code into that
57 directory (around 55Mb). When the process is finished, the
58 @qq{Command output} window will display @qq{Done}, and the button
59 label will change to say @qq{Update source}.
62 Navigate to the @file{lilypond-git/} directory to view the source
63 files. You should now be able to modify the source files using
64 your normal text editor.
68 You should now progress to @ref{Compiling with lilybuntu}.
70 @warning{Throughout the rest of this manual, most command-line
71 input should be entered from @file{~/lilypond-git/}. This is
72 referred to as the @emph{top source directory}.}
75 @subsubheading Other operating music systems
79 If you haven't already, download and install Git.
84 Lilybuntu users: git has already been installed for you.
86 @item Windows users: download the @code{.exe} file labeled
87 @qq{Full installer for official Git} from:
90 @uref{http://code.google.com/p/msysgit/downloads/list}
93 @item Other operating systems: either install @command{git} with
94 your package manager, or download it from the @qq{Binaries}
98 @uref{http://git-scm.com/download}
105 Download the @command{lily-git.tcl} script from:
107 @c don't change the cgit link below to gitweb; gitweb uses
108 @c long filenames like "scripts_auxiliar_lily-git.tcl"
111 @uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
115 To run the program from the command line, navigate to the
116 directory containing @command{lily-git.tcl} and enter:
123 Go read the lilybuntu instructions, starting from the @qq{get
128 @advanced{the @qq{Get source} button does not fetch the entire
129 history of the git repository, so utilities like @command{gitk}
130 will only be able to display the most recent additions. As you
131 continue to work with @command{lily-git.tcl}, the @qq{Update
132 source} button will take any new additions and add it to whatever
133 is currently in your repository's history.}
136 @node Daily use of lily-git.tcl
137 @unnumberedsubsec Daily use of @command{lily-git.tcl}
139 @warning{Only work on one set of changes at once. Do not start
140 work on any new changes until your first set has been accepted.}
142 @subsubheading 1. Update source
144 At the beginning of each session of lilypond work, you should
145 click the @qq{Update source} button to get the latest changes to
148 @warning{In some rare and unfortunate circumstances, this will
149 result in a @emph{merge conflict}. If this occurs, follow the
150 instructions for @qq{Abort changes}, below. Your work will not be
154 @subsubheading 2a. New local commit
156 A single commit typically represents one logical set of related
157 changes (such as a bug-fix), and may incorporate changes to
158 multiple files at the same time.
160 When you're finished making the changes for a commit, click the
161 @qq{New local commit} button. This will open the @qq{Git Commit
162 Message} window. The message header is required, and the message
165 After entering a commit message, click @qq{OK} to finalize the
168 @advanced{for more information regarding commits and commit
169 messages, see @ref{Commits and patches}.}
172 @subsubheading 2b. Amend previous commit
174 You can go back and make changes to the most recent commit with
175 the @qq{Amend previous commit} button. This is useful if a
176 mistake is found after you have clicked the @qq{New local commit}
179 To amend the most recent commit, re-edit the source files as
180 needed and then click the @qq{Amend previous commit} button. The
181 earlier version of the commit is not saved, but is replaced by the
184 @warning{This does not update the patch @strong{files}; if you
185 have a patch file from an earlier version of the commit, you will
186 need to make another patch set when using this feature. The old
187 patch file will not be saved, but will be replaced by the new one
188 after you click on @qq{Make patch set}.}
191 @subsubheading 3. Make patch set
193 Before making a patch set from any commits, you should click the
194 @qq{Update source} button to make sure the commits are based on
195 the most recent remote snapshot.
197 When you click the @qq{Make patch set} button,
198 @command{lily-git.tcl} will produce patch files for any new
199 commits, saving them to the current directory. The command output
200 will display the name of the new patch files near the end of the
204 0001-CG-add-lily-git-instructions.patch
208 Send patch files to the appropriate place:
212 If you have a mentor, send it to them via email.
215 New contributors should send the patch attached to an email to
216 @email{frogs@@lilynet.net}. Please add @qq{[PATCH]} to the
220 Translators should send patches to
221 @email{translations@@lilynet.net}.
224 More experienced contributors should upload the patch for
225 web-based review. This requires additional software and use of
226 the command-line; see @ref{Uploading a patch for review}.
231 @subsubheading The @qq{Abort changes -- Reset to origin} button
233 @warning{Only use this if your local commit history gets
234 hopelessly confused!}
236 The button labeled @qq{Abort changes -- Reset to origin} will copy
237 all changed files to a subdirectory of @file{lilypond-git/} named
238 @file{aborted_edits/}, and will reset the repository to the
239 current state of the remote repository (at @code{git.sv.gnu.org}).
242 @node Starting with Git
243 @section Starting with Git
246 Using the Git program directly (as opposed to using the
247 @command{lily-git.tcl} GUI) allows you to have much greater control
248 over the contributing process. You should consider using Git if
249 you want to work on complex projects, or if you want to work on
250 multiple projects concurrently.
255 * Downloading remote branches::
260 @subsection Setting up
263 TODO: Remove this note if incorporating Windows instructions
264 throughout this section:
266 @warning{These instructions assume that you are using the
267 command-line version of Git 1.5 or higher. Windows users should
268 skip to @ref{Git on Windows}.}
272 * Initializing a repository::
278 @unnumberedsubsubsec Installing Git
281 If you are using a Unix-based machine, the easiest way to download
282 and install Git is through a package manager such as @command{rpm}
283 or @command{apt-get}---the installation is generally automatic.
284 The only required package is (usually) called @command{git-core},
285 although some of the auxiliary @command{git@var{*}} packages are
286 also useful (such as @command{gitk}).
288 Alternatively, you can visit the Git website
289 (@uref{http://git-scm.com/}) for downloadable binaries and
292 TODO: add Windows installation instructions (or @@ref@{Git on
296 @node Initializing a repository
297 @unnumberedsubsubsec Initializing a repository
300 Once Git is installed, you'll need to create a new directory where
301 your initial repository will be stored (the example below uses
302 @file{~/lilypond-git/}, where @code{~} represents your home
303 directory). Run @command{git@tie{}init} from within the new
304 directory to initialize an empty repository:
307 mkdir ~/lilypond-git/; cd ~/lilypond-git/
311 @subsubheading Technical details
313 This creates (within the @file{~/lilypond-git/} directory) a
314 subdirectory called @file{.git/}, which Git uses to keep track of
315 changes to the repository, among other things. Normally you don't
316 need to access it, but it's good to know it's there.
319 @node Configuring Git
320 @unnumberedsubsubsec Configuring Git
322 @warning{Throughout the rest of this manual, all command-line
323 input should be entered from the top directory of the Git
324 repository being discussed (eg. @file{~/lilypond-git/}). This is
325 referred to as the @emph{top source directory}.}
327 Before downloading a copy of the main LilyPond repository, you
328 should configure some basic settings with the
329 @command{git@tie{}config} command. Git allows you to set both
330 global and repository-specific options.
332 To configure settings that affect all repositories, use the
333 @command{--global} command line option. For example, the first
334 two options that you should always set are your @var{name} and
335 @var{email}, since Git needs these to keep track of commit
339 git config --global user.name "@var{John Smith}"
340 git config --global user.email @var{john@@example.com}
343 To configure Git to use colored output where possible, use:
346 git config --global color.ui auto
349 The text editor that opens when using @command{git@tie{}commit}
350 can also be changed. If none of your editor-related environment
351 variables are set ($GIT_EDITOR, $VISUAL, or $EDITOR), the default
352 editor is usually @command{vi} or @command{vim}. If you're not
353 familiar with either of these, you should probably change the
354 default to an editor that you know how to use. For example, to
355 change the default editor to @command{nano}, enter:
358 git config --global core.editor @var{nano}
361 TODO: Add instructions for changing the editor on Windows, which
362 is a little different, I think. -mp
364 @subsubheading Technical details
366 Git stores the information entered with
367 @command{git@tie{}config@tie{}--global} in the file
368 @file{.gitconfig}, located in your home directory. This file can
369 also be modified directly, without using
370 @command{git@tie{}config}. The @file{.gitconfig} file generated
371 by the above commands would look like this:
376 email = john@@example.com
383 Using the @command{git@tie{}config} command @emph{without} the
384 @command{--global} option configures repository-specific settings,
385 which are stored in the file @file{.git/config}. This file is
386 created when a repository is initialized (using
387 @command{git@tie{}init}), and by default contains these lines:
391 repositoryformatversion = 0
394 logallrefupdates = true
397 However, since different repository-specific options are
398 recommended for different development tasks, it is best to avoid
399 setting any now. Specific recommendations will be mentioned later
403 @node Downloading remote branches
404 @subsection Downloading remote branches
408 * Organization of remote branches::
409 * LilyPond repository sources::
410 * Downloading individual branches::
411 * Downloading all remote branches::
416 @node Organization of remote branches
417 @unnumberedsubsubsec Organization of remote branches
420 The main LilyPond repository is organized into @emph{branches} to
421 facilitate development. These are often called @emph{remote}
422 branches to distinguish them from @emph{local} branches you might
423 create yourself (see @ref{Using local branches}).
425 The @code{master} branch contains all the source files used to
426 build LilyPond, which includes the program itself (both stable and
427 development releases), the documentation (and its translations),
428 and the website. Generally, the @code{master} branch is expected
429 to compile successfully.
431 The @code{lilypond/translation} branch is a side branch that
432 allows translators to work without needing to worry about
433 compilation problems. Periodically, the Translation Meister
434 (after verifying that it doesn't break compilation), will
435 @emph{merge} this branch back into @code{master} to incorporate
436 recent translations. Similarly, the @code{master} branch is
437 usually merged into the @code{lilypond/translation} branch after
438 significant changes to the English documentation. See
439 @ref{Translating the documentation} for details.
442 @node LilyPond repository sources
443 @unnumberedsubsubsec LilyPond repository sources
446 The recommended source for downloading a copy of the main
450 git://git.sv.gnu.org/lilypond.git
453 However, if your internet router filters out connections using the
454 GIT protocol, or if you experience difficulty connecting via GIT,
455 you can try these other sources:
458 ssh://git.sv.gnu.org/srv/git/lilypond.git
459 http://git.sv.gnu.org/r/lilypond.git
462 The SSH protocol can only be used if your system is properly set
463 up to use it. Also, the HTTP protocol is slowest, so it should
464 only be used as a last resort.
467 @node Downloading individual branches
468 @unnumberedsubsubsec Downloading individual branches
471 Once you have initialized an empty Git repository on your system
472 (see @ref{Initializing a repository}), you can download a remote
473 branch into it. Make sure you know which branch you want to start
476 To download the @code{master} branch, enter the following:
479 git remote add -ft master -m master \
480 origin git://git.sv.gnu.org/lilypond.git/
483 To download the @code{lilypond/translation} branch, enter:
486 git remote add -ft lilypond/translation -m \
487 lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
490 The @command{git@tie{}remote@tie{}add} process could take up to
491 ten minutes, depending on the speed of your connection. The
492 output will be something like this:
496 remote: Counting objects: 235967, done.
497 remote: Compressing objects: 100% (42721/42721), done.
498 remote: Total 235967 (delta 195098), reused 233311 (delta 192772)
499 Receiving objects: 100% (235967/235967), 68.37 MiB | 479 KiB/s, done.
500 Resolving deltas: 100% (195098/195098), done.
501 From git://git.sv.gnu.org/lilypond
502 * [new branch] master -> origin/master
503 From git://git.sv.gnu.org/lilypond
504 * [new tag] flower/1.0.1 -> flower/1.0.1
505 * [new tag] flower/1.0.10 -> flower/1.0.10
507 * [new tag] release/2.9.6 -> release/2.9.6
508 * [new tag] release/2.9.7 -> release/2.9.7
511 When @command{git@tie{}remote@tie{}add} is finished, the remote
512 branch should be downloaded into your repository---though not yet
513 in a form that you can use. In order to browse the source code
514 files, you need to @emph{create} and @emph{checkout} your own
515 local branch. In this case, however, it is easier to have Git
516 create the branch automatically by using the @command{checkout}
517 command on a non-existent branch. Enter the following:
520 git checkout -b @var{branch} origin/@var{branch}
524 where @code{@var{branch}} is the name of your tracking branch,
525 either @code{master} or @code{lilypond/translation}.
527 Git will issue some warnings; this is normal:
530 warning: You appear to be on a branch yet to be born.
531 warning: Forcing checkout of origin/master.
532 Branch master set up to track remote branch master from origin.
536 By now the source files should be accessible---you should be able
537 to edit any files in the @file{lilypond-git/} directory using a
538 text editor of your choice. But don't start just yet! Before
539 editing any source files, learn how to keep your changes organized
540 and prevent problems later---read @ref{Basic Git procedures}.
542 @subsubheading Technical Details
544 The @command{git@tie{}remote@tie{}add} command should add some
545 lines to your local repository's @file{.git/config} file:
549 url = git://git.sv.gnu.org/lilypond.git/
550 fetch = +refs/heads/master:refs/remotes/origin/master
554 @node Downloading all remote branches
555 @unnumberedsubsubsec Downloading all remote branches
558 To download all remote branches at once, you can @command{clone}
559 the entire repository:
562 git clone git://git.sv.gnu.org/lilypond.git
567 @unnumberedsubsubsec Other branches
569 Most contributors will never need to touch the other branches. If
570 you wish to do so, you will need more familiarity with Git; please
571 see @ref{Other Git documentation}.
574 @item @code{dev/XYZ}:
575 These branches are for individual developers. They store code
576 which is not yet stable enough to be added to the @code{master}
579 @item @code{stable/XYZ}:
580 The branches are kept for archival reasons.
584 Another item of interest might be the Grand Unified Builder, our
585 cross-platform building tool. Since it is used by projects as
586 well, it is not stored in our gub repository. For more info, see
587 @uref{http://lilypond.org/gub}. The git location is
588 @uref{http://github.com/janneke/gub}.
591 @node Basic Git procedures
592 @section Basic Git procedures
596 * The Git contributor's cycle::
597 * Pulling and rebasing::
598 * Using local branches::
599 * Commits and patches::
603 @node The Git contributor's cycle
604 @subsection The Git contributor's cycle
607 Here is a simplified view of the contribution process on Git:
611 Update your local repository by @emph{pulling} the most recent
612 updates from the remote repository.
615 Edit source files within your local repository's @emph{working
619 @emph{Commit} the changes you've made to a local @emph{branch}.
622 Generate a @emph{patch} to share your changes with the developers.
626 @node Pulling and rebasing
627 @subsection Pulling and rebasing
630 When developers push new patches to the @code{git.sv.gnu.org}
631 repository, your local repository is @strong{not} automatically
632 updated. It is important to keep your repository up-to-date by
633 periodically @emph{pulling} the most recent @emph{commits} from
634 the remote branch. Developers expect patches to be as current as
635 possible, since outdated patches require extra work before they
638 Occasionally you may need to rework some of your own modifications
639 to match changes made to the remote branch (see @ref{Resolving
640 conflicts}), and it's considerably easier to rework things
641 incrementally. If you don't update your repository along the way,
642 you may have to spend a lot of time resolving branch conflicts and
643 reconfiguring much of the work you've already done.
645 Fortunately, Git is able to resolve certain types of branch
646 conflicts automatically with a process called @emph{rebasing}.
647 When rebasing, Git tries to modify your old commits so they appear
648 as new commits (based on the latest updates). For a more involved
649 explanation, see the @command{git-rebase} man page.
651 To pull without rebasing (recommended for translators), use the
655 git pull # recommended for translators
658 If you're tracking the remote @code{master} branch, you should add
659 the @code{-r} option (short for @code{--rebase}) to keep commits
660 on your local branch current:
663 git pull -r # use with caution when translating
666 If you don't edit translated documentation and don't want to type
667 @code{-r} every time, configure the master branch to rebase by
668 default with this command:
671 git config branch.master.rebase true
674 If pull fails because of a message like
677 error: Your local changes to 'Documentation/learning/tutorial.itely'
678 would be overwritten by merge. Aborting.
685 Documentation/learning/tutorial.itely: needs update
686 refusing to pull with rebase: your working tree is not up-to-date
690 it means that you have modified some files in you working tree
691 without committing changes (see @ref{Commits and patches}); you
692 can use the @command{git@tie{}stash} command to work around this:
695 git stash # save uncommitted changes
696 git pull -r # pull using rebase (translators omit "-r")
697 git stash pop # reapply previously saved changes
700 Note that @command{git@tie{}stash@tie{}pop} will try to apply a
701 patch, and this may create a conflict. If this happens, see
702 @ref{Resolving conflicts}.
704 TODO: I think the next paragraph is confusing. Perhaps prepare
705 the reader for new terms `committish' and `head'? -mp
707 @warning{translators and documentation editors, if you have
708 changed committishes in the head of translated files using commits
709 you have not yet pushed to @code{git.sv.gnu.org}, please do not
710 rebase. If you want to avoid wondering whether you should rebase
711 each time you pull, please always use committishes from master
712 and/or lilypond/translation branch on @code{git.sv.gnu.org}, which
713 in particular implies that you must push your changes to
714 documentation except committishes updates (possibly after having
715 rebased), then update the committishes and push them.}
717 TODO: when committishes automatic conditional update have been
718 tested and documented, append the following to the warning above:
719 Note that using update-committishes make target generally touches
722 @subsubheading Technical details
724 The @command{git@tie{}config} command mentioned above adds the
725 line @code{rebase = true} to the master branch in your local
726 repository's @file{.git/config} file:
731 merge = refs/heads/master
736 @node Using local branches
737 @subsection Using local branches
741 * Creating and removing branches::
742 * Listing branches and remotes::
743 * Checking out branches::
748 @node Creating and removing branches
749 @unnumberedsubsubsec Creating and removing branches
752 Local branches are useful when you're working on several different
753 projects concurrently. To create a new branch, enter:
756 git branch @var{name}
759 To delete a branch, enter:
762 git branch -d @var{name}
765 Git will ask you for confirmation if it sees that data would be
766 lost by deleting the branch. Use @code{-D} instead of @code{-d}
767 to bypass this. Note that you cannot delete a branch if it is
768 currently checked out.
771 @node Listing branches and remotes
772 @unnumberedsubsubsec Listing branches and remotes
774 You can get the exact path or URL of all remote branches by
781 To list Git branches on your local repositories, run
784 git branch # list local branches only
785 git branch -r # list remote branches
786 git branch -a # list all branches
790 @node Checking out branches
791 @unnumberedsubsubsec Checking out branches
793 To know the currently checked out branch, i.e. the branch whose
794 source files are present in your working tree, read the first line
802 The currently checked out branch is also marked with an asterisk
803 in the output of @command{git branch}.
805 You can check out another branch @code{@var{other_branch}}, i.e.
806 check out @code{@var{other_branch}} to the working tree, by
810 git checkout @var{other_branch}
813 Note that it is possible to check out another branch while having
814 uncommitted changes, but it is not recommended unless you know
815 what you are doing; it is recommended to run @command{git status}
816 to check this kind of issue before checking out another branch.
818 @node Merging branches
819 @unnumberedsubsubsec Merging branches
821 To merge branch @code{@var{foo}} into branch @code{@var{bar}},
822 i.e. to @qq{add} all changes made in branch @code{@var{foo}} to
823 branch @code{@var{bar}}, run
826 git checkout @var{bar}
830 If any conflict happens, see @ref{Resolving conflicts}.
832 There are common usage cases for merging: as a translator, you
833 will often want to merge @code{master} into
834 @code{lilypond/translation}; on the other hand, the Translations
835 meister wants to merge @code{lilypond/translation} into
836 @code{master} whenever he has checked that
837 @code{lilypond/translation} builds successfully.
840 @node Commits and patches
841 @subsection Commits and patches
845 * Understanding commits::
849 * Uploading a patch for review::
853 @node Understanding commits
854 @unnumberedsubsubsec Understanding commits
856 Technically, a @emph{commit} is a single point in the history of a
857 branch, but most developers use the term to mean a @emph{commit
858 object}, which stores information about a particular revision. A
859 single commit can record changes to multiple source files, and
860 typically represents one logical set of related changes (such as a
861 bug-fix). You can list the ten most recent commits in your
862 current branch with this command:
865 git log -10 --oneline
868 If you're using an older version of Git and get an @q{unrecognized
869 argument} error, use this instead:
872 git log -10 --pretty=oneline --abbrev-commit
875 More interactive lists of the commits on the remote @code{master}
876 branch are available at
877 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=shortlog} and
878 @uref{http://git.sv.gnu.org/cgit/lilypond.git/log/}.
882 @unnumberedsubsubsec Making commits
885 Once you have modified some source files in your working
886 directory, you can make a commit with the following procedure:
890 Make sure you've configured Git properly (see @ref{Configuring
891 Git}). Check that your changes meet the requirements described in
892 @ref{Code style} and/or @ref{Documentation policy}. For advanced
893 edits, you may also want to verify that the changes don't break
894 the compilation process.
897 Run the following command:
904 to make sure you're on the right branch, and to see which files
905 have been modified, added or removed, etc. You may need to tell
906 Git about any files you've added by running one of these:
909 git add @var{file} # add untracked @var{file} individually
910 git add . # add all untracked files in current directory
914 After @command{git@tie{}add}, run @command{git@tie{}status} again
915 to make sure you got everything. You may also need to modify
919 Preview the changes about to be committed (to make sure everything
927 The @code{HEAD} argument refers to the most recent commit on the
928 currently checked-out branch.
931 Generate the commit with:
938 The @code{-a} is short for @code{--all} which includes modified
939 and deleted files, but only those newly created files that have
940 previously been added.
945 @node Commit messages
946 @unnumberedsubsubsec Commit messages
949 When you run the @command{git@tie{}commit@tie{}-a} command, Git
950 automatically opens the default text editor so you can enter a
951 @emph{commit message}. If you find yourself in a foreign editing
952 environment, you're probably in @command{vi} or @command{vim}. If
953 you want to switch to an editor you're more familiar with, quit by
954 typing @code{:q!} and pressing @code{<Enter>}. See
955 @ref{Configuring Git} for instructions on changing the default
958 In any case, Git will open a text file for your commit message
959 that looks like this:
963 # Please enter the commit message for your changes. Lines starting
964 # with '#' will be ignored, and an empty message aborts the commit.
966 # Changes to be committed:
967 # (use "git reset HEAD <file>..." to unstage)
969 # modified: working.itexi
973 Your commit message should begin with a one-line summary
974 describing the change (no more than 50 characters long), and if
975 necessary a blank line followed by several lines giving the
978 @c $ git log -1 --pretty=medium 4d6f1e5
980 Doc: add Baerenreiter and Henle solo cello suites
982 Added comparison of solo cello suite engravings to new essay with
983 high-res images, fixed cropping on Finale example.
986 Commit messages often start with a short prefix describing the
987 general location of the changes. If a commit affects the
988 documentation in English (or in several languages simultaneously)
989 the commit message should be prefixed with @qq{Doc:@tie{}}. If
990 the commit affects only one of the translations, the commit
991 message should be prefixed with @qq{Doc-@var{**}:@tie{}}, where
992 @var{**} is the two-letter language code. Commits that affect the
993 website should use @qq{Web:@tie{}} for English, and
994 @qq{Web-@var{**}:@tie{}} for the other languages. Also, changes
995 to a single file are often prefixed with the name of the file
996 involved. Visit the links listed in @ref{Understanding commits}
1000 @node Making patches
1001 @unnumberedsubsubsec Making patches
1003 If you want to share your changes with other contributors and
1004 developers, you need to generate @emph{patches} from your commits.
1005 We prefer it if you follow the instructions in
1006 @ref{Uploading a patch for review}. However, we present an
1007 alternate method here.
1009 You should always run @command{git@tie{}pull@tie{}-r} (translators
1010 should leave off the @code{-r}) before doing this to ensure that
1011 your patches are as current as possible.
1013 Once you have made one or more commits in your local repository,
1014 and pulled the most recent commits from the remote branch, you can
1015 generate patches from your local commits with the command:
1018 git format-patch origin
1021 The @code{origin} argument refers to the remote tracking branch at
1022 @code{git.sv.gnu.org}. This command generates a separate patch
1023 for each commit that's in the current branch but not in the remote
1024 branch. Patches are placed in the current working directory and
1025 will have names that look something like this:
1028 0001-Doc-Fix-typos.patch
1029 0002-Web-Remove-dead-links.patch
1033 Send an email (must be less than 64 KB) to
1034 @email{lilypond-devel@@gnu.org} briefly explaining your work, with
1035 the patch files attached. Translators should send patches to
1036 @email{translations@@lilynet.net}. After your patches are
1037 reviewed, the developers may push one or more of them to the main
1038 repository or discuss them with you.
1041 @node Uploading a patch for review
1042 @unnumberedsubsubsec Uploading a patch for review
1044 Any non-trivial change should be uploaded to our @qq{Rietveld}
1045 code review website:
1048 @uref{http://codereview.appspot.com/}
1051 @subsubheading Initial setup
1056 You must have a gmail account.
1059 Install @command{git-cl} by entering:
1062 git clone git://neugierig.org/git-cl.git
1066 Add the @file{git-cl/} directory to your PATH, or create a
1067 symbolic link to the @command{git-cl} and @command{upload.py}
1068 scripts in one of your PATH directories (such as
1073 Move into the top source directory and then configure
1074 @command{git cl}. If you do not understand any question, just
1075 answer with a newline (CR).
1078 cd $HOME/lilypond-git/
1082 The @qq{CC list} question should be answered with:
1085 lilypond-devel@@gnu.org
1090 @subsubheading Uploading patch set
1092 @warning{Unless you are familiar with branches, only work on one
1093 set of changes at once.}
1095 There are two methods, depending on your git setup.
1099 @strong{Master branch}: (easy option, and used in @command{lily-git.tcl})
1101 If you added your patch to @code{master}, then:
1105 git cl upload origin/master
1108 If you have git push ability, make sure that you @emph{remove}
1109 your patch (with @command{git rebase} or @command{git reset})
1110 before pushing other stuff.
1113 @strong{Separate branch}: (complicated option)
1115 Ensure your changes are committed in a separate branch, which
1116 should differ from the reference branch to be used by just the
1117 changes to be uploaded. If the reference branch is to be
1118 origin/master, ensure this is up-to-date. If necessary, use git
1119 rebase to rebase the branch containing the changes to the head of
1120 origin/master. Finally, check out branch with the changes and
1124 git cl upload <reference SHA1 ID>
1128 where <reference SHA1 ID> is the SHA1 ID of the commit to be used
1129 as a reference source for the patch. Generally, this will be the
1130 SHA1 ID of origin/master, and in that case the command:
1133 git cl upload origin/master
1141 After prompting for your Google email address and password, the
1142 patch set will be posted to Rietveld, and you will be given a URL
1145 @subsubheading Announcing your patch set
1147 You should then announce the patch by logging into the code review
1148 issue webpage and using @qq{Publish + Mail Comments} to add a
1149 (mostly bogus) comment to your issue. The text of your comment
1150 will be sent to our developer mailing list.
1152 @subsubheading Revisions
1154 As revisions are made in response to comments, successive patch sets
1155 for the same issue can be uploaded by reissuing the git-cl command
1156 with the modified branch checked out.
1158 Sometimes in response to comments on revisions, the best way to
1159 work may require creation of a new branch in git. In order to
1160 associate the new branch with an existing Rietveld issue,
1161 the following command can be used:
1164 git cl issue issue-number
1168 where @code{issue-number} is the number of the existing Rietveld
1171 @subsubheading Resetting git cl
1173 If @command{git cl} becomes confused, you can @qq{reset} it by
1181 @node Advanced Git procedures
1182 @section Advanced Git procedures
1185 @warning{This section is not necessary for normal contributors;
1186 these commands are presented for information for people interested
1187 in learning more about git.}
1189 It is possible to work with several branches on the same local Git
1190 repository; this is especially useful for translators who may have
1191 to deal with both @code{lilypond/translation} and a stable branch,
1192 e.g. @code{stable/2.12}.
1194 Some Git commands are introduced first, then a workflow with
1195 several Git branches of LilyPond source code is presented.
1199 * Advanced Git concepts::
1200 * Resolving conflicts::
1201 * Reverting all local changes::
1202 * Working with remote branches::
1204 * Applying remote patches::
1205 * Sending and receiving patches via email::
1210 @node Advanced Git concepts
1211 @subsection Advanced Git concepts
1214 A bit of Git vocabulary will be explained below. The following is
1215 only introductory; for a better understanding of Git concepts, you
1216 may wish to read @ref{Other Git documentation}.
1218 The @code{git@tie{}pull@tie{}origin} command above is just a
1219 shortcut for this command:
1222 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
1226 where @code{@var{branch}} is typically @code{master} or
1227 @code{lilypond/translation}; if you do not know or remember, see
1228 @ref{Downloading remote branches} to remember which commands you
1229 issued or which source code you wanted to get.
1231 A @emph{commit} is a set of changes made to the sources; it also
1232 includes the committish of the parent commit, the name and e-mail
1233 of the @emph{author} (the person who wrote the changes), the name
1234 and e-mail of the @emph{committer} (the person who brings these
1235 changes into the Git repository), and a commit message.
1237 A @emph{committish} is the SHA1 checksum of a commit, a number
1238 made of 40 hexadecimal digits, which acts as the internal unique
1239 identifier for this commit. To refer to a particular revision,
1240 don't use vague references like the (approximative) date, simply
1241 copy and paste the committish.
1243 A @emph{branch} is nothing more than a pointer to a particular
1244 commit, which is called the @emph{head} of the branch; when
1245 referring to a branch, one often actually thinks about its head
1246 and the ancestor commits of the head.
1248 Now we will explain the two last commands you used to get the
1249 source code from Git---see @ref{Downloading individual branches}.
1252 git remote add -ft @var{branch} -m @var{branch} \
1253 origin git://git.sv.gnu.org/lilypond.git/
1255 git checkout -b @var{branch} origin/@var{branch}
1258 The @command{git@tie{}remote} has created a branch called
1259 @code{origin/@var{branch}} in your local Git repository. As this
1260 branch is a copy of the remote branch web from git.sv.gnu.org
1261 LilyPond repository, it is called a @emph{remote branch}, and is
1262 meant to track the changes on the branch from git.sv.gnu.org: it
1263 will be updated every time you run
1264 @command{git@tie{}pull@tie{}origin} or
1265 @command{git@tie{}fetch@tie{}origin}.
1267 The @command{git@tie{}checkout} command has created a branch named
1268 @code{@var{branch}}. At the beginning, this branch is identical
1269 to @code{origin/@var{branch}}, but it will differ as soon as you
1270 make changes, e.g. adding newly translated pages or editing some
1271 documentation or code source file. Whenever you pull, you merge
1272 the changes from @code{origin/@var{branch}} and
1273 @code{@var{branch}} since the last pulling. If you do not have
1274 push (i.e. @qq{write}) access on git.sv.gnu.org, your
1275 @code{@var{branch}} will always differ from
1276 @code{origin/@var{branch}}. In this case, remember that other
1277 people working like you with the remote branch @code{@var{branch}}
1278 of git://git.sv.gnu.org/lilypond.git/ (called
1279 @code{origin/@var{branch}} on your local repository) know nothing
1280 about your own @code{@var{branch}}: this means that whenever you
1281 use a committish or make a patch, others expect you to take the
1282 latest commit of @code{origin/@var{branch}} as a reference.
1284 Finally, please remember to read the man page of every Git command
1285 you will find in this manual in case you want to discover
1286 alternate methods or just understand how it works.
1289 @node Resolving conflicts
1290 @subsection Resolving conflicts
1293 Occasionally an update may result in conflicts -- this happens
1294 when you and somebody else have modified the same part of the same
1295 file and git cannot figure out how to merge the two versions
1296 together. When this happens, you must manually merge the two
1299 If you need some documentation to understand and resolve
1300 conflicts, see paragraphs @emph{How conflicts are presented} and
1301 @emph{How to resolve conflicts} in @command{git merge} man page.
1303 If all else fails, you can follow the instructions in
1304 @ref{Reverting all local changes}. Be aware that this eliminates
1305 any changes you have made!
1308 @node Reverting all local changes
1309 @subsection Reverting all local changes
1311 Sometimes git will become hopelessly confused, and you just want
1312 to get back to a known, stable state. This command destroys any
1313 local changes you have made, but at least you get back to the
1314 current online version:
1317 git reset --hard origin/master
1321 @node Working with remote branches
1322 @subsection Working with remote branches
1325 @subsubheading Fetching new branches from git.sv.gnu.org
1327 To fetch and check out a new branch named @code{@var{branch}} on
1328 git.sv.gnu.org, run from top of the Git repository
1331 git config --add remote.origin.fetch \
1332 +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
1334 git checkout --track -b @var{branch} origin/@var{branch}
1337 After this, you can pull @code{@var{branch}} from git.sv.gnu.org
1344 Note that this command generally fetches all branches you added
1345 with @command{git@tie{}remote@tie{}add} (when you initialized the
1346 repository) or @command{git@tie{}config@tie{}--add}, i.e. it
1347 updates all remote branches from remote @code{origin}, then it
1348 merges the remote branch tracked by the current branch into the
1349 current branch. For example, if your current branch is
1350 @code{master}, @code{origin/master} will be merged into
1354 @subsubheading Local clones, or having several working trees
1356 If you play with several Git branches, e.g. @code{master},
1357 @code{lilypond/translation}, @code{stable/2.12}), you may want to
1358 have one source and build tree for each branch; this is possible
1359 with subdirectories of your local Git repository, used as local
1360 cloned subrepositories. To create a local clone for the branch
1361 named @code{@var{branch}}, run
1364 git checkout @var{branch}
1365 git clone -lsn . @var{subdir}
1370 Note that @code{@var{subdir}} must be a directory name which does
1371 not already exist. In @code{@var{subdir}}, you can use all Git
1372 commands to browse revisions history, commit and uncommit changes;
1373 to update the cloned subrepository with changes made on the main
1374 repository, cd into @code{@var{subdir}} and run
1375 @command{git@tie{}pull}; to send changes made on the subrepository
1376 back to the main repository, run @command{git@tie{}push} from
1377 @code{@var{subdir}}. Note that only one branch (the currently
1378 checked out branch) is created in the subrepository by default; it
1379 is possible to have several branches in a subrepository and do
1380 usual operations (checkout, merge, create, delete...) on these
1381 branches, but this possibility is not detailed here.
1383 When you push @code{@var{branch}} from @code{@var{subdir}} to the
1384 main repository, and @code{@var{branch}} is checked out in the
1385 main repository, you must save uncommitted changes (see
1386 @command{git@tie{}stash}) and do
1387 @command{git@tie{}reset@tie{}--hard} in the main repository in
1388 order to apply pushed changes in the working tree of the main
1396 The commands above don't only bring you the latest version of the
1397 sources, but also the full history of revisions (revisions, also
1398 called commits, are changes made to the sources), stored in the
1399 @file{.git} directory. You can browse this history with
1402 git log # only shows the logs (author, committish and commit message)
1403 git log -p # also shows diffs
1404 gitk # shows history graphically
1407 @warning{The @code{gitk} command may require a separate
1408 @code{gitk} package, available in the appropriate distribution's
1412 @node Applying remote patches
1413 @subsection Applying remote patches
1416 TODO: Explain how to determine if a patch was created with
1417 @code{git@tie{}format-patch}.
1419 Well-formed git patches created with @code{git@tie{}format-patch}
1420 should be committed with the following command:
1426 Patches created without @code{git@tie{}format-patch} can be
1427 applied in two steps. The first step is to apply the patch to the
1431 git apply @var{patch}
1435 The second step is to commit the changes and give credit to the
1436 author of the patch. This can be done with the following command:
1439 git commit -a --author="@var{John Smith} <@var{john@@example.com}>"
1443 @node Sending and receiving patches via email
1444 @subsection Sending and receiving patches via email
1447 The default @code{x-diff} MIME type associated with patch files
1448 (i.e., files whose name ends in @code{.patch}) means that the
1449 encoding of line endings may be changed from UNIX to DOS format
1450 when they are sent as attachments. Attempting to apply such an
1451 inadvertently altered patch will cause git to fail with a message
1452 about @q{whitespace errors}.
1454 The solution to such problems is surprisingly simple---just change
1455 the default file extension of patches generated by git to end in
1456 @code{.txt}, for example:
1459 git config format.suffix '.patch.txt'
1462 This should cause email programs to apply the correct base64
1463 encoding to attached patches.
1465 If you receive a patch with DOS instead of UNIX line-endings, it
1466 can be converted back using the @code{dos2unix} utility.
1468 Lots of useful information on email complications with patches is
1469 provided on the Wine wiki at
1470 @uref{http://wiki.winehq.org/GitWine}.
1474 @subsection Commit access
1477 Most contributors are not able to commit patches directly to the
1478 main repository---only members of the LilyPond development team
1479 have @emph{commit access}. If you are a contributor and are
1480 interested in joining the development team, contact the Project
1481 Manager through the mailing list
1482 (@email{lilypond-devel@@gnu.org}). Generally, only contributors
1483 who have already provided a number of patches which have been
1484 pushed to the main repository will be considered for membership.
1486 If you have been approved by the Project Manager, use the
1487 following procedure to obtain commit access:
1491 If you don't already have one, set up a Savannah user account at
1492 @uref{https://savannah.gnu.org/account/register.php}. If your web
1493 browser responds with an @qq{untrusted connection} message when
1494 you visit the link, follow the steps for including the CAcert root
1495 certificate in your browser, given at
1496 @uref{http://savannah.gnu.org/tls/tutorial/}.
1500 After registering, if you are not logged in automatically, login
1501 at @uref{https://savannah.gnu.org/account/login.php}---this should
1502 take you to your @qq{my} page
1503 (@uref{https://savannah.gnu.org/my/}).
1507 Click on the @qq{My Groups} link to access the @qq{My Group
1508 Membership} page. From there, find the @qq{Request for Inclusion}
1509 box and search for @qq{LilyPond}. Among the search results, check
1510 the box labeled @qq{GNU LilyPond Music Typesetter} and write a
1511 brief (required) message for the Project Manager (@qq{Hey it's
1512 me!} should be fine).
1514 Note that you will not have commit access until the Project
1515 Manager activates your membership. Once your membership is
1516 activated, LilyPond should appear under the heading @qq{Groups I'm
1517 Contributor of} on your @qq{My Group Membership} page.
1521 Generate an SSH @q{dsa} key pair. Enter the following at the
1528 When prompted for a location to save the key, press <ENTER> to
1529 accept the default location (@file{~/.ssh/id_dsa}).
1531 Next you are asked to enter an optional passphrase. On most
1532 systems, if you use a passphrase, you will likely be prompted for
1533 it every time you use @command{git@tie{}push} or
1534 @command{git@tie{}pull}. You may prefer this since it can protect
1535 you from your own mistakes (like pushing when you mean to pull),
1536 though you may find it tedious to keep re-entering it.
1538 You can change/enable/disable your passphrase at any time with:
1541 ssh-keygen -f ~/.ssh/id_dsa -p
1544 Note that the GNOME desktop has a feature which stores your
1545 passphrase for you for an entire GNOME session. If you use a
1546 passphrase to @qq{protect you from yourself}, you will want to
1547 disable this feature, since you'll only be prompted once. Run the
1548 following command, then logout of GNOME and log back in:
1551 gconftool-2 --set -t bool \
1552 /apps/gnome-keyring/daemon-components/ssh false
1555 After setting up your passphrase, your private key is saved as
1556 @file{~/.ssh/id_dsa} and your public key is saved as
1557 @file{~/.ssh/id_dsa.pub}.
1561 Register your public SSH @q{dsa} key with Savannah. From the
1562 @qq{My Account Configuration} page, click on @qq{Edit SSH Keys},
1563 then paste the contents of your @file{~/.ssh/id_dsa.pub} file into
1564 one of the @qq{Authorized keys} text fields, and click
1567 Savannah should respond with something like:
1570 Success: Key #1 seen Keys registered
1575 Configure Git to use the SSH protocol (instead of the GIT
1576 protocol). From your local Git repository, enter:
1579 git config remote.origin.url \
1580 ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1584 where @var{user} is your username on Savannah.
1588 After your membership has been activated and you've configured Git
1589 to use SSH, test the connection with:
1595 SSH should issue the following warning:
1598 The authenticity of host 'git.sv.gnu.org (140.186.70.72)' can't
1600 RSA key fingerprint is
1601 80:5a:b0:0c:ec:93:66:29:49:7e:04:2b:fd:ba:2c:d5.
1602 Are you sure you want to continue connecting (yes/no)?
1605 Make sure the RSA key fingerprint displayed matches the one above.
1606 If it doesn't, respond @qq{no} and check that you configured Git
1607 properly in the previous step. If it does match, respond
1608 @qq{yes}. SSH should then issue another warning:
1611 Warning: Permanently added 'git.sv.gnu.org,140.186.70.72' (RSA) to
1612 the list of known hosts.
1615 The list of known hosts is stored in the file
1616 @file{~/.ssh/known_hosts}.
1618 At this point, you are prompted for your passphrase if you have
1619 one, then Git will attempt a pull.
1621 If @command{git@tie{}pull@tie{}--verbose} fails, you should see
1622 error messages like these:
1625 Permission denied (publickey).
1626 fatal: The remote end hung up unexpectedly
1629 If you get the above error, you may have made a mistake when
1630 registering your SSH key at Savannah. If the key is properly
1631 registered, you probably just need to wait for the Savannah server
1632 to activate it. It usually takes a few minutes for the key to be
1633 active after registering it, but if it still doesn't work after an
1634 hour, ask for help on the mailing list.
1636 If @command{git@tie{}pull@tie{}--verbose} succeeds, the output
1637 will include a @q{From} line that shows @q{ssh} as the protocol:
1640 From ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond
1643 If the protocol shown is not @q{ssh}, check that you configured
1644 Git properly in the previous step.
1648 Test your commit access with a dry run:
1651 git push --dry-run --verbose
1654 Note that recent versions of Git (Git 1.6.3 or later) will issue a
1655 big warning if the above command is used. The simplest solution
1656 is to tell Git to push all matching branches by default:
1659 git config push.default matching
1663 Then @code{git@tie{}push} should work as before. For more
1664 details, consult the @code{git@tie{}push} man page.
1668 @subsubheading Technical details
1672 On Firefox, to view or remove the CAcert root certificate, go to:
1673 Edit > Preferences > Advanced > Encryption > View Certificates >
1674 Authorities > Certificate Name > Root CA > CA Cert Signing
1678 The @command{git@tie{}config} commands above should modify your
1679 local repository's @file{.git/config} file. These lines:
1683 url = git://git.sv.gnu.org/lilypond.git/
1687 should now be changed to:
1691 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1695 where @var{user} is your login name on Savannah.
1699 @command{git@tie{}config@tie{}push.default@tie{}matching} command
1700 should add these lines to @file{.git/config}:
1709 Encryption protocols, including ssh, generally do not permit packet
1710 fragmentation to avoid introducing a point of insecurity. This
1711 means that the maximum packet size must not exceed the smallest
1712 MTU (Maximum Transmission Unit) set in the routers along the path.
1713 This smallest MTU is determined by a procedure during call set-up
1714 which relies on the transmission over the path of ICMP packets.
1715 If any of the routers in the path block ICMP packets this mechanism
1716 fails, resulting in the possibility of packets being transmitted
1717 which exceed the MTU of one of the routers. If this happens the
1718 packet is discarded, causing the ssh session to hang, timeout or
1719 terminate with the error message
1722 ssh: connect to host <host ip addr> port 22: Bad file number
1723 fatal: The remote end hung up unexpectedly
1726 depending on precisely when in the proceedings the first large
1727 packet is transmitted. Most routers on the internet have MTU
1728 set to 1500, but routers installed in homes to connect via
1729 broadband may use a slightly smaller MTU for efficient transmission
1730 over ATM. If this problem is encountered a possible work-around is
1731 to set the MTU in the local router to 1500.
1733 @node Git on Windows
1734 @section Git on Windows
1736 @c Some of this may duplicate stuff in other sections
1737 @c But it is probably best for windows users to have it all together
1738 @c If necessary, clear this up later -td
1740 TODO: Decide what to do with this... Pare it down? Move
1741 paragraphs next to analogous Unix instructions? -mp
1743 @subsection Background to nomenclature
1745 Git is a system for tracking the changes made to source files by a
1746 distributed set of editors. It is designed to work without a
1747 master repository, but we have chosen to have a master repository
1748 for LilyPond files. Editors hold a local copy of the master
1749 repository together with any changes they have made locally.
1750 Local changes are held in a local @q{branch}, of which there may
1751 be several, but these instructions assume you are using just one.
1752 The files visible in the local repository always correspond to
1753 those on the currently @q{checked out} local branch.
1755 Files are edited on a local branch, and in that state the changes
1756 are said to be @q{unstaged}. When editing is complete, the
1757 changes are moved to being @q{staged for commit}, and finally the
1758 changes are @q{committed} to the local branch. Once committed,
1759 the changes (called a @q{commit}) are given a unique 40-digit
1760 hexadecimal reference number called the @q{Committish} or @q{SHA1
1761 ID} which identifies the commit to Git. Such committed changes
1762 can be sent to the master repository by @q{pushing} them (if you
1763 have write permission) or by sending them by email to someone who
1764 has, either as a complete file or as a @q{diff} or @q{patch}
1765 (which send just the differences from the master repository).
1767 @subsection Installing git
1770 @uref{http://code.google.com/p/msysgit/downloads/list} (note, not
1771 msysGit, which is for Git developers and not PortableGit, which is
1772 not a full git installation) and install it.
1774 Note that most users will not need to install SSH. That is not
1775 required until you have been granted direct push permissions to
1776 the master git repository.
1778 Start Git by clicking on the desktop icon. This will bring up a
1779 command line bash shell. This may be unfamiliar to Windows users.
1780 If so, follow these instructions carefully. Commands are entered
1781 at a $ prompt and are terminated by keying a newline.
1783 @subsection Initialising Git
1785 Decide where you wish to place your local Git repository, creating
1786 the folders in Windows as necessary. Here we call the folder to
1787 contain the repository @code{[path]/Git}, but if you intend using
1788 Git for other projects a directory name like @code{lilypond-git}
1789 might be better. You will need to have space for around
1792 Start the Git bash shell by clicking on the desk-top icon
1793 installed with Git and type
1799 to position the shell at your new Git repository.
1801 Note: if [path] contains folders with names containing spaces use
1813 to initialize your Git repository.
1815 Then type (all on one line; the shell will wrap automatically)
1818 git remote add -ft master origin git://git.sv.gnu.org/lilypond.git
1821 to download the lilypond master files.
1823 @warning{Be patient! Even on a broadband connection this can take
1824 10 minutes or more. Wait for lots of [new tag] messages and the $
1827 We now need to generate a local copy of the downloaded files in a
1828 new local branch. Your local branch needs to have a name. It is
1829 usual to call it @q{master} and we shall do that here.
1834 git checkout -b master origin/master
1837 This creates a second branch called @q{master}. You will see two
1838 warnings (ignore these), and a message advising you that your
1839 local branch @q{master} has been set up to track the remote
1840 branch. You now have two branches, a local branch called
1841 @q{master}, and a tracking branch called @q{origin/master}, which
1842 is a shortened form of @q{remotes/origin/master}.
1844 Return to Windows Explorer and look in your Git repository. You
1845 should see lots of folders. For example, the LilyPond
1846 documentation can be found in [path]/Git/Documentation/.
1848 The Git bash shell is terminated by typing @code{exit} or by
1849 clicking on the usual Windows close-window widget.
1853 Almost all subsequent work will use the Git Graphical User
1854 Interface, which avoids having to type command line commands. To
1855 start Git GUI first start the Git bash shell by clicking on the
1856 desktop icon, and type
1863 The Git GUI will open in a new window. It contains four panels
1864 and 7 pull-down menus. At this stage do not use any of the
1865 commands under Branch, Commit, Merge or Remote. These will be
1868 The top panel on the left contains the names of files which you
1869 are in the process of editing (Unstaged Changes), and the lower
1870 panel on the left contains the names of files you have finished
1871 editing and have staged ready for committing (Staged Changes). At
1872 present, these panels will be empty as you have not yet made any
1873 changes to any file. After a file has been edited and saved the
1874 top panel on the right will display the differences between the
1875 edited file selected in one of the panels on the left and the last
1876 version committed on the current branch.
1878 The panel at bottom right is used to enter a descriptive message
1879 about the change before committing it.
1881 The Git GUI is terminated by entering CNTL-Q while it is the
1882 active window or by clicking on the usual Windows close-window
1885 @subsection Personalising your local git repository
1887 Open the Git GUI, click on
1893 and enter your name and email address in the left-hand (Git
1894 Repository) panel. Leave everything else unchanged and save it.
1896 Note that Windows users must leave the default setting for line
1897 endings unchanged. All files in a git repository must have lines
1898 terminated by just a LF, as this is required for Merge to work,
1899 but Windows files are terminated by CRLF by default. The git
1900 default setting causes the line endings of files in a Windows git
1901 repository to be flipped automatically between LF and CRLF as
1902 required. This enables files to be edited by any Windows editor
1903 without causing problems in the git repository.
1905 @subsection Checking out a branch
1907 At this stage you have two branches in your local repository,
1908 both identical. To see them click on
1914 You should have one local branch called @q{master} and one
1915 tracking branch called @q{origin/master}. The latter is your
1916 local copy of the @q{remotes/origin/master} branch in the master
1917 LilyPond repository. The local @q{master} branch is where you
1918 will make your local changes.
1920 When a particular branch is selected, i.e., checked out, the files
1921 visible in your repository are changed to reflect the state of the
1922 files on that branch.
1924 @subsection Updating files from @q{remote/origin/master}
1926 Before starting the editing of a file, ensure your local
1927 repository contains the latest version of the files in the remote
1928 repository by first clicking
1931 Remote -> Fetch from -> origin
1937 This will place the latest version of every file, including all
1938 the changes made by others, into the @q{origin/master} branch of
1939 the tracking branches in your git repository. You can see these
1940 files by checking out this branch, but you must @emph{never} edit
1941 any files while this branch is checked out. Check out your local
1942 @q{master} branch again.
1944 You then need to merge these fetched files into your local
1945 @q{master} branch by clicking on
1948 Merge -> Local Merge
1952 and if necessary select the local @q{master} branch.
1954 Note that a merge cannot be completed if you have made any local
1955 changes which have not yet been committed.
1957 This merge will update all the files in the @q{master} branch to
1958 reflect the current state of the @q{origin/master} branch. If any
1959 of the changes conflict with changes you have made yourself
1960 recently you will be notified of the conflict (see below).
1962 @subsection Editing files
1964 First ensure your @q{master} branch is checked out, then simply
1965 edit the files in your local Git repository with your favourite
1966 editor and save them back there. If any file contains non-ASCII
1967 characters ensure you save it in UTF-8 format. Git will detect
1968 any changes whenever you restart Git GUI and the file names will
1969 then be listed in the Unstaged Changes panel. Or you can click
1970 the Rescan button to refresh the panel contents at any time. You
1971 may break off and resume editing any time.
1973 The changes you have made may be displayed in diff form in the top
1974 right-hand panel of Git GUI by clicking on the file name shown in
1975 one of the left panels.
1977 When your editing is complete, move the files from being Unstaged
1978 to Staged by clicking the document symbol to the left of each
1979 name. If you change your mind it can be moved back by clicking on
1980 the ticked box to the left of the name.
1982 Finally the changes you have made may be committed to your
1983 @q{master} branch by entering a brief message in the Commit
1984 Message box and clicking the Commit button.
1986 If you wish to amend your changes after a commit has been made,
1987 the original version and the changes you made in that commit may
1988 be recovered by selecting
1991 Commit -> Amend Last Commit
1995 or by checking the Amend Last Commit radio button at bottom right.
1996 This will return the changes to the Staged state, so further
1997 editing made be carried out within that commit. This must only be
1998 done @emph{before} the changes have been Pushed or sent to your
1999 mentor for Pushing - after that it is too late and corrections
2000 have to be made as a separate commit.
2003 @subsection Sending changes to @q{remotes/origin/master}
2005 If you do not have write access to @q{remotes/origin/master} you
2006 will need to send your changes by email to someone who does.
2008 First you need to create a diff or patch file containing your
2009 changes. To create this, the file must first be committed. Then
2010 terminate the Git GUI. In the git bash shell first cd to your Git
2017 if necessary, then produce the patch with
2020 git format-patch origin
2023 This will create a patch file for all the locally committed files
2024 which differ from @q{origin/master}. The patch file can be found
2025 in [path]/Git and will have a name formed from the commit message.
2027 @subsection Resolving merge conflicts
2029 As soon as you have committed a changed file your local
2030 @code{master} branch has diverged from @code{origin/master}, and
2031 will remain diverged until your changes have been committed in
2032 @code{remotes/origin/master} and Fetched back into your
2033 @code{origin/master} branch. Similarly, if a new commit has been
2034 made to @code{remotes/origin/master} by someone else and Fetched,
2035 your local @code{master} branch is divergent. You can detect a
2036 divergent branch by clicking on
2039 Repository -> Visualise all branch history
2042 This opens up a very useful new window called @q{gitk}. Use this
2043 to browse all the commits made by yourself and others.
2045 If the diagram at top left of the resulting window does not show
2046 your @code{master} tag on the same node as the
2047 @code{remotes/origin/master} tag your branch has diverged from
2048 @code{origin/master}. This is quite normal if files you have
2049 modified yourself have not yet been Pushed to
2050 @code{remotes/origin/master} and Fetched, or if files modified and
2051 committed by others have been Fetched since you last Merged
2052 @code{origin/master} into your local @code{master} branch.
2054 If a file being merged from @code{origin/master} differs from one
2055 you have modified in a way that cannot be resolved automatically
2056 by git, Merge will report a Conflict which you must resolve by
2057 editing the file to create the version you wish to keep.
2059 This could happen if the person updating
2060 @code{remotes/origin/master} for you has added some changes of his
2061 own before committing your changes to
2062 @code{remotes/origin/master}, or if someone else has changed the
2063 same file since you last fetched the file from
2064 @code{remotes/origin/master}.
2066 Open the file in your editor and look for sections which are
2069 [to be completed when I next have a merge conflict to be sure I
2070 give the right instructions -td]
2073 @subsection Other actions
2075 The instructions above describe the simplest way of using git on
2076 Windows. Other git facilities which may usefully supplement these
2080 @item Using multiple local branches (Create, Rename, Delete)
2081 @item Resetting branches
2082 @item Cherry-picking commits
2083 @item Pushing commits to @w{remote/origin/master}
2084 @item Using gitk to review history
2087 Once familiarity with using git on Windows has been gained the
2088 standard git manuals can be used to learn about these.
2091 @node Repository directory structure
2092 @section Repository directory structure
2095 @c TODO: integrate the roadmap better
2096 @verbatiminclude ROADMAP
2099 @node Other Git documentation
2100 @section Other Git documentation
2104 Official git man pages:
2105 @uref{http://www.kernel.org/pub/software/scm/git/docs/}
2108 More in-depth tutorials: @uref{http://git-scm.com/documentation}
2111 Book about git: @uref{http://progit.org/,Pro Git}