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}.
71 @subsubheading Other operating music systems
75 If you haven't already, download and install Git.
80 Lilybuntu users: git has already been installed for you.
82 @item Windows users: download the @code{.exe} file labeled
83 @qq{Full installer for official Git} from:
86 @uref{http://code.google.com/p/msysgit/downloads/list}
89 @item Other operating systems: either install @command{git} with
90 your package manager, or download it from the @qq{Binaries}
94 @uref{http://git-scm.com/download}
101 Download the @command{lily-git.tcl} script from:
103 @c don't change the cgit link below to gitweb; gitweb uses
104 @c long filenames like "scripts_auxiliar_lily-git.tcl"
107 @uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
111 To run the program from the command line, navigate to the
112 directory containing @command{lily-git.tcl} and enter:
119 Go read the lilybuntu instructions, starting from the @qq{get
124 @advanced{the @qq{Get source} button does not fetch the entire
125 history of the git repository, so utilities like @command{gitk}
126 will only be able to display the most recent additions. As you
127 continue to work with @command{lily-git.tcl}, the @qq{Update
128 source} button will take any new additions and add it to whatever
129 is currently in your repository's history.}
132 @node Daily use of lily-git.tcl
133 @unnumberedsubsec Daily use of @command{lily-git.tcl}
135 @warning{Only work on one set of changes at once. Do not start
136 work on any new changes until your first set has been accepted.}
138 @subsubheading 1. Update source
140 At the beginning of each session of lilypond work, you should
141 click the @qq{Update source} button to get the latest changes to
144 @warning{In some rare and unfortunate circumstances, this will
145 result in a @emph{merge conflict}. If this occurs, follow the
146 instructions for @qq{Abort changes}, below. Your work will not be
150 @subsubheading 2a. New local commit
152 A single commit typically represents one logical set of related
153 changes (such as a bug-fix), and may incorporate changes to
154 multiple files at the same time.
156 When you're finished making the changes for a commit, click the
157 @qq{New local commit} button. This will open the @qq{Git Commit
158 Message} window. The message header is required, and the message
161 After entering a commit message, click @qq{OK} to finalize the
164 @advanced{for more information regarding commits and commit
165 messages, see @ref{Commits and patches}.}
168 @subsubheading 2b. Amend previous commit
170 You can go back and make changes to the most recent commit with
171 the @qq{Amend previous commit} button. This is useful if a
172 mistake is found after you have clicked the @qq{New local commit}
175 To amend the most recent commit, re-edit the source files as
176 needed and then click the @qq{Amend previous commit} button. The
177 earlier version of the commit is not saved, but is replaced by the
180 @warning{This does not update the patch @strong{files}; if you
181 have a patch file from an earlier version of the commit, you will
182 need to make another patch set when using this feature. The old
183 patch file will not be saved, but will be replaced by the new one
184 after you click on @qq{Make patch set}.}
187 @subsubheading 3. Make patch set
189 Before making a patch set from any commits, you should click the
190 @qq{Update source} button to make sure the commits are based on
191 the most recent remote snapshot.
193 When you click the @qq{Make patch set} button,
194 @command{lily-git.tcl} will produce patch files for any new
195 commits, saving them to the current directory. The command output
196 will display the name of the new patch files near the end of the
200 0001-CG-add-lily-git-instructions.patch
204 Send patch files to the appropriate place:
208 If you have a mentor, send it to them via email.
211 New contributors should send the patch attached to an email to
212 @email{frogs@@lilynet.net}. Please add @qq{[PATCH]} to the
216 Translators should send patches to
217 @email{translations@@lilynet.net}.
220 More experienced contributors should upload the patch for
221 web-based review. This requires additional software and use of
222 the command-line; see @ref{Uploading a patch for review}.
227 @subsubheading The @qq{Abort changes -- Reset to origin} button
229 @warning{Only use this if your local commit history gets
230 hopelessly confused!}
232 The button labeled @qq{Abort changes -- Reset to origin} will copy
233 all changed files to a subdirectory of @file{lilypond-git/} named
234 @file{aborted_edits/}, and will reset the repository to the
235 current state of the remote repository (at @code{git.sv.gnu.org}).
238 @node Starting with Git
239 @section Starting with Git
242 Using the Git program directly (as opposed to using the
243 @command{lily-git.tcl} GUI) allows you to have much greater control
244 over the contributing process. You should consider using Git if
245 you want to work on complex projects, or if you want to work on
246 multiple projects concurrently.
251 * Downloading remote branches::
256 @subsection Setting up
259 TODO: Remove this note if incorporating Windows instructions
260 throughout this section:
262 @warning{These instructions assume that you are using the
263 command-line version of Git 1.5 or higher. Windows users should
264 skip to @ref{Git on Windows}.}
268 * Initializing a repository::
274 @unnumberedsubsubsec Installing Git
277 If you are using a Unix-based machine, the easiest way to download
278 and install Git is through a package manager such as @command{rpm}
279 or @command{apt-get}---the installation is generally automatic.
280 The only required package is (usually) called @command{git-core},
281 although some of the auxiliary @command{git@var{*}} packages are
282 also useful (such as @command{gitk}).
284 Alternatively, you can visit the Git website
285 (@uref{http://git-scm.com/}) for downloadable binaries and
288 TODO: add Windows installation instructions (or @@ref@{Git on
292 @node Initializing a repository
293 @unnumberedsubsubsec Initializing a repository
296 Once Git is installed, you'll need to create a new directory where
297 your initial repository will be stored (the example below uses
298 @file{~/lilypond-git/}, where @code{~} represents your home
299 directory). Run @command{git@tie{}init} from within the new
300 directory to initialize an empty repository:
303 mkdir ~/lilypond-git/; cd ~/lilypond-git/
307 @subsubheading Technical details
309 This creates (within the @file{~/lilypond-git/} directory) a
310 subdirectory called @file{.git/}, which Git uses to keep track of
311 changes to the repository, among other things. Normally you don't
312 need to access it, but it's good to know it's there.
315 @node Configuring Git
316 @unnumberedsubsubsec Configuring Git
318 @warning{Throughout the rest of this manual, all command-line
319 input should be entered from the top directory of the Git
320 repository being discussed (eg. @file{~/lilypond-git/}). This is
321 referred to as a @emph{top source directory}.}
323 Before downloading a copy of the main LilyPond repository, you
324 should configure some basic settings with the
325 @command{git@tie{}config} command. Git allows you to set both
326 global and repository-specific options.
328 To configure settings that affect all repositories, use the
329 @command{--global} command line option. For example, the first
330 two options that you should always set are your @var{name} and
331 @var{email}, since Git needs these to keep track of commit
335 git config --global user.name "@var{John Smith}"
336 git config --global user.email @var{john@@example.com}
339 To configure Git to use colored output where possible, use:
342 git config --global color.ui auto
345 The text editor that opens when using @command{git@tie{}commit}
346 can also be changed. If none of your editor-related environment
347 variables are set ($GIT_EDITOR, $VISUAL, or $EDITOR), the default
348 editor is usually @command{vi} or @command{vim}. If you're not
349 familiar with either of these, you should probably change the
350 default to an editor that you know how to use. For example, to
351 change the default editor to @command{nano}, enter:
354 git config --global core.editor @var{nano}
357 TODO: Add instructions for changing the editor on Windows, which
358 is a little different, I think. -mp
360 @subsubheading Technical details
362 Git stores the information entered with
363 @command{git@tie{}config@tie{}--global} in the file
364 @file{.gitconfig}, located in your home directory. This file can
365 also be modified directly, without using
366 @command{git@tie{}config}. The @file{.gitconfig} file generated
367 by the above commands would look like this:
372 email = john@@example.com
379 Using the @command{git@tie{}config} command @emph{without} the
380 @command{--global} option configures repository-specific settings,
381 which are stored in the file @file{.git/config}. This file is
382 created when a repository is initialized (using
383 @command{git@tie{}init}), and by default contains these lines:
387 repositoryformatversion = 0
390 logallrefupdates = true
393 However, since different repository-specific options are
394 recommended for different development tasks, it is best to avoid
395 setting any now. Specific recommendations will be mentioned later
399 @node Downloading remote branches
400 @subsection Downloading remote branches
404 * Organization of remote branches::
405 * LilyPond repository sources::
406 * Downloading individual branches::
407 * Downloading all remote branches::
412 @node Organization of remote branches
413 @unnumberedsubsubsec Organization of remote branches
416 The main LilyPond repository is organized into @emph{branches} to
417 facilitate development. These are often called @emph{remote}
418 branches to distinguish them from @emph{local} branches you might
419 create yourself (see @ref{Using local branches}).
421 The @code{master} branch contains all the source files used to
422 build LilyPond, which includes the program itself (both stable and
423 development releases), the documentation (and its translations),
424 and the website. Generally, the @code{master} branch is expected
425 to compile successfully.
427 The @code{lilypond/translation} branch is a side branch that
428 allows translators to work without needing to worry about
429 compilation problems. Periodically, the Translation Meister
430 (after verifying that it doesn't break compilation), will
431 @emph{merge} this branch back into @code{master} to incorporate
432 recent translations. Similarly, the @code{master} branch is
433 usually merged into the @code{lilypond/translation} branch after
434 significant changes to the English documentation. See
435 @ref{Translating the documentation} for details.
438 @node LilyPond repository sources
439 @unnumberedsubsubsec LilyPond repository sources
442 The recommended source for downloading a copy of the main
446 git://git.sv.gnu.org/lilypond.git
449 However, if your internet router filters out connections using the
450 GIT protocol, or if you experience difficulty connecting via GIT,
451 you can try these other sources:
454 ssh://git.sv.gnu.org/srv/git/lilypond.git
455 http://git.sv.gnu.org/r/lilypond.git
458 The SSH protocol can only be used if your system is properly set
459 up to use it. Also, the HTTP protocol is slowest, so it should
460 only be used as a last resort.
463 @node Downloading individual branches
464 @unnumberedsubsubsec Downloading individual branches
467 Once you have initialized an empty Git repository on your system
468 (see @ref{Initializing a repository}), you can download a remote
469 branch into it. Make sure you know which branch you want to start
472 To download the @code{master} branch, enter the following:
475 git remote add -ft master -m master \
476 origin git://git.sv.gnu.org/lilypond.git/
479 To download the @code{lilypond/translation} branch, enter:
482 git remote add -ft lilypond/translation -m \
483 lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
486 The @command{git@tie{}remote@tie{}add} process could take up to
487 ten minutes, depending on the speed of your connection. The
488 output will be something like this:
492 remote: Counting objects: 235967, done.
493 remote: Compressing objects: 100% (42721/42721), done.
494 remote: Total 235967 (delta 195098), reused 233311 (delta 192772)
495 Receiving objects: 100% (235967/235967), 68.37 MiB | 479 KiB/s, done.
496 Resolving deltas: 100% (195098/195098), done.
497 From git://git.sv.gnu.org/lilypond
498 * [new branch] master -> origin/master
499 From git://git.sv.gnu.org/lilypond
500 * [new tag] flower/1.0.1 -> flower/1.0.1
501 * [new tag] flower/1.0.10 -> flower/1.0.10
503 * [new tag] release/2.9.6 -> release/2.9.6
504 * [new tag] release/2.9.7 -> release/2.9.7
507 When @command{git@tie{}remote@tie{}add} is finished, the remote
508 branch should be downloaded into your repository---though not yet
509 in a form that you can use. In order to browse the source code
510 files, you need to @emph{create} and @emph{checkout} your own
511 local branch. In this case, however, it is easier to have Git
512 create the branch automatically by using the @command{checkout}
513 command on a non-existent branch. Enter the following:
516 git checkout -b @var{branch} origin/@var{branch}
520 where @code{@var{branch}} is the name of your tracking branch,
521 either @code{master} or @code{lilypond/translation}.
523 Git will issue some warnings; this is normal:
526 warning: You appear to be on a branch yet to be born.
527 warning: Forcing checkout of origin/master.
528 Branch master set up to track remote branch master from origin.
532 By now the source files should be accessible---you should be able
533 to edit any files in the @file{lilypond-git/} directory using a
534 text editor of your choice. But don't start just yet! Before
535 editing any source files, learn how to keep your changes organized
536 and prevent problems later---read @ref{Basic Git procedures}.
538 @subsubheading Technical Details
540 The @command{git@tie{}remote@tie{}add} command should add some
541 lines to your local repository's @file{.git/config} file:
545 url = git://git.sv.gnu.org/lilypond.git/
546 fetch = +refs/heads/master:refs/remotes/origin/master
550 @node Downloading all remote branches
551 @unnumberedsubsubsec Downloading all remote branches
554 To download all remote branches at once, you can @command{clone}
555 the entire repository:
558 git clone git://git.sv.gnu.org/lilypond.git
563 @unnumberedsubsubsec Other branches
565 Most contributors will never need to touch the other branches. If
566 you wish to do so, you will need more familiarity with Git; please
567 see @ref{Other Git documentation}.
570 @item @code{dev/XYZ}:
571 These branches are for individual developers. They store code
572 which is not yet stable enough to be added to the @code{master}
575 @item @code{stable/XYZ}:
576 The branches are kept for archival reasons.
580 Another item of interest might be the Grand Unified Builder, our
581 cross-platform building tool. Since it is used by projects as
582 well, it is not stored in our gub repository. For more info, see
583 @uref{http://lilypond.org/gub}. The git location is
584 @uref{http://github.com/janneke/gub}.
587 @node Basic Git procedures
588 @section Basic Git procedures
592 * The Git contributor's cycle::
593 * Pulling and rebasing::
594 * Using local branches::
595 * Commits and patches::
599 @node The Git contributor's cycle
600 @subsection The Git contributor's cycle
603 Here is a simplified view of the contribution process on Git:
607 Update your local repository by @emph{pulling} the most recent
608 updates from the remote repository.
611 Edit source files within your local repository's @emph{working
615 @emph{Commit} the changes you've made to a local @emph{branch}.
618 Generate a @emph{patch} to share your changes with the developers.
622 @node Pulling and rebasing
623 @subsection Pulling and rebasing
626 When developers push new patches to the @code{git.sv.gnu.org}
627 repository, your local repository is @strong{not} automatically
628 updated. It is important to keep your repository up-to-date by
629 periodically @emph{pulling} the most recent @emph{commits} from
630 the remote branch. Developers expect patches to be as current as
631 possible, since outdated patches require extra work before they
634 Occasionally you may need to rework some of your own modifications
635 to match changes made to the remote branch (see @ref{Resolving
636 conflicts}), and it's considerably easier to rework things
637 incrementally. If you don't update your repository along the way,
638 you may have to spend a lot of time resolving branch conflicts and
639 reconfiguring much of the work you've already done.
641 Fortunately, Git is able to resolve certain types of branch
642 conflicts automatically with a process called @emph{rebasing}.
643 When rebasing, Git tries to modify your old commits so they appear
644 as new commits (based on the latest updates). For a more involved
645 explanation, see the @command{git-rebase} man page.
647 To pull without rebasing (recommended for translators), use the
651 git pull # recommended for translators
654 If you're tracking the remote @code{master} branch, you should add
655 the @code{-r} option (short for @code{--rebase}) to keep commits
656 on your local branch current:
659 git pull -r # use with caution when translating
662 If you don't edit translated documentation and don't want to type
663 @code{-r} every time, configure the master branch to rebase by
664 default with this command:
667 git config branch.master.rebase true
670 If pull fails because of a message like
673 error: Your local changes to 'Documentation/learning/tutorial.itely'
674 would be overwritten by merge. Aborting.
681 Documentation/learning/tutorial.itely: needs update
682 refusing to pull with rebase: your working tree is not up-to-date
686 it means that you have modified some files in you working tree
687 without committing changes (see @ref{Commits and patches}); you
688 can use the @command{git@tie{}stash} command to work around this:
691 git stash # save uncommitted changes
692 git pull -r # pull using rebase (translators omit "-r")
693 git stash pop # reapply previously saved changes
696 Note that @command{git@tie{}stash@tie{}pop} will try to apply a
697 patch, and this may create a conflict. If this happens, see
698 @ref{Resolving conflicts}.
700 TODO: I think the next paragraph is confusing. Perhaps prepare
701 the reader for new terms `committish' and `head'? -mp
703 @warning{translators and documentation editors, if you have
704 changed committishes in the head of translated files using commits
705 you have not yet pushed to @code{git.sv.gnu.org}, please do not
706 rebase. If you want to avoid wondering whether you should rebase
707 each time you pull, please always use committishes from master
708 and/or lilypond/translation branch on @code{git.sv.gnu.org}, which
709 in particular implies that you must push your changes to
710 documentation except committishes updates (possibly after having
711 rebased), then update the committishes and push them.}
713 TODO: when committishes automatic conditional update have been
714 tested and documented, append the following to the warning above:
715 Note that using update-committishes make target generally touches
718 @subsubheading Technical details
720 The @command{git@tie{}config} command mentioned above adds the
721 line @code{rebase = true} to the master branch in your local
722 repository's @file{.git/config} file:
727 merge = refs/heads/master
732 @node Using local branches
733 @subsection Using local branches
737 * Creating and removing branches::
738 * Listing branches and remotes::
739 * Checking out branches::
744 @node Creating and removing branches
745 @unnumberedsubsubsec Creating and removing branches
748 Local branches are useful when you're working on several different
749 projects concurrently. To create a new branch, enter:
752 git branch @var{name}
755 To delete a branch, enter:
758 git branch -d @var{name}
761 Git will ask you for confirmation if it sees that data would be
762 lost by deleting the branch. Use @code{-D} instead of @code{-d}
763 to bypass this. Note that you cannot delete a branch if it is
764 currently checked out.
767 @node Listing branches and remotes
768 @unnumberedsubsubsec Listing branches and remotes
770 You can get the exact path or URL of all remote branches by
777 To list Git branches on your local repositories, run
780 git branch # list local branches only
781 git branch -r # list remote branches
782 git branch -a # list all branches
786 @node Checking out branches
787 @unnumberedsubsubsec Checking out branches
789 To know the currently checked out branch, i.e. the branch whose
790 source files are present in your working tree, read the first line
798 The currently checked out branch is also marked with an asterisk
799 in the output of @command{git branch}.
801 You can check out another branch @code{@var{other_branch}}, i.e.
802 check out @code{@var{other_branch}} to the working tree, by
806 git checkout @var{other_branch}
809 Note that it is possible to check out another branch while having
810 uncommitted changes, but it is not recommended unless you know
811 what you are doing; it is recommended to run @command{git status}
812 to check this kind of issue before checking out another branch.
814 @node Merging branches
815 @unnumberedsubsubsec Merging branches
817 To merge branch @code{@var{foo}} into branch @code{@var{bar}},
818 i.e. to @qq{add} all changes made in branch @code{@var{foo}} to
819 branch @code{@var{bar}}, run
822 git checkout @var{bar}
826 If any conflict happens, see @ref{Resolving conflicts}.
828 There are common usage cases for merging: as a translator, you
829 will often want to merge @code{master} into
830 @code{lilypond/translation}; on the other hand, the Translations
831 meister wants to merge @code{lilypond/translation} into
832 @code{master} whenever he has checked that
833 @code{lilypond/translation} builds successfully.
836 @node Commits and patches
837 @subsection Commits and patches
841 * Understanding commits::
845 * Uploading a patch for review::
849 @node Understanding commits
850 @unnumberedsubsubsec Understanding commits
852 Technically, a @emph{commit} is a single point in the history of a
853 branch, but most developers use the term to mean a @emph{commit
854 object}, which stores information about a particular revision. A
855 single commit can record changes to multiple source files, and
856 typically represents one logical set of related changes (such as a
857 bug-fix). You can list the ten most recent commits in your
858 current branch with this command:
861 git log -10 --oneline
864 If you're using an older version of Git and get an @q{unrecognized
865 argument} error, use this instead:
868 git log -10 --pretty=oneline --abbrev-commit
871 More interactive lists of the commits on the remote @code{master}
872 branch are available at
873 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=shortlog} and
874 @uref{http://git.sv.gnu.org/cgit/lilypond.git/log/}.
878 @unnumberedsubsubsec Making commits
881 Once you have modified some source files in your working
882 directory, you can make a commit with the following procedure:
886 Make sure you've configured Git properly (see @ref{Configuring
887 Git}). Check that your changes meet the requirements described in
888 @ref{Code style} and/or @ref{Documentation policy}. For advanced
889 edits, you may also want to verify that the changes don't break
890 the compilation process.
893 Run the following command:
900 to make sure you're on the right branch, and to see which files
901 have been modified, added or removed, etc. You may need to tell
902 Git about any files you've added by running one of these:
905 git add @var{file} # add untracked @var{file} individually
906 git add . # add all untracked files in current directory
910 After @command{git@tie{}add}, run @command{git@tie{}status} again
911 to make sure you got everything. You may also need to modify
915 Preview the changes about to be committed (to make sure everything
923 The @code{HEAD} argument refers to the most recent commit on the
924 currently checked-out branch.
927 Generate the commit with:
934 The @code{-a} is short for @code{--all} which includes modified
935 and deleted files, but only those newly created files that have
936 previously been added.
941 @node Commit messages
942 @unnumberedsubsubsec Commit messages
945 When you run the @command{git@tie{}commit@tie{}-a} command, Git
946 automatically opens the default text editor so you can enter a
947 @emph{commit message}. If you find yourself in a foreign editing
948 environment, you're probably in @command{vi} or @command{vim}. If
949 you want to switch to an editor you're more familiar with, quit by
950 typing @code{:q!} and pressing @code{<Enter>}. See
951 @ref{Configuring Git} for instructions on changing the default
954 In any case, Git will open a text file for your commit message
955 that looks like this:
959 # Please enter the commit message for your changes. Lines starting
960 # with '#' will be ignored, and an empty message aborts the commit.
962 # Changes to be committed:
963 # (use "git reset HEAD <file>..." to unstage)
965 # modified: working.itexi
969 Your commit message should begin with a one-line summary
970 describing the change (no more than 50 characters long), and if
971 necessary a blank line followed by several lines giving the
974 @c $ git log -1 --pretty=medium 4d6f1e5
976 Doc: add Baerenreiter and Henle solo cello suites
978 Added comparison of solo cello suite engravings to new essay with
979 high-res images, fixed cropping on Finale example.
982 Commit messages often start with a short prefix describing the
983 general location of the changes. If a commit affects the
984 documentation in English (or in several languages simultaneously)
985 the commit message should be prefixed with @qq{Doc:@tie{}}. If
986 the commit affects only one of the translations, the commit
987 message should be prefixed with @qq{Doc-@var{**}:@tie{}}, where
988 @var{**} is the two-letter language code. Commits that affect the
989 website should use @qq{Web:@tie{}} for English, and
990 @qq{Web-@var{**}:@tie{}} for the other languages. Also, changes
991 to a single file are often prefixed with the name of the file
992 involved. Visit the links listed in @ref{Understanding commits}
997 @unnumberedsubsubsec Making patches
999 If you want to share your changes with other contributors and
1000 developers, you need to generate @emph{patches} from your commits.
1001 We prefer it if you follow the instructions in
1002 @ref{Uploading a patch for review}. However, we present an
1003 alternate method here.
1005 You should always run @command{git@tie{}pull@tie{}-r} (translators
1006 should leave off the @code{-r}) before doing this to ensure that
1007 your patches are as current as possible.
1009 Once you have made one or more commits in your local repository,
1010 and pulled the most recent commits from the remote branch, you can
1011 generate patches from your local commits with the command:
1014 git format-patch origin
1017 The @code{origin} argument refers to the remote tracking branch at
1018 @code{git.sv.gnu.org}. This command generates a separate patch
1019 for each commit that's in the current branch but not in the remote
1020 branch. Patches are placed in the current working directory and
1021 will have names that look something like this:
1024 0001-Doc-Fix-typos.patch
1025 0002-Web-Remove-dead-links.patch
1029 Send an email (must be less than 64 KB) to
1030 @email{lilypond-devel@@gnu.org} briefly explaining your work, with
1031 the patch files attached. Translators should send patches to
1032 @email{translations@@lilynet.net}. After your patches are
1033 reviewed, the developers may push one or more of them to the main
1034 repository or discuss them with you.
1037 @node Uploading a patch for review
1038 @unnumberedsubsubsec Uploading a patch for review
1040 Any non-trivial change should be uploaded to our @qq{Rietveld}
1041 code review website:
1044 @uref{http://codereview.appspot.com/}
1047 @subsubheading Initial setup
1052 You must have a gmail account.
1055 Install @command{git-cl} by entering:
1058 git clone git://neugierig.org/git-cl.git
1062 Add the @file{git-cl/} directory to your PATH, or create a
1063 symbolic link to the @command{git-cl} and @command{upload.py}
1064 scripts in one of your PATH directories (such as
1069 Move into the top source directory and then configure
1070 @command{git cl}. If you do not understand any question, just
1071 answer with a newline (CR).
1074 cd $HOME/lilypond-git/
1078 The @qq{CC list} question should be answered with:
1081 lilypond-devel@@gnu.org
1086 @subsubheading Uploading patch set
1088 @warning{Unless you are familiar with branches, only work on one
1089 set of changes at once.}
1091 There are two methods, depending on your git setup.
1095 @strong{Master branch}: (easy option, and used in @command{lily-git.tcl})
1097 If you added your patch to @code{master}, then:
1101 git cl upload origin/master
1104 If you have git push ability, make sure that you @emph{remove}
1105 your patch (with @command{git rebase} or @command{git reset})
1106 before pushing other stuff.
1109 @strong{Separate branch}: (complicated option)
1111 Ensure your changes are committed in a separate branch, which
1112 should differ from the reference branch to be used by just the
1113 changes to be uploaded. If the reference branch is to be
1114 origin/master, ensure this is up-to-date. If necessary, use git
1115 rebase to rebase the branch containing the changes to the head of
1116 origin/master. Finally, check out branch with the changes and
1120 git cl upload <reference SHA1 ID>
1124 where <reference SHA1 ID> is the SHA1 ID of the commit to be used
1125 as a reference source for the patch. Generally, this will be the
1126 SHA1 ID of origin/master, and in that case the command:
1129 git cl upload origin/master
1137 After prompting for your Google email address and password, the
1138 patch set will be posted to Rietveld, and you will be given a URL
1141 @subsubheading Announcing your patch set
1143 You should then announce the patch by logging into the code review
1144 issue webpage and using @qq{Publish + Mail Comments} to add a
1145 (mostly bogus) comment to your issue. The text of your comment
1146 will be sent to our developer mailing list.
1148 @subsubheading Revisions
1150 As revisions are made in response to comments, successive patch sets
1151 for the same issue can be uploaded by reissuing the git-cl command
1152 with the modified branch checked out.
1154 Sometimes in response to comments on revisions, the best way to
1155 work may require creation of a new branch in git. In order to
1156 associate the new branch with an existing Rietveld issue,
1157 the following command can be used:
1160 git cl issue issue-number
1164 where @code{issue-number} is the number of the existing Rietveld
1167 @subsubheading Resetting git cl
1169 If @command{git cl} becomes confused, you can @qq{reset} it by
1177 @node Advanced Git procedures
1178 @section Advanced Git procedures
1181 @warning{This section is not necessary for normal contributors;
1182 these commands are presented for information for people interested
1183 in learning more about git.}
1185 It is possible to work with several branches on the same local Git
1186 repository; this is especially useful for translators who may have
1187 to deal with both @code{lilypond/translation} and a stable branch,
1188 e.g. @code{stable/2.12}.
1190 Some Git commands are introduced first, then a workflow with
1191 several Git branches of LilyPond source code is presented.
1195 * Advanced Git concepts::
1196 * Resolving conflicts::
1197 * Reverting all local changes::
1198 * Working with remote branches::
1200 * Applying remote patches::
1201 * Sending and receiving patches via email::
1206 @node Advanced Git concepts
1207 @subsection Advanced Git concepts
1210 A bit of Git vocabulary will be explained below. The following is
1211 only introductory; for a better understanding of Git concepts, you
1212 may wish to read @ref{Other Git documentation}.
1214 The @code{git@tie{}pull@tie{}origin} command above is just a
1215 shortcut for this command:
1218 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
1222 where @code{@var{branch}} is typically @code{master} or
1223 @code{lilypond/translation}; if you do not know or remember, see
1224 @ref{Downloading remote branches} to remember which commands you
1225 issued or which source code you wanted to get.
1227 A @emph{commit} is a set of changes made to the sources; it also
1228 includes the committish of the parent commit, the name and e-mail
1229 of the @emph{author} (the person who wrote the changes), the name
1230 and e-mail of the @emph{committer} (the person who brings these
1231 changes into the Git repository), and a commit message.
1233 A @emph{committish} is the SHA1 checksum of a commit, a number
1234 made of 40 hexadecimal digits, which acts as the internal unique
1235 identifier for this commit. To refer to a particular revision,
1236 don't use vague references like the (approximative) date, simply
1237 copy and paste the committish.
1239 A @emph{branch} is nothing more than a pointer to a particular
1240 commit, which is called the @emph{head} of the branch; when
1241 referring to a branch, one often actually thinks about its head
1242 and the ancestor commits of the head.
1244 Now we will explain the two last commands you used to get the
1245 source code from Git---see @ref{Downloading individual branches}.
1248 git remote add -ft @var{branch} -m @var{branch} \
1249 origin git://git.sv.gnu.org/lilypond.git/
1251 git checkout -b @var{branch} origin/@var{branch}
1254 The @command{git@tie{}remote} has created a branch called
1255 @code{origin/@var{branch}} in your local Git repository. As this
1256 branch is a copy of the remote branch web from git.sv.gnu.org
1257 LilyPond repository, it is called a @emph{remote branch}, and is
1258 meant to track the changes on the branch from git.sv.gnu.org: it
1259 will be updated every time you run
1260 @command{git@tie{}pull@tie{}origin} or
1261 @command{git@tie{}fetch@tie{}origin}.
1263 The @command{git@tie{}checkout} command has created a branch named
1264 @code{@var{branch}}. At the beginning, this branch is identical
1265 to @code{origin/@var{branch}}, but it will differ as soon as you
1266 make changes, e.g. adding newly translated pages or editing some
1267 documentation or code source file. Whenever you pull, you merge
1268 the changes from @code{origin/@var{branch}} and
1269 @code{@var{branch}} since the last pulling. If you do not have
1270 push (i.e. @qq{write}) access on git.sv.gnu.org, your
1271 @code{@var{branch}} will always differ from
1272 @code{origin/@var{branch}}. In this case, remember that other
1273 people working like you with the remote branch @code{@var{branch}}
1274 of git://git.sv.gnu.org/lilypond.git/ (called
1275 @code{origin/@var{branch}} on your local repository) know nothing
1276 about your own @code{@var{branch}}: this means that whenever you
1277 use a committish or make a patch, others expect you to take the
1278 latest commit of @code{origin/@var{branch}} as a reference.
1280 Finally, please remember to read the man page of every Git command
1281 you will find in this manual in case you want to discover
1282 alternate methods or just understand how it works.
1285 @node Resolving conflicts
1286 @subsection Resolving conflicts
1289 Occasionally an update may result in conflicts -- this happens
1290 when you and somebody else have modified the same part of the same
1291 file and git cannot figure out how to merge the two versions
1292 together. When this happens, you must manually merge the two
1295 If you need some documentation to understand and resolve
1296 conflicts, see paragraphs @emph{How conflicts are presented} and
1297 @emph{How to resolve conflicts} in @command{git merge} man page.
1299 If all else fails, you can follow the instructions in
1300 @ref{Reverting all local changes}. Be aware that this eliminates
1301 any changes you have made!
1304 @node Reverting all local changes
1305 @subsection Reverting all local changes
1307 Sometimes git will become hopelessly confused, and you just want
1308 to get back to a known, stable state. This command destroys any
1309 local changes you have made, but at least you get back to the
1310 current online version:
1313 git reset --hard origin/master
1317 @node Working with remote branches
1318 @subsection Working with remote branches
1321 @subsubheading Fetching new branches from git.sv.gnu.org
1323 To fetch and check out a new branch named @code{@var{branch}} on
1324 git.sv.gnu.org, run from top of the Git repository
1327 git config --add remote.origin.fetch \
1328 +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
1330 git checkout --track -b @var{branch} origin/@var{branch}
1333 After this, you can pull @code{@var{branch}} from git.sv.gnu.org
1340 Note that this command generally fetches all branches you added
1341 with @command{git@tie{}remote@tie{}add} (when you initialized the
1342 repository) or @command{git@tie{}config@tie{}--add}, i.e. it
1343 updates all remote branches from remote @code{origin}, then it
1344 merges the remote branch tracked by the current branch into the
1345 current branch. For example, if your current branch is
1346 @code{master}, @code{origin/master} will be merged into
1350 @subsubheading Local clones, or having several working trees
1352 If you play with several Git branches, e.g. @code{master},
1353 @code{lilypond/translation}, @code{stable/2.12}), you may want to
1354 have one source and build tree for each branch; this is possible
1355 with subdirectories of your local Git repository, used as local
1356 cloned subrepositories. To create a local clone for the branch
1357 named @code{@var{branch}}, run
1360 git checkout @var{branch}
1361 git clone -lsn . @var{subdir}
1366 Note that @code{@var{subdir}} must be a directory name which does
1367 not already exist. In @code{@var{subdir}}, you can use all Git
1368 commands to browse revisions history, commit and uncommit changes;
1369 to update the cloned subrepository with changes made on the main
1370 repository, cd into @code{@var{subdir}} and run
1371 @command{git@tie{}pull}; to send changes made on the subrepository
1372 back to the main repository, run @command{git@tie{}push} from
1373 @code{@var{subdir}}. Note that only one branch (the currently
1374 checked out branch) is created in the subrepository by default; it
1375 is possible to have several branches in a subrepository and do
1376 usual operations (checkout, merge, create, delete...) on these
1377 branches, but this possibility is not detailed here.
1379 When you push @code{@var{branch}} from @code{@var{subdir}} to the
1380 main repository, and @code{@var{branch}} is checked out in the
1381 main repository, you must save uncommitted changes (see
1382 @command{git@tie{}stash}) and do
1383 @command{git@tie{}reset@tie{}--hard} in the main repository in
1384 order to apply pushed changes in the working tree of the main
1392 The commands above don't only bring you the latest version of the
1393 sources, but also the full history of revisions (revisions, also
1394 called commits, are changes made to the sources), stored in the
1395 @file{.git} directory. You can browse this history with
1398 git log # only shows the logs (author, committish and commit message)
1399 git log -p # also shows diffs
1400 gitk # shows history graphically
1403 @warning{The @code{gitk} command may require a separate
1404 @code{gitk} package, available in the appropriate distribution's
1408 @node Applying remote patches
1409 @subsection Applying remote patches
1412 TODO: Explain how to determine if a patch was created with
1413 @code{git@tie{}format-patch}.
1415 Well-formed git patches created with @code{git@tie{}format-patch}
1416 should be committed with the following command:
1422 Patches created without @code{git@tie{}format-patch} can be
1423 applied in two steps. The first step is to apply the patch to the
1427 git apply @var{patch}
1431 The second step is to commit the changes and give credit to the
1432 author of the patch. This can be done with the following command:
1435 git commit -a --author="@var{John Smith} <@var{john@@example.com}>"
1439 @node Sending and receiving patches via email
1440 @subsection Sending and receiving patches via email
1443 The default @code{x-diff} MIME type associated with patch files
1444 (i.e., files whose name ends in @code{.patch}) means that the
1445 encoding of line endings may be changed from UNIX to DOS format
1446 when they are sent as attachments. Attempting to apply such an
1447 inadvertently altered patch will cause git to fail with a message
1448 about @q{whitespace errors}.
1450 The solution to such problems is surprisingly simple---just change
1451 the default file extension of patches generated by git to end in
1452 @code{.txt}, for example:
1455 git config format.suffix '.patch.txt'
1458 This should cause email programs to apply the correct base64
1459 encoding to attached patches.
1461 If you receive a patch with DOS instead of UNIX line-endings, it
1462 can be converted back using the @code{dos2unix} utility.
1464 Lots of useful information on email complications with patches is
1465 provided on the Wine wiki at
1466 @uref{http://wiki.winehq.org/GitWine}.
1470 @subsection Commit access
1473 Most contributors are not able to commit patches directly to the
1474 main repository---only members of the LilyPond development team
1475 have @emph{commit access}. If you are a contributor and are
1476 interested in joining the development team, contact the Project
1477 Manager through the mailing list
1478 (@email{lilypond-devel@@gnu.org}). Generally, only contributors
1479 who have already provided a number of patches which have been
1480 pushed to the main repository will be considered for membership.
1482 If you have been approved by the Project Manager, use the
1483 following procedure to obtain commit access:
1487 If you don't already have one, set up a Savannah user account at
1488 @uref{https://savannah.gnu.org/account/register.php}. If your web
1489 browser responds with an @qq{untrusted connection} message when
1490 you visit the link, follow the steps for including the CAcert root
1491 certificate in your browser, given at
1492 @uref{http://savannah.gnu.org/tls/tutorial/}.
1496 After registering, if you are not logged in automatically, login
1497 at @uref{https://savannah.gnu.org/account/login.php}---this should
1498 take you to your @qq{my} page
1499 (@uref{https://savannah.gnu.org/my/}).
1503 Click on the @qq{My Groups} link to access the @qq{My Group
1504 Membership} page. From there, find the @qq{Request for Inclusion}
1505 box and search for @qq{LilyPond}. Among the search results, check
1506 the box labeled @qq{GNU LilyPond Music Typesetter} and write a
1507 brief (required) message for the Project Manager (@qq{Hey it's
1508 me!} should be fine).
1510 Note that you will not have commit access until the Project
1511 Manager activates your membership. Once your membership is
1512 activated, LilyPond should appear under the heading @qq{Groups I'm
1513 Contributor of} on your @qq{My Group Membership} page.
1517 Generate an SSH @q{dsa} key pair. Enter the following at the
1524 When prompted for a location to save the key, press <ENTER> to
1525 accept the default location (@file{~/.ssh/id_dsa}).
1527 Next you are asked to enter an optional passphrase. On most
1528 systems, if you use a passphrase, you will likely be prompted for
1529 it every time you use @command{git@tie{}push} or
1530 @command{git@tie{}pull}. You may prefer this since it can protect
1531 you from your own mistakes (like pushing when you mean to pull),
1532 though you may find it tedious to keep re-entering it.
1534 You can change/enable/disable your passphrase at any time with:
1537 ssh-keygen -f ~/.ssh/id_dsa -p
1540 Note that the GNOME desktop has a feature which stores your
1541 passphrase for you for an entire GNOME session. If you use a
1542 passphrase to @qq{protect you from yourself}, you will want to
1543 disable this feature, since you'll only be prompted once. Run the
1544 following command, then logout of GNOME and log back in:
1547 gconftool-2 --set -t bool \
1548 /apps/gnome-keyring/daemon-components/ssh false
1551 After setting up your passphrase, your private key is saved as
1552 @file{~/.ssh/id_dsa} and your public key is saved as
1553 @file{~/.ssh/id_dsa.pub}.
1557 Register your public SSH @q{dsa} key with Savannah. From the
1558 @qq{My Account Configuration} page, click on @qq{Edit SSH Keys},
1559 then paste the contents of your @file{~/.ssh/id_dsa.pub} file into
1560 one of the @qq{Authorized keys} text fields, and click
1563 Savannah should respond with something like:
1566 Success: Key #1 seen Keys registered
1571 Configure Git to use the SSH protocol (instead of the GIT
1572 protocol). From your local Git repository, enter:
1575 git config remote.origin.url \
1576 ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1580 where @var{user} is your username on Savannah.
1584 After your membership has been activated and you've configured Git
1585 to use SSH, test the connection with:
1591 SSH should issue the following warning:
1594 The authenticity of host 'git.sv.gnu.org (140.186.70.72)' can't
1596 RSA key fingerprint is
1597 80:5a:b0:0c:ec:93:66:29:49:7e:04:2b:fd:ba:2c:d5.
1598 Are you sure you want to continue connecting (yes/no)?
1601 Make sure the RSA key fingerprint displayed matches the one above.
1602 If it doesn't, respond @qq{no} and check that you configured Git
1603 properly in the previous step. If it does match, respond
1604 @qq{yes}. SSH should then issue another warning:
1607 Warning: Permanently added 'git.sv.gnu.org,140.186.70.72' (RSA) to
1608 the list of known hosts.
1611 The list of known hosts is stored in the file
1612 @file{~/.ssh/known_hosts}.
1614 At this point, you are prompted for your passphrase if you have
1615 one, then Git will attempt a pull.
1617 If @command{git@tie{}pull@tie{}--verbose} fails, you should see
1618 error messages like these:
1621 Permission denied (publickey).
1622 fatal: The remote end hung up unexpectedly
1625 If you get the above error, you may have made a mistake when
1626 registering your SSH key at Savannah. If the key is properly
1627 registered, you probably just need to wait for the Savannah server
1628 to activate it. It usually takes a few minutes for the key to be
1629 active after registering it, but if it still doesn't work after an
1630 hour, ask for help on the mailing list.
1632 If @command{git@tie{}pull@tie{}--verbose} succeeds, the output
1633 will include a @q{From} line that shows @q{ssh} as the protocol:
1636 From ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond
1639 If the protocol shown is not @q{ssh}, check that you configured
1640 Git properly in the previous step.
1644 Test your commit access with a dry run:
1647 git push --dry-run --verbose
1650 Note that recent versions of Git (Git 1.6.3 or later) will issue a
1651 big warning if the above command is used. The simplest solution
1652 is to tell Git to push all matching branches by default:
1655 git config push.default matching
1659 Then @code{git@tie{}push} should work as before. For more
1660 details, consult the @code{git@tie{}push} man page.
1664 @subsubheading Technical details
1668 On Firefox, to view or remove the CAcert root certificate, go to:
1669 Edit > Preferences > Advanced > Encryption > View Certificates >
1670 Authorities > Certificate Name > Root CA > CA Cert Signing
1674 The @command{git@tie{}config} commands above should modify your
1675 local repository's @file{.git/config} file. These lines:
1679 url = git://git.sv.gnu.org/lilypond.git/
1683 should now be changed to:
1687 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1691 where @var{user} is your login name on Savannah.
1695 @command{git@tie{}config@tie{}push.default@tie{}matching} command
1696 should add these lines to @file{.git/config}:
1705 Encryption protocols, including ssh, generally do not permit packet
1706 fragmentation to avoid introducing a point of insecurity. This
1707 means that the maximum packet size must not exceed the smallest
1708 MTU (Maximum Transmission Unit) set in the routers along the path.
1709 This smallest MTU is determined by a procedure during call set-up
1710 which relies on the transmission over the path of ICMP packets.
1711 If any of the routers in the path block ICMP packets this mechanism
1712 fails, resulting in the possibility of packets being transmitted
1713 which exceed the MTU of one of the routers. If this happens the
1714 packet is discarded, causing the ssh session to hang, timeout or
1715 terminate with the error message
1718 ssh: connect to host <host ip addr> port 22: Bad file number
1719 fatal: The remote end hung up unexpectedly
1722 depending on precisely when in the proceedings the first large
1723 packet is transmitted. Most routers on the internet have MTU
1724 set to 1500, but routers installed in homes to connect via
1725 broadband may use a slightly smaller MTU for efficient transmission
1726 over ATM. If this problem is encountered a possible work-around is
1727 to set the MTU in the local router to 1500.
1729 @node Git on Windows
1730 @section Git on Windows
1732 @c Some of this may duplicate stuff in other sections
1733 @c But it is probably best for windows users to have it all together
1734 @c If necessary, clear this up later -td
1736 TODO: Decide what to do with this... Pare it down? Move
1737 paragraphs next to analogous Unix instructions? -mp
1739 @subsection Background to nomenclature
1741 Git is a system for tracking the changes made to source files by a
1742 distributed set of editors. It is designed to work without a
1743 master repository, but we have chosen to have a master repository
1744 for LilyPond files. Editors hold a local copy of the master
1745 repository together with any changes they have made locally.
1746 Local changes are held in a local @q{branch}, of which there may
1747 be several, but these instructions assume you are using just one.
1748 The files visible in the local repository always correspond to
1749 those on the currently @q{checked out} local branch.
1751 Files are edited on a local branch, and in that state the changes
1752 are said to be @q{unstaged}. When editing is complete, the
1753 changes are moved to being @q{staged for commit}, and finally the
1754 changes are @q{committed} to the local branch. Once committed,
1755 the changes (called a @q{commit}) are given a unique 40-digit
1756 hexadecimal reference number called the @q{Committish} or @q{SHA1
1757 ID} which identifies the commit to Git. Such committed changes
1758 can be sent to the master repository by @q{pushing} them (if you
1759 have write permission) or by sending them by email to someone who
1760 has, either as a complete file or as a @q{diff} or @q{patch}
1761 (which send just the differences from the master repository).
1763 @subsection Installing git
1766 @uref{http://code.google.com/p/msysgit/downloads/list} (note, not
1767 msysGit, which is for Git developers and not PortableGit, which is
1768 not a full git installation) and install it.
1770 Note that most users will not need to install SSH. That is not
1771 required until you have been granted direct push permissions to
1772 the master git repository.
1774 Start Git by clicking on the desktop icon. This will bring up a
1775 command line bash shell. This may be unfamiliar to Windows users.
1776 If so, follow these instructions carefully. Commands are entered
1777 at a $ prompt and are terminated by keying a newline.
1779 @subsection Initialising Git
1781 Decide where you wish to place your local Git repository, creating
1782 the folders in Windows as necessary. Here we call the folder to
1783 contain the repository @code{[path]/Git}, but if you intend using
1784 Git for other projects a directory name like @code{lilypond-git}
1785 might be better. You will need to have space for around
1788 Start the Git bash shell by clicking on the desk-top icon
1789 installed with Git and type
1795 to position the shell at your new Git repository.
1797 Note: if [path] contains folders with names containing spaces use
1809 to initialize your Git repository.
1811 Then type (all on one line; the shell will wrap automatically)
1814 git remote add -ft master origin git://git.sv.gnu.org/lilypond.git
1817 to download the lilypond master files.
1819 @warning{Be patient! Even on a broadband connection this can take
1820 10 minutes or more. Wait for lots of [new tag] messages and the $
1823 We now need to generate a local copy of the downloaded files in a
1824 new local branch. Your local branch needs to have a name. It is
1825 usual to call it @q{master} and we shall do that here.
1830 git checkout -b master origin/master
1833 This creates a second branch called @q{master}. You will see two
1834 warnings (ignore these), and a message advising you that your
1835 local branch @q{master} has been set up to track the remote
1836 branch. You now have two branches, a local branch called
1837 @q{master}, and a tracking branch called @q{origin/master}, which
1838 is a shortened form of @q{remotes/origin/master}.
1840 Return to Windows Explorer and look in your Git repository. You
1841 should see lots of folders. For example, the LilyPond
1842 documentation can be found in [path]/Git/Documentation/.
1844 The Git bash shell is terminated by typing @code{exit} or by
1845 clicking on the usual Windows close-window widget.
1849 Almost all subsequent work will use the Git Graphical User
1850 Interface, which avoids having to type command line commands. To
1851 start Git GUI first start the Git bash shell by clicking on the
1852 desktop icon, and type
1859 The Git GUI will open in a new window. It contains four panels
1860 and 7 pull-down menus. At this stage do not use any of the
1861 commands under Branch, Commit, Merge or Remote. These will be
1864 The top panel on the left contains the names of files which you
1865 are in the process of editing (Unstaged Changes), and the lower
1866 panel on the left contains the names of files you have finished
1867 editing and have staged ready for committing (Staged Changes). At
1868 present, these panels will be empty as you have not yet made any
1869 changes to any file. After a file has been edited and saved the
1870 top panel on the right will display the differences between the
1871 edited file selected in one of the panels on the left and the last
1872 version committed on the current branch.
1874 The panel at bottom right is used to enter a descriptive message
1875 about the change before committing it.
1877 The Git GUI is terminated by entering CNTL-Q while it is the
1878 active window or by clicking on the usual Windows close-window
1881 @subsection Personalising your local git repository
1883 Open the Git GUI, click on
1889 and enter your name and email address in the left-hand (Git
1890 Repository) panel. Leave everything else unchanged and save it.
1892 Note that Windows users must leave the default setting for line
1893 endings unchanged. All files in a git repository must have lines
1894 terminated by just a LF, as this is required for Merge to work,
1895 but Windows files are terminated by CRLF by default. The git
1896 default setting causes the line endings of files in a Windows git
1897 repository to be flipped automatically between LF and CRLF as
1898 required. This enables files to be edited by any Windows editor
1899 without causing problems in the git repository.
1901 @subsection Checking out a branch
1903 At this stage you have two branches in your local repository,
1904 both identical. To see them click on
1910 You should have one local branch called @q{master} and one
1911 tracking branch called @q{origin/master}. The latter is your
1912 local copy of the @q{remotes/origin/master} branch in the master
1913 LilyPond repository. The local @q{master} branch is where you
1914 will make your local changes.
1916 When a particular branch is selected, i.e., checked out, the files
1917 visible in your repository are changed to reflect the state of the
1918 files on that branch.
1920 @subsection Updating files from @q{remote/origin/master}
1922 Before starting the editing of a file, ensure your local
1923 repository contains the latest version of the files in the remote
1924 repository by first clicking
1927 Remote -> Fetch from -> origin
1933 This will place the latest version of every file, including all
1934 the changes made by others, into the @q{origin/master} branch of
1935 the tracking branches in your git repository. You can see these
1936 files by checking out this branch, but you must @emph{never} edit
1937 any files while this branch is checked out. Check out your local
1938 @q{master} branch again.
1940 You then need to merge these fetched files into your local
1941 @q{master} branch by clicking on
1944 Merge -> Local Merge
1948 and if necessary select the local @q{master} branch.
1950 Note that a merge cannot be completed if you have made any local
1951 changes which have not yet been committed.
1953 This merge will update all the files in the @q{master} branch to
1954 reflect the current state of the @q{origin/master} branch. If any
1955 of the changes conflict with changes you have made yourself
1956 recently you will be notified of the conflict (see below).
1958 @subsection Editing files
1960 First ensure your @q{master} branch is checked out, then simply
1961 edit the files in your local Git repository with your favourite
1962 editor and save them back there. If any file contains non-ASCII
1963 characters ensure you save it in UTF-8 format. Git will detect
1964 any changes whenever you restart Git GUI and the file names will
1965 then be listed in the Unstaged Changes panel. Or you can click
1966 the Rescan button to refresh the panel contents at any time. You
1967 may break off and resume editing any time.
1969 The changes you have made may be displayed in diff form in the top
1970 right-hand panel of Git GUI by clicking on the file name shown in
1971 one of the left panels.
1973 When your editing is complete, move the files from being Unstaged
1974 to Staged by clicking the document symbol to the left of each
1975 name. If you change your mind it can be moved back by clicking on
1976 the ticked box to the left of the name.
1978 Finally the changes you have made may be committed to your
1979 @q{master} branch by entering a brief message in the Commit
1980 Message box and clicking the Commit button.
1982 If you wish to amend your changes after a commit has been made,
1983 the original version and the changes you made in that commit may
1984 be recovered by selecting
1987 Commit -> Amend Last Commit
1991 or by checking the Amend Last Commit radio button at bottom right.
1992 This will return the changes to the Staged state, so further
1993 editing made be carried out within that commit. This must only be
1994 done @emph{before} the changes have been Pushed or sent to your
1995 mentor for Pushing - after that it is too late and corrections
1996 have to be made as a separate commit.
1999 @subsection Sending changes to @q{remotes/origin/master}
2001 If you do not have write access to @q{remotes/origin/master} you
2002 will need to send your changes by email to someone who does.
2004 First you need to create a diff or patch file containing your
2005 changes. To create this, the file must first be committed. Then
2006 terminate the Git GUI. In the git bash shell first cd to your Git
2013 if necessary, then produce the patch with
2016 git format-patch origin
2019 This will create a patch file for all the locally committed files
2020 which differ from @q{origin/master}. The patch file can be found
2021 in [path]/Git and will have a name formed from the commit message.
2023 @subsection Resolving merge conflicts
2025 As soon as you have committed a changed file your local
2026 @code{master} branch has diverged from @code{origin/master}, and
2027 will remain diverged until your changes have been committed in
2028 @code{remotes/origin/master} and Fetched back into your
2029 @code{origin/master} branch. Similarly, if a new commit has been
2030 made to @code{remotes/origin/master} by someone else and Fetched,
2031 your local @code{master} branch is divergent. You can detect a
2032 divergent branch by clicking on
2035 Repository -> Visualise all branch history
2038 This opens up a very useful new window called @q{gitk}. Use this
2039 to browse all the commits made by yourself and others.
2041 If the diagram at top left of the resulting window does not show
2042 your @code{master} tag on the same node as the
2043 @code{remotes/origin/master} tag your branch has diverged from
2044 @code{origin/master}. This is quite normal if files you have
2045 modified yourself have not yet been Pushed to
2046 @code{remotes/origin/master} and Fetched, or if files modified and
2047 committed by others have been Fetched since you last Merged
2048 @code{origin/master} into your local @code{master} branch.
2050 If a file being merged from @code{origin/master} differs from one
2051 you have modified in a way that cannot be resolved automatically
2052 by git, Merge will report a Conflict which you must resolve by
2053 editing the file to create the version you wish to keep.
2055 This could happen if the person updating
2056 @code{remotes/origin/master} for you has added some changes of his
2057 own before committing your changes to
2058 @code{remotes/origin/master}, or if someone else has changed the
2059 same file since you last fetched the file from
2060 @code{remotes/origin/master}.
2062 Open the file in your editor and look for sections which are
2065 [to be completed when I next have a merge conflict to be sure I
2066 give the right instructions -td]
2069 @subsection Other actions
2071 The instructions above describe the simplest way of using git on
2072 Windows. Other git facilities which may usefully supplement these
2076 @item Using multiple local branches (Create, Rename, Delete)
2077 @item Resetting branches
2078 @item Cherry-picking commits
2079 @item Pushing commits to @w{remote/origin/master}
2080 @item Using gitk to review history
2083 Once familiarity with using git on Windows has been gained the
2084 standard git manuals can be used to learn about these.
2087 @node Repository directory structure
2088 @section Repository directory structure
2091 @c TODO: integrate the roadmap better
2092 @verbatiminclude ROADMAP
2095 @node Other Git documentation
2096 @section Other Git documentation
2100 Official git man pages:
2101 @uref{http://www.kernel.org/pub/software/scm/git/docs/}
2104 More in-depth tutorials: @uref{http://git-scm.com/documentation}
2107 Book about git: @uref{http://progit.org/,Pro Git}