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
42 @warning{The rest of this manual assumes that you are using the
43 command-line; go to @clicksequence{Applications @click{}
44 Accessories @click{} Terminal}.}
48 @code{lily-git.tcl} has already been install for you. Simply type
57 Click on the @qq{Get source} button.
59 This will create a directory called @file{lilypond-git/} within
60 your home directory, and will download the source code into that
61 directory (around 55Mb). When the process is finished, the
62 @qq{Command output} window will display @qq{Done}, and the button
63 label will change to say @qq{Update source}.
66 Navigate to the @file{lilypond-git/} directory to view the source
67 files. You should now be able to modify the source files using
68 your normal text editor.
72 You should now progress to @ref{Compiling with lilybuntu}.
74 @warning{Throughout the rest of this manual, most command-line
75 input should be entered from @file{~/lilypond-git/}. This is
76 referred to as the @emph{top source directory}.}
79 @subsubheading Other operating music systems
83 If you haven't already, download and install Git.
88 Lilybuntu users: git has already been installed for you.
90 @item Windows users: download the @code{.exe} file labeled
91 @qq{Full installer for official Git} from:
94 @uref{http://code.google.com/p/msysgit/downloads/list}
97 @item Other operating systems: either install @command{git} with
98 your package manager, or download it from the @qq{Binaries}
102 @uref{http://git-scm.com/download}
109 Download the @command{lily-git.tcl} script from:
111 @c don't change the cgit link below to gitweb; gitweb uses
112 @c long filenames like "scripts_auxiliar_lily-git.tcl"
115 @uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
119 To run the program from the command line, navigate to the
120 directory containing @command{lily-git.tcl} and enter:
127 Go read the lilybuntu instructions, starting from the @qq{get
132 @advanced{the @qq{Get source} button does not fetch the entire
133 history of the git repository, so utilities like @command{gitk}
134 will only be able to display the most recent additions. As you
135 continue to work with @command{lily-git.tcl}, the @qq{Update
136 source} button will take any new additions and add it to whatever
137 is currently in your repository's history.}
140 @node Daily use of lily-git.tcl
141 @unnumberedsubsec Daily use of @command{lily-git.tcl}
143 @warning{Only work on one set of changes at once. Do not start
144 work on any new changes until your first set has been accepted.}
146 @subsubheading 1. Update source
148 At the beginning of each session of lilypond work, you should
149 click the @qq{Update source} button to get the latest changes to
152 @warning{In some rare and unfortunate circumstances, this will
153 result in a @emph{merge conflict}. If this occurs, follow the
154 instructions for @qq{Abort changes}, below. Your work will not be
158 @subsubheading 2a. New local commit
160 A single commit typically represents one logical set of related
161 changes (such as a bug-fix), and may incorporate changes to
162 multiple files at the same time.
164 When you're finished making the changes for a commit, click the
165 @qq{New local commit} button. This will open the @qq{Git Commit
166 Message} window. The message header is required, and the message
169 After entering a commit message, click @qq{OK} to finalize the
172 @advanced{for more information regarding commits and commit
173 messages, see @ref{Commits and patches}.}
176 @subsubheading 2b. Amend previous commit
178 You can go back and make changes to the most recent commit with
179 the @qq{Amend previous commit} button. This is useful if a
180 mistake is found after you have clicked the @qq{New local commit}
183 To amend the most recent commit, re-edit the source files as
184 needed and then click the @qq{Amend previous commit} button. The
185 earlier version of the commit is not saved, but is replaced by the
188 @warning{This does not update the patch @strong{files}; if you
189 have a patch file from an earlier version of the commit, you will
190 need to make another patch set when using this feature. The old
191 patch file will not be saved, but will be replaced by the new one
192 after you click on @qq{Make patch set}.}
195 @subsubheading 3. Make patch set
197 Before making a patch set from any commits, you should click the
198 @qq{Update source} button to make sure the commits are based on
199 the most recent remote snapshot.
201 When you click the @qq{Make patch set} button,
202 @command{lily-git.tcl} will produce patch files for any new
203 commits, saving them to the current directory. The command output
204 will display the name of the new patch files near the end of the
208 0001-CG-add-lily-git-instructions.patch
212 Send patch files to the appropriate place:
216 If you have a mentor, send it to them via email.
219 New contributors should send the patch attached to an email to
220 @email{frogs@@lilynet.net}. Please add @qq{[PATCH]} to the
224 Translators should send patches to
225 @email{translations@@lilynet.net}.
228 More experienced contributors should upload the patch for
229 web-based review. This requires additional software and use of
230 the command-line; see @ref{Uploading a patch for review}.
235 @subsubheading The @qq{Abort changes -- Reset to origin} button
237 @warning{Only use this if your local commit history gets
238 hopelessly confused!}
240 The button labeled @qq{Abort changes -- Reset to origin} will copy
241 all changed files to a subdirectory of @file{lilypond-git/} named
242 @file{aborted_edits/}, and will reset the repository to the
243 current state of the remote repository (at @code{git.sv.gnu.org}).
246 @node Starting with Git
247 @section Starting with Git
250 Using the Git program directly (as opposed to using the
251 @command{lily-git.tcl} GUI) allows you to have much greater control
252 over the contributing process. You should consider using Git if
253 you want to work on complex projects, or if you want to work on
254 multiple projects concurrently.
259 * Downloading remote branches::
264 @subsection Setting up
267 TODO: Remove this note if incorporating Windows instructions
268 throughout this section:
270 @warning{These instructions assume that you are using the
271 command-line version of Git 1.5 or higher. Windows users should
272 skip to @ref{Git on Windows}.}
276 * Initializing a repository::
282 @unnumberedsubsubsec Installing Git
285 If you are using a Unix-based machine, the easiest way to download
286 and install Git is through a package manager such as @command{rpm}
287 or @command{apt-get}---the installation is generally automatic.
288 The only required package is (usually) called @command{git-core},
289 although some of the auxiliary @command{git@var{*}} packages are
290 also useful (such as @command{gitk}).
292 Alternatively, you can visit the Git website
293 (@uref{http://git-scm.com/}) for downloadable binaries and
296 TODO: add Windows installation instructions (or @@ref@{Git on
300 @node Initializing a repository
301 @unnumberedsubsubsec Initializing a repository
304 Once Git is installed, you'll need to create a new directory where
305 your initial repository will be stored (the example below uses
306 @file{~/lilypond-git/}, where @code{~} represents your home
307 directory). Run @command{git@tie{}init} from within the new
308 directory to initialize an empty repository:
311 mkdir ~/lilypond-git/; cd ~/lilypond-git/
315 @subsubheading Technical details
317 This creates (within the @file{~/lilypond-git/} directory) a
318 subdirectory called @file{.git/}, which Git uses to keep track of
319 changes to the repository, among other things. Normally you don't
320 need to access it, but it's good to know it's there.
323 @node Configuring Git
324 @unnumberedsubsubsec Configuring Git
326 @warning{Throughout the rest of this manual, all command-line
327 input should be entered from the top directory of the Git
328 repository being discussed (eg. @file{~/lilypond-git/}). This is
329 referred to as the @emph{top source directory}.}
331 Before downloading a copy of the main LilyPond repository, you
332 should configure some basic settings with the
333 @command{git@tie{}config} command. Git allows you to set both
334 global and repository-specific options.
336 To configure settings that affect all repositories, use the
337 @command{--global} command line option. For example, the first
338 two options that you should always set are your @var{name} and
339 @var{email}, since Git needs these to keep track of commit
343 git config --global user.name "@var{John Smith}"
344 git config --global user.email @var{john@@example.com}
347 To configure Git to use colored output where possible, use:
350 git config --global color.ui auto
353 The text editor that opens when using @command{git@tie{}commit}
354 can also be changed. If none of your editor-related environment
355 variables are set ($GIT_EDITOR, $VISUAL, or $EDITOR), the default
356 editor is usually @command{vi} or @command{vim}. If you're not
357 familiar with either of these, you should probably change the
358 default to an editor that you know how to use. For example, to
359 change the default editor to @command{nano}, enter:
362 git config --global core.editor @var{nano}
365 TODO: Add instructions for changing the editor on Windows, which
366 is a little different, I think. -mp
368 @subsubheading Technical details
370 Git stores the information entered with
371 @command{git@tie{}config@tie{}--global} in the file
372 @file{.gitconfig}, located in your home directory. This file can
373 also be modified directly, without using
374 @command{git@tie{}config}. The @file{.gitconfig} file generated
375 by the above commands would look like this:
380 email = john@@example.com
387 Using the @command{git@tie{}config} command @emph{without} the
388 @command{--global} option configures repository-specific settings,
389 which are stored in the file @file{.git/config}. This file is
390 created when a repository is initialized (using
391 @command{git@tie{}init}), and by default contains these lines:
395 repositoryformatversion = 0
398 logallrefupdates = true
401 However, since different repository-specific options are
402 recommended for different development tasks, it is best to avoid
403 setting any now. Specific recommendations will be mentioned later
407 @node Downloading remote branches
408 @subsection Downloading remote branches
412 * Organization of remote branches::
413 * LilyPond repository sources::
414 * Downloading individual branches::
415 * Downloading all remote branches::
420 @node Organization of remote branches
421 @unnumberedsubsubsec Organization of remote branches
424 The main LilyPond repository is organized into @emph{branches} to
425 facilitate development. These are often called @emph{remote}
426 branches to distinguish them from @emph{local} branches you might
427 create yourself (see @ref{Using local branches}).
429 The @code{master} branch contains all the source files used to
430 build LilyPond, which includes the program itself (both stable and
431 development releases), the documentation (and its translations),
432 and the website. Generally, the @code{master} branch is expected
433 to compile successfully.
435 The @code{lilypond/translation} branch is a side branch that
436 allows translators to work without needing to worry about
437 compilation problems. Periodically, the Translation Meister
438 (after verifying that it doesn't break compilation), will
439 @emph{merge} this branch back into @code{master} to incorporate
440 recent translations. Similarly, the @code{master} branch is
441 usually merged into the @code{lilypond/translation} branch after
442 significant changes to the English documentation. See
443 @ref{Translating the documentation} for details.
446 @node LilyPond repository sources
447 @unnumberedsubsubsec LilyPond repository sources
450 The recommended source for downloading a copy of the main
454 git://git.sv.gnu.org/lilypond.git
457 However, if your internet router filters out connections using the
458 GIT protocol, or if you experience difficulty connecting via GIT,
459 you can try these other sources:
462 ssh://git.sv.gnu.org/srv/git/lilypond.git
463 http://git.sv.gnu.org/r/lilypond.git
466 The SSH protocol can only be used if your system is properly set
467 up to use it. Also, the HTTP protocol is slowest, so it should
468 only be used as a last resort.
471 @node Downloading individual branches
472 @unnumberedsubsubsec Downloading individual branches
475 Once you have initialized an empty Git repository on your system
476 (see @ref{Initializing a repository}), you can download a remote
477 branch into it. Make sure you know which branch you want to start
480 To download the @code{master} branch, enter the following:
483 git remote add -ft master -m master \
484 origin git://git.sv.gnu.org/lilypond.git/
487 To download the @code{lilypond/translation} branch, enter:
490 git remote add -ft lilypond/translation -m \
491 lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
494 The @command{git@tie{}remote@tie{}add} process could take up to
495 ten minutes, depending on the speed of your connection. The
496 output will be something like this:
500 remote: Counting objects: 235967, done.
501 remote: Compressing objects: 100% (42721/42721), done.
502 remote: Total 235967 (delta 195098), reused 233311 (delta 192772)
503 Receiving objects: 100% (235967/235967), 68.37 MiB | 479 KiB/s, done.
504 Resolving deltas: 100% (195098/195098), done.
505 From git://git.sv.gnu.org/lilypond
506 * [new branch] master -> origin/master
507 From git://git.sv.gnu.org/lilypond
508 * [new tag] flower/1.0.1 -> flower/1.0.1
509 * [new tag] flower/1.0.10 -> flower/1.0.10
511 * [new tag] release/2.9.6 -> release/2.9.6
512 * [new tag] release/2.9.7 -> release/2.9.7
515 When @command{git@tie{}remote@tie{}add} is finished, the remote
516 branch should be downloaded into your repository---though not yet
517 in a form that you can use. In order to browse the source code
518 files, you need to @emph{create} and @emph{checkout} your own
519 local branch. In this case, however, it is easier to have Git
520 create the branch automatically by using the @command{checkout}
521 command on a non-existent branch. Enter the following:
524 git checkout -b @var{branch} origin/@var{branch}
528 where @code{@var{branch}} is the name of your tracking branch,
529 either @code{master} or @code{lilypond/translation}.
531 Git will issue some warnings; this is normal:
534 warning: You appear to be on a branch yet to be born.
535 warning: Forcing checkout of origin/master.
536 Branch master set up to track remote branch master from origin.
540 By now the source files should be accessible---you should be able
541 to edit any files in the @file{lilypond-git/} directory using a
542 text editor of your choice. But don't start just yet! Before
543 editing any source files, learn how to keep your changes organized
544 and prevent problems later---read @ref{Basic Git procedures}.
546 @subsubheading Technical Details
548 The @command{git@tie{}remote@tie{}add} command should add some
549 lines to your local repository's @file{.git/config} file:
553 url = git://git.sv.gnu.org/lilypond.git/
554 fetch = +refs/heads/master:refs/remotes/origin/master
558 @node Downloading all remote branches
559 @unnumberedsubsubsec Downloading all remote branches
562 To download all remote branches at once, you can @command{clone}
563 the entire repository:
566 git clone git://git.sv.gnu.org/lilypond.git
571 @unnumberedsubsubsec Other branches
573 Most contributors will never need to touch the other branches. If
574 you wish to do so, you will need more familiarity with Git; please
575 see @ref{Other Git documentation}.
578 @item @code{dev/XYZ}:
579 These branches are for individual developers. They store code
580 which is not yet stable enough to be added to the @code{master}
583 @item @code{stable/XYZ}:
584 The branches are kept for archival reasons.
588 Another item of interest might be the Grand Unified Builder, our
589 cross-platform building tool. Since it is used by projects as
590 well, it is not stored in our gub repository. For more info, see
591 @uref{http://lilypond.org/gub}. The git location is
592 @uref{http://github.com/janneke/gub}.
595 @node Basic Git procedures
596 @section Basic Git procedures
600 * The Git contributor's cycle::
601 * Pulling and rebasing::
602 * Using local branches::
603 * Commits and patches::
607 @node The Git contributor's cycle
608 @subsection The Git contributor's cycle
611 Here is a simplified view of the contribution process on Git:
615 Update your local repository by @emph{pulling} the most recent
616 updates from the remote repository.
619 Edit source files within your local repository's @emph{working
623 @emph{Commit} the changes you've made to a local @emph{branch}.
626 Generate a @emph{patch} to share your changes with the developers.
630 @node Pulling and rebasing
631 @subsection Pulling and rebasing
634 When developers push new patches to the @code{git.sv.gnu.org}
635 repository, your local repository is @strong{not} automatically
636 updated. It is important to keep your repository up-to-date by
637 periodically @emph{pulling} the most recent @emph{commits} from
638 the remote branch. Developers expect patches to be as current as
639 possible, since outdated patches require extra work before they
642 Occasionally you may need to rework some of your own modifications
643 to match changes made to the remote branch (see @ref{Resolving
644 conflicts}), and it's considerably easier to rework things
645 incrementally. If you don't update your repository along the way,
646 you may have to spend a lot of time resolving branch conflicts and
647 reconfiguring much of the work you've already done.
649 Fortunately, Git is able to resolve certain types of branch
650 conflicts automatically with a process called @emph{rebasing}.
651 When rebasing, Git tries to modify your old commits so they appear
652 as new commits (based on the latest updates). For a more involved
653 explanation, see the @command{git-rebase} man page.
655 To pull without rebasing (recommended for translators), use the
659 git pull # recommended for translators
662 If you're tracking the remote @code{master} branch, you should add
663 the @code{-r} option (short for @code{--rebase}) to keep commits
664 on your local branch current:
667 git pull -r # use with caution when translating
670 If you don't edit translated documentation and don't want to type
671 @code{-r} every time, configure the master branch to rebase by
672 default with this command:
675 git config branch.master.rebase true
678 If pull fails because of a message like
681 error: Your local changes to 'Documentation/learning/tutorial.itely'
682 would be overwritten by merge. Aborting.
689 Documentation/learning/tutorial.itely: needs update
690 refusing to pull with rebase: your working tree is not up-to-date
694 it means that you have modified some files in you working tree
695 without committing changes (see @ref{Commits and patches}); you
696 can use the @command{git@tie{}stash} command to work around this:
699 git stash # save uncommitted changes
700 git pull -r # pull using rebase (translators omit "-r")
701 git stash pop # reapply previously saved changes
704 Note that @command{git@tie{}stash@tie{}pop} will try to apply a
705 patch, and this may create a conflict. If this happens, see
706 @ref{Resolving conflicts}.
708 TODO: I think the next paragraph is confusing. Perhaps prepare
709 the reader for new terms `committish' and `head'? -mp
711 @warning{translators and documentation editors, if you have
712 changed committishes in the head of translated files using commits
713 you have not yet pushed to @code{git.sv.gnu.org}, please do not
714 rebase. If you want to avoid wondering whether you should rebase
715 each time you pull, please always use committishes from master
716 and/or lilypond/translation branch on @code{git.sv.gnu.org}, which
717 in particular implies that you must push your changes to
718 documentation except committishes updates (possibly after having
719 rebased), then update the committishes and push them.}
721 TODO: when committishes automatic conditional update have been
722 tested and documented, append the following to the warning above:
723 Note that using update-committishes make target generally touches
726 @subsubheading Technical details
728 The @command{git@tie{}config} command mentioned above adds the
729 line @code{rebase = true} to the master branch in your local
730 repository's @file{.git/config} file:
735 merge = refs/heads/master
740 @node Using local branches
741 @subsection Using local branches
745 * Creating and removing branches::
746 * Listing branches and remotes::
747 * Checking out branches::
752 @node Creating and removing branches
753 @unnumberedsubsubsec Creating and removing branches
756 Local branches are useful when you're working on several different
757 projects concurrently. To create a new branch, enter:
760 git branch @var{name}
763 To delete a branch, enter:
766 git branch -d @var{name}
769 Git will ask you for confirmation if it sees that data would be
770 lost by deleting the branch. Use @code{-D} instead of @code{-d}
771 to bypass this. Note that you cannot delete a branch if it is
772 currently checked out.
775 @node Listing branches and remotes
776 @unnumberedsubsubsec Listing branches and remotes
778 You can get the exact path or URL of all remote branches by
785 To list Git branches on your local repositories, run
788 git branch # list local branches only
789 git branch -r # list remote branches
790 git branch -a # list all branches
794 @node Checking out branches
795 @unnumberedsubsubsec Checking out branches
797 To know the currently checked out branch, i.e. the branch whose
798 source files are present in your working tree, read the first line
806 The currently checked out branch is also marked with an asterisk
807 in the output of @command{git branch}.
809 You can check out another branch @code{@var{other_branch}}, i.e.
810 check out @code{@var{other_branch}} to the working tree, by
814 git checkout @var{other_branch}
817 Note that it is possible to check out another branch while having
818 uncommitted changes, but it is not recommended unless you know
819 what you are doing; it is recommended to run @command{git status}
820 to check this kind of issue before checking out another branch.
822 @node Merging branches
823 @unnumberedsubsubsec Merging branches
825 To merge branch @code{@var{foo}} into branch @code{@var{bar}},
826 i.e. to @qq{add} all changes made in branch @code{@var{foo}} to
827 branch @code{@var{bar}}, run
830 git checkout @var{bar}
834 If any conflict happens, see @ref{Resolving conflicts}.
836 There are common usage cases for merging: as a translator, you
837 will often want to merge @code{master} into
838 @code{lilypond/translation}; on the other hand, the Translations
839 meister wants to merge @code{lilypond/translation} into
840 @code{master} whenever he has checked that
841 @code{lilypond/translation} builds successfully.
844 @node Commits and patches
845 @subsection Commits and patches
849 * Understanding commits::
853 * Uploading a patch for review::
857 @node Understanding commits
858 @unnumberedsubsubsec Understanding commits
860 Technically, a @emph{commit} is a single point in the history of a
861 branch, but most developers use the term to mean a @emph{commit
862 object}, which stores information about a particular revision. A
863 single commit can record changes to multiple source files, and
864 typically represents one logical set of related changes (such as a
865 bug-fix). You can list the ten most recent commits in your
866 current branch with this command:
869 git log -10 --oneline
872 If you're using an older version of Git and get an @q{unrecognized
873 argument} error, use this instead:
876 git log -10 --pretty=oneline --abbrev-commit
879 More interactive lists of the commits on the remote @code{master}
880 branch are available at
881 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=shortlog} and
882 @uref{http://git.sv.gnu.org/cgit/lilypond.git/log/}.
886 @unnumberedsubsubsec Making commits
889 Once you have modified some source files in your working
890 directory, you can make a commit with the following procedure:
894 Make sure you've configured Git properly (see @ref{Configuring
895 Git}). Check that your changes meet the requirements described in
896 @ref{Code style} and/or @ref{Documentation policy}. For advanced
897 edits, you may also want to verify that the changes don't break
898 the compilation process.
901 Run the following command:
908 to make sure you're on the right branch, and to see which files
909 have been modified, added or removed, etc. You may need to tell
910 Git about any files you've added by running one of these:
913 git add @var{file} # add untracked @var{file} individually
914 git add . # add all untracked files in current directory
918 After @command{git@tie{}add}, run @command{git@tie{}status} again
919 to make sure you got everything. You may also need to modify
923 Preview the changes about to be committed (to make sure everything
931 The @code{HEAD} argument refers to the most recent commit on the
932 currently checked-out branch.
935 Generate the commit with:
942 The @code{-a} is short for @code{--all} which includes modified
943 and deleted files, but only those newly created files that have
944 previously been added.
949 @node Commit messages
950 @unnumberedsubsubsec Commit messages
953 When you run the @command{git@tie{}commit@tie{}-a} command, Git
954 automatically opens the default text editor so you can enter a
955 @emph{commit message}. If you find yourself in a foreign editing
956 environment, you're probably in @command{vi} or @command{vim}. If
957 you want to switch to an editor you're more familiar with, quit by
958 typing @code{:q!} and pressing @code{<Enter>}. See
959 @ref{Configuring Git} for instructions on changing the default
962 In any case, Git will open a text file for your commit message
963 that looks like this:
967 # Please enter the commit message for your changes. Lines starting
968 # with '#' will be ignored, and an empty message aborts the commit.
970 # Changes to be committed:
971 # (use "git reset HEAD <file>..." to unstage)
973 # modified: working.itexi
977 Your commit message should begin with a one-line summary
978 describing the change (no more than 50 characters long), and if
979 necessary a blank line followed by several lines giving the
982 @c $ git log -1 --pretty=medium 4d6f1e5
984 Doc: add Baerenreiter and Henle solo cello suites
986 Added comparison of solo cello suite engravings to new essay with
987 high-res images, fixed cropping on Finale example.
990 Commit messages often start with a short prefix describing the
991 general location of the changes. If a commit affects the
992 documentation in English (or in several languages simultaneously)
993 the commit message should be prefixed with @qq{Doc:@tie{}}. If
994 the commit affects only one of the translations, the commit
995 message should be prefixed with @qq{Doc-@var{**}:@tie{}}, where
996 @var{**} is the two-letter language code. Commits that affect the
997 website should use @qq{Web:@tie{}} for English, and
998 @qq{Web-@var{**}:@tie{}} for the other languages. Also, changes
999 to a single file are often prefixed with the name of the file
1000 involved. Visit the links listed in @ref{Understanding commits}
1004 @node Making patches
1005 @unnumberedsubsubsec Making patches
1007 If you want to share your changes with other contributors and
1008 developers, you need to generate @emph{patches} from your commits.
1009 We prefer it if you follow the instructions in
1010 @ref{Uploading a patch for review}. However, we present an
1011 alternate method here.
1013 You should always run @command{git@tie{}pull@tie{}-r} (translators
1014 should leave off the @code{-r}) before doing this to ensure that
1015 your patches are as current as possible.
1017 Once you have made one or more commits in your local repository,
1018 and pulled the most recent commits from the remote branch, you can
1019 generate patches from your local commits with the command:
1022 git format-patch origin
1025 The @code{origin} argument refers to the remote tracking branch at
1026 @code{git.sv.gnu.org}. This command generates a separate patch
1027 for each commit that's in the current branch but not in the remote
1028 branch. Patches are placed in the current working directory and
1029 will have names that look something like this:
1032 0001-Doc-Fix-typos.patch
1033 0002-Web-Remove-dead-links.patch
1037 Send an email (must be less than 64 KB) to
1038 @email{lilypond-devel@@gnu.org} briefly explaining your work, with
1039 the patch files attached. Translators should send patches to
1040 @email{translations@@lilynet.net}. After your patches are
1041 reviewed, the developers may push one or more of them to the main
1042 repository or discuss them with you.
1045 @node Uploading a patch for review
1046 @unnumberedsubsubsec Uploading a patch for review
1048 Any non-trivial change should be uploaded to our @qq{Rietveld}
1049 code review website:
1052 @uref{http://codereview.appspot.com/}
1055 @subsubheading Initial setup
1060 You must have a gmail account.
1063 Install @command{git-cl} by entering:
1066 git clone git://neugierig.org/git-cl.git
1070 Add the @file{git-cl/} directory to your PATH, or create a
1071 symbolic link to the @command{git-cl} and @command{upload.py}
1072 scripts in one of your PATH directories (such as
1077 Move into the top source directory and then configure
1078 @command{git cl}. If you do not understand any question, just
1079 answer with a newline (CR).
1082 cd $HOME/lilypond-git/
1086 The @qq{CC list} question should be answered with:
1089 lilypond-devel@@gnu.org
1094 @subsubheading Uploading patch set
1096 @warning{Unless you are familiar with branches, only work on one
1097 set of changes at once.}
1099 There are two methods, depending on your git setup.
1103 @strong{Master branch}: (easy option, and used in @command{lily-git.tcl})
1105 If you added your patch to @code{master}, then:
1109 git cl upload origin/master
1112 If you have git push ability, make sure that you @emph{remove}
1113 your patch (with @command{git rebase} or @command{git reset})
1114 before pushing other stuff.
1117 @strong{Separate branch}: (complicated option)
1119 Ensure your changes are committed in a separate branch, which
1120 should differ from the reference branch to be used by just the
1121 changes to be uploaded. If the reference branch is to be
1122 origin/master, ensure this is up-to-date. If necessary, use git
1123 rebase to rebase the branch containing the changes to the head of
1124 origin/master. Finally, check out branch with the changes and
1128 git cl upload <reference SHA1 ID>
1132 where <reference SHA1 ID> is the SHA1 ID of the commit to be used
1133 as a reference source for the patch. Generally, this will be the
1134 SHA1 ID of origin/master, and in that case the command:
1137 git cl upload origin/master
1145 After prompting for your Google email address and password, the
1146 patch set will be posted to Rietveld, and you will be given a URL
1149 @subsubheading Announcing your patch set
1151 You should then announce the patch by logging into the code review
1152 issue webpage and using @qq{Publish + Mail Comments} to add a
1153 (mostly bogus) comment to your issue. The text of your comment
1154 will be sent to our developer mailing list.
1156 @subsubheading Revisions
1158 As revisions are made in response to comments, successive patch sets
1159 for the same issue can be uploaded by reissuing the git-cl command
1160 with the modified branch checked out.
1162 Sometimes in response to comments on revisions, the best way to
1163 work may require creation of a new branch in git. In order to
1164 associate the new branch with an existing Rietveld issue,
1165 the following command can be used:
1168 git cl issue issue-number
1172 where @code{issue-number} is the number of the existing Rietveld
1175 @subsubheading Resetting git cl
1177 If @command{git cl} becomes confused, you can @qq{reset} it by
1185 @node Advanced Git procedures
1186 @section Advanced Git procedures
1189 @warning{This section is not necessary for normal contributors;
1190 these commands are presented for information for people interested
1191 in learning more about git.}
1193 It is possible to work with several branches on the same local Git
1194 repository; this is especially useful for translators who may have
1195 to deal with both @code{lilypond/translation} and a stable branch,
1196 e.g. @code{stable/2.12}.
1198 Some Git commands are introduced first, then a workflow with
1199 several Git branches of LilyPond source code is presented.
1203 * Advanced Git concepts::
1204 * Resolving conflicts::
1205 * Reverting all local changes::
1206 * Working with remote branches::
1208 * Applying remote patches::
1209 * Sending and receiving patches via email::
1214 @node Advanced Git concepts
1215 @subsection Advanced Git concepts
1218 A bit of Git vocabulary will be explained below. The following is
1219 only introductory; for a better understanding of Git concepts, you
1220 may wish to read @ref{Other Git documentation}.
1222 The @code{git@tie{}pull@tie{}origin} command above is just a
1223 shortcut for this command:
1226 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
1230 where @code{@var{branch}} is typically @code{master} or
1231 @code{lilypond/translation}; if you do not know or remember, see
1232 @ref{Downloading remote branches} to remember which commands you
1233 issued or which source code you wanted to get.
1235 A @emph{commit} is a set of changes made to the sources; it also
1236 includes the committish of the parent commit, the name and e-mail
1237 of the @emph{author} (the person who wrote the changes), the name
1238 and e-mail of the @emph{committer} (the person who brings these
1239 changes into the Git repository), and a commit message.
1241 A @emph{committish} is the SHA1 checksum of a commit, a number
1242 made of 40 hexadecimal digits, which acts as the internal unique
1243 identifier for this commit. To refer to a particular revision,
1244 don't use vague references like the (approximative) date, simply
1245 copy and paste the committish.
1247 A @emph{branch} is nothing more than a pointer to a particular
1248 commit, which is called the @emph{head} of the branch; when
1249 referring to a branch, one often actually thinks about its head
1250 and the ancestor commits of the head.
1252 Now we will explain the two last commands you used to get the
1253 source code from Git---see @ref{Downloading individual branches}.
1256 git remote add -ft @var{branch} -m @var{branch} \
1257 origin git://git.sv.gnu.org/lilypond.git/
1259 git checkout -b @var{branch} origin/@var{branch}
1262 The @command{git@tie{}remote} has created a branch called
1263 @code{origin/@var{branch}} in your local Git repository. As this
1264 branch is a copy of the remote branch web from git.sv.gnu.org
1265 LilyPond repository, it is called a @emph{remote branch}, and is
1266 meant to track the changes on the branch from git.sv.gnu.org: it
1267 will be updated every time you run
1268 @command{git@tie{}pull@tie{}origin} or
1269 @command{git@tie{}fetch@tie{}origin}.
1271 The @command{git@tie{}checkout} command has created a branch named
1272 @code{@var{branch}}. At the beginning, this branch is identical
1273 to @code{origin/@var{branch}}, but it will differ as soon as you
1274 make changes, e.g. adding newly translated pages or editing some
1275 documentation or code source file. Whenever you pull, you merge
1276 the changes from @code{origin/@var{branch}} and
1277 @code{@var{branch}} since the last pulling. If you do not have
1278 push (i.e. @qq{write}) access on git.sv.gnu.org, your
1279 @code{@var{branch}} will always differ from
1280 @code{origin/@var{branch}}. In this case, remember that other
1281 people working like you with the remote branch @code{@var{branch}}
1282 of git://git.sv.gnu.org/lilypond.git/ (called
1283 @code{origin/@var{branch}} on your local repository) know nothing
1284 about your own @code{@var{branch}}: this means that whenever you
1285 use a committish or make a patch, others expect you to take the
1286 latest commit of @code{origin/@var{branch}} as a reference.
1288 Finally, please remember to read the man page of every Git command
1289 you will find in this manual in case you want to discover
1290 alternate methods or just understand how it works.
1293 @node Resolving conflicts
1294 @subsection Resolving conflicts
1297 Occasionally an update may result in conflicts -- this happens
1298 when you and somebody else have modified the same part of the same
1299 file and git cannot figure out how to merge the two versions
1300 together. When this happens, you must manually merge the two
1303 If you need some documentation to understand and resolve
1304 conflicts, see paragraphs @emph{How conflicts are presented} and
1305 @emph{How to resolve conflicts} in @command{git merge} man page.
1307 If all else fails, you can follow the instructions in
1308 @ref{Reverting all local changes}. Be aware that this eliminates
1309 any changes you have made!
1312 @node Reverting all local changes
1313 @subsection Reverting all local changes
1315 Sometimes git will become hopelessly confused, and you just want
1316 to get back to a known, stable state. This command destroys any
1317 local changes you have made, but at least you get back to the
1318 current online version:
1321 git reset --hard origin/master
1325 @node Working with remote branches
1326 @subsection Working with remote branches
1329 @subsubheading Fetching new branches from git.sv.gnu.org
1331 To fetch and check out a new branch named @code{@var{branch}} on
1332 git.sv.gnu.org, run from top of the Git repository
1335 git config --add remote.origin.fetch \
1336 +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
1338 git checkout --track -b @var{branch} origin/@var{branch}
1341 After this, you can pull @code{@var{branch}} from git.sv.gnu.org
1348 Note that this command generally fetches all branches you added
1349 with @command{git@tie{}remote@tie{}add} (when you initialized the
1350 repository) or @command{git@tie{}config@tie{}--add}, i.e. it
1351 updates all remote branches from remote @code{origin}, then it
1352 merges the remote branch tracked by the current branch into the
1353 current branch. For example, if your current branch is
1354 @code{master}, @code{origin/master} will be merged into
1358 @subsubheading Local clones, or having several working trees
1360 If you play with several Git branches, e.g. @code{master},
1361 @code{lilypond/translation}, @code{stable/2.12}), you may want to
1362 have one source and build tree for each branch; this is possible
1363 with subdirectories of your local Git repository, used as local
1364 cloned subrepositories. To create a local clone for the branch
1365 named @code{@var{branch}}, run
1368 git checkout @var{branch}
1369 git clone -lsn . @var{subdir}
1374 Note that @code{@var{subdir}} must be a directory name which does
1375 not already exist. In @code{@var{subdir}}, you can use all Git
1376 commands to browse revisions history, commit and uncommit changes;
1377 to update the cloned subrepository with changes made on the main
1378 repository, cd into @code{@var{subdir}} and run
1379 @command{git@tie{}pull}; to send changes made on the subrepository
1380 back to the main repository, run @command{git@tie{}push} from
1381 @code{@var{subdir}}. Note that only one branch (the currently
1382 checked out branch) is created in the subrepository by default; it
1383 is possible to have several branches in a subrepository and do
1384 usual operations (checkout, merge, create, delete...) on these
1385 branches, but this possibility is not detailed here.
1387 When you push @code{@var{branch}} from @code{@var{subdir}} to the
1388 main repository, and @code{@var{branch}} is checked out in the
1389 main repository, you must save uncommitted changes (see
1390 @command{git@tie{}stash}) and do
1391 @command{git@tie{}reset@tie{}--hard} in the main repository in
1392 order to apply pushed changes in the working tree of the main
1400 The commands above don't only bring you the latest version of the
1401 sources, but also the full history of revisions (revisions, also
1402 called commits, are changes made to the sources), stored in the
1403 @file{.git} directory. You can browse this history with
1406 git log # only shows the logs (author, committish and commit message)
1407 git log -p # also shows diffs
1408 gitk # shows history graphically
1411 @warning{The @code{gitk} command may require a separate
1412 @code{gitk} package, available in the appropriate distribution's
1416 @node Applying remote patches
1417 @subsection Applying remote patches
1420 TODO: Explain how to determine if a patch was created with
1421 @code{git@tie{}format-patch}.
1423 Well-formed git patches created with @code{git@tie{}format-patch}
1424 should be committed with the following command:
1430 Patches created without @code{git@tie{}format-patch} can be
1431 applied in two steps. The first step is to apply the patch to the
1435 git apply @var{patch}
1439 The second step is to commit the changes and give credit to the
1440 author of the patch. This can be done with the following command:
1443 git commit -a --author="@var{John Smith} <@var{john@@example.com}>"
1447 @node Sending and receiving patches via email
1448 @subsection Sending and receiving patches via email
1451 The default @code{x-diff} MIME type associated with patch files
1452 (i.e., files whose name ends in @code{.patch}) means that the
1453 encoding of line endings may be changed from UNIX to DOS format
1454 when they are sent as attachments. Attempting to apply such an
1455 inadvertently altered patch will cause git to fail with a message
1456 about @q{whitespace errors}.
1458 The solution to such problems is surprisingly simple---just change
1459 the default file extension of patches generated by git to end in
1460 @code{.txt}, for example:
1463 git config format.suffix '.patch.txt'
1466 This should cause email programs to apply the correct base64
1467 encoding to attached patches.
1469 If you receive a patch with DOS instead of UNIX line-endings, it
1470 can be converted back using the @code{dos2unix} utility.
1472 Lots of useful information on email complications with patches is
1473 provided on the Wine wiki at
1474 @uref{http://wiki.winehq.org/GitWine}.
1478 @subsection Commit access
1481 Most contributors are not able to commit patches directly to the
1482 main repository---only members of the LilyPond development team
1483 have @emph{commit access}. If you are a contributor and are
1484 interested in joining the development team, contact the Project
1485 Manager through the mailing list
1486 (@email{lilypond-devel@@gnu.org}). Generally, only contributors
1487 who have already provided a number of patches which have been
1488 pushed to the main repository will be considered for membership.
1490 If you have been approved by the Project Manager, use the
1491 following procedure to obtain commit access:
1495 If you don't already have one, set up a Savannah user account at
1496 @uref{https://savannah.gnu.org/account/register.php}. If your web
1497 browser responds with an @qq{untrusted connection} message when
1498 you visit the link, follow the steps for including the CAcert root
1499 certificate in your browser, given at
1500 @uref{http://savannah.gnu.org/tls/tutorial/}.
1504 After registering, if you are not logged in automatically, login
1505 at @uref{https://savannah.gnu.org/account/login.php}---this should
1506 take you to your @qq{my} page
1507 (@uref{https://savannah.gnu.org/my/}).
1511 Click on the @qq{My Groups} link to access the @qq{My Group
1512 Membership} page. From there, find the @qq{Request for Inclusion}
1513 box and search for @qq{LilyPond}. Among the search results, check
1514 the box labeled @qq{GNU LilyPond Music Typesetter} and write a
1515 brief (required) message for the Project Manager (@qq{Hey it's
1516 me!} should be fine).
1518 Note that you will not have commit access until the Project
1519 Manager activates your membership. Once your membership is
1520 activated, LilyPond should appear under the heading @qq{Groups I'm
1521 Contributor of} on your @qq{My Group Membership} page.
1525 Generate an SSH @q{dsa} key pair. Enter the following at the
1532 When prompted for a location to save the key, press <ENTER> to
1533 accept the default location (@file{~/.ssh/id_dsa}).
1535 Next you are asked to enter an optional passphrase. On most
1536 systems, if you use a passphrase, you will likely be prompted for
1537 it every time you use @command{git@tie{}push} or
1538 @command{git@tie{}pull}. You may prefer this since it can protect
1539 you from your own mistakes (like pushing when you mean to pull),
1540 though you may find it tedious to keep re-entering it.
1542 You can change/enable/disable your passphrase at any time with:
1545 ssh-keygen -f ~/.ssh/id_dsa -p
1548 Note that the GNOME desktop has a feature which stores your
1549 passphrase for you for an entire GNOME session. If you use a
1550 passphrase to @qq{protect you from yourself}, you will want to
1551 disable this feature, since you'll only be prompted once. Run the
1552 following command, then logout of GNOME and log back in:
1555 gconftool-2 --set -t bool \
1556 /apps/gnome-keyring/daemon-components/ssh false
1559 After setting up your passphrase, your private key is saved as
1560 @file{~/.ssh/id_dsa} and your public key is saved as
1561 @file{~/.ssh/id_dsa.pub}.
1565 Register your public SSH @q{dsa} key with Savannah. From the
1566 @qq{My Account Configuration} page, click on @qq{Edit SSH Keys},
1567 then paste the contents of your @file{~/.ssh/id_dsa.pub} file into
1568 one of the @qq{Authorized keys} text fields, and click
1571 Savannah should respond with something like:
1574 Success: Key #1 seen Keys registered
1579 Configure Git to use the SSH protocol (instead of the GIT
1580 protocol). From your local Git repository, enter:
1583 git config remote.origin.url \
1584 ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1588 where @var{user} is your username on Savannah.
1592 After your membership has been activated and you've configured Git
1593 to use SSH, test the connection with:
1599 SSH should issue the following warning:
1602 The authenticity of host 'git.sv.gnu.org (140.186.70.72)' can't
1604 RSA key fingerprint is
1605 80:5a:b0:0c:ec:93:66:29:49:7e:04:2b:fd:ba:2c:d5.
1606 Are you sure you want to continue connecting (yes/no)?
1609 Make sure the RSA key fingerprint displayed matches the one above.
1610 If it doesn't, respond @qq{no} and check that you configured Git
1611 properly in the previous step. If it does match, respond
1612 @qq{yes}. SSH should then issue another warning:
1615 Warning: Permanently added 'git.sv.gnu.org,140.186.70.72' (RSA) to
1616 the list of known hosts.
1619 The list of known hosts is stored in the file
1620 @file{~/.ssh/known_hosts}.
1622 At this point, you are prompted for your passphrase if you have
1623 one, then Git will attempt a pull.
1625 If @command{git@tie{}pull@tie{}--verbose} fails, you should see
1626 error messages like these:
1629 Permission denied (publickey).
1630 fatal: The remote end hung up unexpectedly
1633 If you get the above error, you may have made a mistake when
1634 registering your SSH key at Savannah. If the key is properly
1635 registered, you probably just need to wait for the Savannah server
1636 to activate it. It usually takes a few minutes for the key to be
1637 active after registering it, but if it still doesn't work after an
1638 hour, ask for help on the mailing list.
1640 If @command{git@tie{}pull@tie{}--verbose} succeeds, the output
1641 will include a @q{From} line that shows @q{ssh} as the protocol:
1644 From ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond
1647 If the protocol shown is not @q{ssh}, check that you configured
1648 Git properly in the previous step.
1652 Test your commit access with a dry run:
1655 git push --dry-run --verbose
1658 Note that recent versions of Git (Git 1.6.3 or later) will issue a
1659 big warning if the above command is used. The simplest solution
1660 is to tell Git to push all matching branches by default:
1663 git config push.default matching
1667 Then @code{git@tie{}push} should work as before. For more
1668 details, consult the @code{git@tie{}push} man page.
1672 @subsubheading Technical details
1676 On Firefox, to view or remove the CAcert root certificate, go to:
1677 Edit > Preferences > Advanced > Encryption > View Certificates >
1678 Authorities > Certificate Name > Root CA > CA Cert Signing
1682 The @command{git@tie{}config} commands above should modify your
1683 local repository's @file{.git/config} file. These lines:
1687 url = git://git.sv.gnu.org/lilypond.git/
1691 should now be changed to:
1695 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1699 where @var{user} is your login name on Savannah.
1703 @command{git@tie{}config@tie{}push.default@tie{}matching} command
1704 should add these lines to @file{.git/config}:
1713 Encryption protocols, including ssh, generally do not permit packet
1714 fragmentation to avoid introducing a point of insecurity. This
1715 means that the maximum packet size must not exceed the smallest
1716 MTU (Maximum Transmission Unit) set in the routers along the path.
1717 This smallest MTU is determined by a procedure during call set-up
1718 which relies on the transmission over the path of ICMP packets.
1719 If any of the routers in the path block ICMP packets this mechanism
1720 fails, resulting in the possibility of packets being transmitted
1721 which exceed the MTU of one of the routers. If this happens the
1722 packet is discarded, causing the ssh session to hang, timeout or
1723 terminate with the error message
1726 ssh: connect to host <host ip addr> port 22: Bad file number
1727 fatal: The remote end hung up unexpectedly
1730 depending on precisely when in the proceedings the first large
1731 packet is transmitted. Most routers on the internet have MTU
1732 set to 1500, but routers installed in homes to connect via
1733 broadband may use a slightly smaller MTU for efficient transmission
1734 over ATM. If this problem is encountered a possible work-around is
1735 to set the MTU in the local router to 1500.
1737 @node Git on Windows
1738 @section Git on Windows
1740 @c Some of this may duplicate stuff in other sections
1741 @c But it is probably best for windows users to have it all together
1742 @c If necessary, clear this up later -td
1744 TODO: Decide what to do with this... Pare it down? Move
1745 paragraphs next to analogous Unix instructions? -mp
1747 @subsection Background to nomenclature
1749 Git is a system for tracking the changes made to source files by a
1750 distributed set of editors. It is designed to work without a
1751 master repository, but we have chosen to have a master repository
1752 for LilyPond files. Editors hold a local copy of the master
1753 repository together with any changes they have made locally.
1754 Local changes are held in a local @q{branch}, of which there may
1755 be several, but these instructions assume you are using just one.
1756 The files visible in the local repository always correspond to
1757 those on the currently @q{checked out} local branch.
1759 Files are edited on a local branch, and in that state the changes
1760 are said to be @q{unstaged}. When editing is complete, the
1761 changes are moved to being @q{staged for commit}, and finally the
1762 changes are @q{committed} to the local branch. Once committed,
1763 the changes (called a @q{commit}) are given a unique 40-digit
1764 hexadecimal reference number called the @q{Committish} or @q{SHA1
1765 ID} which identifies the commit to Git. Such committed changes
1766 can be sent to the master repository by @q{pushing} them (if you
1767 have write permission) or by sending them by email to someone who
1768 has, either as a complete file or as a @q{diff} or @q{patch}
1769 (which send just the differences from the master repository).
1771 @subsection Installing git
1774 @uref{http://code.google.com/p/msysgit/downloads/list} (note, not
1775 msysGit, which is for Git developers and not PortableGit, which is
1776 not a full git installation) and install it.
1778 Note that most users will not need to install SSH. That is not
1779 required until you have been granted direct push permissions to
1780 the master git repository.
1782 Start Git by clicking on the desktop icon. This will bring up a
1783 command line bash shell. This may be unfamiliar to Windows users.
1784 If so, follow these instructions carefully. Commands are entered
1785 at a $ prompt and are terminated by keying a newline.
1787 @subsection Initialising Git
1789 Decide where you wish to place your local Git repository, creating
1790 the folders in Windows as necessary. Here we call the folder to
1791 contain the repository @code{[path]/Git}, but if you intend using
1792 Git for other projects a directory name like @code{lilypond-git}
1793 might be better. You will need to have space for around
1796 Start the Git bash shell by clicking on the desk-top icon
1797 installed with Git and type
1803 to position the shell at your new Git repository.
1805 Note: if [path] contains folders with names containing spaces use
1817 to initialize your Git repository.
1819 Then type (all on one line; the shell will wrap automatically)
1822 git remote add -ft master origin git://git.sv.gnu.org/lilypond.git
1825 to download the lilypond master files.
1827 @warning{Be patient! Even on a broadband connection this can take
1828 10 minutes or more. Wait for lots of [new tag] messages and the $
1831 We now need to generate a local copy of the downloaded files in a
1832 new local branch. Your local branch needs to have a name. It is
1833 usual to call it @q{master} and we shall do that here.
1838 git checkout -b master origin/master
1841 This creates a second branch called @q{master}. You will see two
1842 warnings (ignore these), and a message advising you that your
1843 local branch @q{master} has been set up to track the remote
1844 branch. You now have two branches, a local branch called
1845 @q{master}, and a tracking branch called @q{origin/master}, which
1846 is a shortened form of @q{remotes/origin/master}.
1848 Return to Windows Explorer and look in your Git repository. You
1849 should see lots of folders. For example, the LilyPond
1850 documentation can be found in [path]/Git/Documentation/.
1852 The Git bash shell is terminated by typing @code{exit} or by
1853 clicking on the usual Windows close-window widget.
1857 Almost all subsequent work will use the Git Graphical User
1858 Interface, which avoids having to type command line commands. To
1859 start Git GUI first start the Git bash shell by clicking on the
1860 desktop icon, and type
1867 The Git GUI will open in a new window. It contains four panels
1868 and 7 pull-down menus. At this stage do not use any of the
1869 commands under Branch, Commit, Merge or Remote. These will be
1872 The top panel on the left contains the names of files which you
1873 are in the process of editing (Unstaged Changes), and the lower
1874 panel on the left contains the names of files you have finished
1875 editing and have staged ready for committing (Staged Changes). At
1876 present, these panels will be empty as you have not yet made any
1877 changes to any file. After a file has been edited and saved the
1878 top panel on the right will display the differences between the
1879 edited file selected in one of the panels on the left and the last
1880 version committed on the current branch.
1882 The panel at bottom right is used to enter a descriptive message
1883 about the change before committing it.
1885 The Git GUI is terminated by entering CNTL-Q while it is the
1886 active window or by clicking on the usual Windows close-window
1889 @subsection Personalising your local git repository
1891 Open the Git GUI, click on
1897 and enter your name and email address in the left-hand (Git
1898 Repository) panel. Leave everything else unchanged and save it.
1900 Note that Windows users must leave the default setting for line
1901 endings unchanged. All files in a git repository must have lines
1902 terminated by just a LF, as this is required for Merge to work,
1903 but Windows files are terminated by CRLF by default. The git
1904 default setting causes the line endings of files in a Windows git
1905 repository to be flipped automatically between LF and CRLF as
1906 required. This enables files to be edited by any Windows editor
1907 without causing problems in the git repository.
1909 @subsection Checking out a branch
1911 At this stage you have two branches in your local repository,
1912 both identical. To see them click on
1918 You should have one local branch called @q{master} and one
1919 tracking branch called @q{origin/master}. The latter is your
1920 local copy of the @q{remotes/origin/master} branch in the master
1921 LilyPond repository. The local @q{master} branch is where you
1922 will make your local changes.
1924 When a particular branch is selected, i.e., checked out, the files
1925 visible in your repository are changed to reflect the state of the
1926 files on that branch.
1928 @subsection Updating files from @q{remote/origin/master}
1930 Before starting the editing of a file, ensure your local
1931 repository contains the latest version of the files in the remote
1932 repository by first clicking
1935 Remote -> Fetch from -> origin
1941 This will place the latest version of every file, including all
1942 the changes made by others, into the @q{origin/master} branch of
1943 the tracking branches in your git repository. You can see these
1944 files by checking out this branch, but you must @emph{never} edit
1945 any files while this branch is checked out. Check out your local
1946 @q{master} branch again.
1948 You then need to merge these fetched files into your local
1949 @q{master} branch by clicking on
1952 Merge -> Local Merge
1956 and if necessary select the local @q{master} branch.
1958 Note that a merge cannot be completed if you have made any local
1959 changes which have not yet been committed.
1961 This merge will update all the files in the @q{master} branch to
1962 reflect the current state of the @q{origin/master} branch. If any
1963 of the changes conflict with changes you have made yourself
1964 recently you will be notified of the conflict (see below).
1966 @subsection Editing files
1968 First ensure your @q{master} branch is checked out, then simply
1969 edit the files in your local Git repository with your favourite
1970 editor and save them back there. If any file contains non-ASCII
1971 characters ensure you save it in UTF-8 format. Git will detect
1972 any changes whenever you restart Git GUI and the file names will
1973 then be listed in the Unstaged Changes panel. Or you can click
1974 the Rescan button to refresh the panel contents at any time. You
1975 may break off and resume editing any time.
1977 The changes you have made may be displayed in diff form in the top
1978 right-hand panel of Git GUI by clicking on the file name shown in
1979 one of the left panels.
1981 When your editing is complete, move the files from being Unstaged
1982 to Staged by clicking the document symbol to the left of each
1983 name. If you change your mind it can be moved back by clicking on
1984 the ticked box to the left of the name.
1986 Finally the changes you have made may be committed to your
1987 @q{master} branch by entering a brief message in the Commit
1988 Message box and clicking the Commit button.
1990 If you wish to amend your changes after a commit has been made,
1991 the original version and the changes you made in that commit may
1992 be recovered by selecting
1995 Commit -> Amend Last Commit
1999 or by checking the Amend Last Commit radio button at bottom right.
2000 This will return the changes to the Staged state, so further
2001 editing made be carried out within that commit. This must only be
2002 done @emph{before} the changes have been Pushed or sent to your
2003 mentor for Pushing - after that it is too late and corrections
2004 have to be made as a separate commit.
2007 @subsection Sending changes to @q{remotes/origin/master}
2009 If you do not have write access to @q{remotes/origin/master} you
2010 will need to send your changes by email to someone who does.
2012 First you need to create a diff or patch file containing your
2013 changes. To create this, the file must first be committed. Then
2014 terminate the Git GUI. In the git bash shell first cd to your Git
2021 if necessary, then produce the patch with
2024 git format-patch origin
2027 This will create a patch file for all the locally committed files
2028 which differ from @q{origin/master}. The patch file can be found
2029 in [path]/Git and will have a name formed from the commit message.
2031 @subsection Resolving merge conflicts
2033 As soon as you have committed a changed file your local
2034 @code{master} branch has diverged from @code{origin/master}, and
2035 will remain diverged until your changes have been committed in
2036 @code{remotes/origin/master} and Fetched back into your
2037 @code{origin/master} branch. Similarly, if a new commit has been
2038 made to @code{remotes/origin/master} by someone else and Fetched,
2039 your local @code{master} branch is divergent. You can detect a
2040 divergent branch by clicking on
2043 Repository -> Visualise all branch history
2046 This opens up a very useful new window called @q{gitk}. Use this
2047 to browse all the commits made by yourself and others.
2049 If the diagram at top left of the resulting window does not show
2050 your @code{master} tag on the same node as the
2051 @code{remotes/origin/master} tag your branch has diverged from
2052 @code{origin/master}. This is quite normal if files you have
2053 modified yourself have not yet been Pushed to
2054 @code{remotes/origin/master} and Fetched, or if files modified and
2055 committed by others have been Fetched since you last Merged
2056 @code{origin/master} into your local @code{master} branch.
2058 If a file being merged from @code{origin/master} differs from one
2059 you have modified in a way that cannot be resolved automatically
2060 by git, Merge will report a Conflict which you must resolve by
2061 editing the file to create the version you wish to keep.
2063 This could happen if the person updating
2064 @code{remotes/origin/master} for you has added some changes of his
2065 own before committing your changes to
2066 @code{remotes/origin/master}, or if someone else has changed the
2067 same file since you last fetched the file from
2068 @code{remotes/origin/master}.
2070 Open the file in your editor and look for sections which are
2073 [to be completed when I next have a merge conflict to be sure I
2074 give the right instructions -td]
2077 @subsection Other actions
2079 The instructions above describe the simplest way of using git on
2080 Windows. Other git facilities which may usefully supplement these
2084 @item Using multiple local branches (Create, Rename, Delete)
2085 @item Resetting branches
2086 @item Cherry-picking commits
2087 @item Pushing commits to @w{remote/origin/master}
2088 @item Using gitk to review history
2091 Once familiarity with using git on Windows has been gained the
2092 standard git manuals can be used to learn about these.
2095 @node Repository directory structure
2096 @section Repository directory structure
2099 @c TODO: integrate the roadmap better
2100 @verbatiminclude ROADMAP
2103 @node Other Git documentation
2104 @section Other Git documentation
2108 Official git man pages:
2109 @uref{http://www.kernel.org/pub/software/scm/git/docs/}
2112 More in-depth tutorials: @uref{http://git-scm.com/documentation}
2115 Book about git: @uref{http://progit.org/,Pro Git}