1 @c -*- coding: utf-8; mode: texinfo; -*-
4 @node Working with source code
5 @chapter Working with source code
11 * Basic Git procedures::
12 * Advanced Git procedures::
14 * Repository directory structure::
15 * Other Git documentation::
20 @section Using lily-git
23 If you haven't already, download and install Git. Go to
24 @uref{http://git-scm.com/download}, and in the @qq{Binaries}
25 section, select the appropriate package for your operating system.
26 Windows users should visit
27 @uref{http://code.google.com/p/msysgit/downloads/list} and
28 download the @file{.exe} file labeled @qq{Full installer for
31 Download the lily-git script from:
33 @c don't change the cgit link below to gitweb; gitweb uses
34 @c long filenames like "scripts_auxiliar_lily-git.tcl"
37 @uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}.
40 To run the program from the command line, navigate to the
41 directory containing @file{lily-git.tcl} and enter:
48 @subsubheading Get source / Update source
50 When you click the @qq{Get source} button, @command{lily-git} will
51 create a directory called @file{lilypond-git/} within your home
52 directory, and will download the complete source code into that
53 directory (around 55Mb). When the process is finished, the
54 @qq{Command output} window will display @qq{Done}, and the button
55 label will change to say @qq{Update source}.
57 Navigate to the @file{lilypond-git/} directory to view the source
58 files. You should now be able to modify the source files using
59 your normal text editor.
62 @subsubheading New local commit
64 A single commit typically represents one logical set of related
65 changes (such as a bug-fix), and may incorporate changes to
66 multiple files at the same time.
68 When you're finished making the changes for your first commit,
69 click the @qq{New local commit} button. This will open the
70 @qq{Git Commit Message} window. The message header is required,
71 and the message body is optional. See @ref{Commits and patches}
72 for more information regarding commits and commit messages.
74 After entering a commit message, click @qq{OK} to finalize the
78 @subsubheading Amend previous commit
80 You can go back and make changes to the most recent commit with
81 the @qq{Amend previous commit} button. This is useful if a
82 mistake is found after you've clicked the @qq{New local commit}
83 button. To amend the most recent commit, edit the source files as
84 needed and click the button. The earlier version of the commit is
85 not saved, but is replaced by the new one.
87 Note that this does not update patch files; if you have a patch
88 file from an earlier version of the commit, you will need to make
89 another patch set when using this feature. The old patch file is
90 not saved, but is replaced by the new one.
93 @subsubheading Make patch set
95 Before making a patch set from any commits, you should click the
96 @qq{Update source} button to make sure the commits are based on
97 the most recent remote snapshot.
99 When you click the @qq{Make patch set} button, @command{lily-git}
100 will produce patch files for any new commits, saving them to the
101 current directory. The command output will display the name of
102 the new patch files near the end of the output:
105 0001-CG-add-lily-git-instructions.patch
109 Send patch files to your mentor if you have one. Otherwise, write
110 an email to @email{lilypond-devel@@gnu.org} briefly explaining
111 your work, with the patch files attached. Translators should send
112 patches to @email{translations@@lilynet.net}.
115 @subsubheading The @qq{Abort changes -- Reset to origin} button
117 @warning{Only use this if your local commit history gets
118 hopelessly confused!}
120 The button labeled @qq{Abort changes -- Reset to origin} will copy
121 all changed files to a subdirectory of @file{lilypond-git/} named
122 @file{aborted_edits/}, and will reset the repository to the
123 current state of the remote repository (at @code{git.sv.gnu.org}).
126 @node Starting with Git
127 @section Starting with Git
130 Using the Git program directly (as opposed to using the
131 @command{lily-git} GUI) allows you to have much greater control
132 over the contributing process. You should consider using Git if
133 you want to work on complex projects, or if you want to work on
134 multiple projects concurrently.
139 * Downloading remote branches::
144 @subsection Setting up
147 FIXME: Remove this note if incorporating Windows instructions
148 throughout this section:
150 @warning{These instructions assume that you are using the
151 command-line version of Git 1.5 or higher. Windows users should
152 skip to @ref{Git on Windows}.}
156 * Initializing a repository::
162 @unnumberedsubsubsec Installing Git
165 If you are using a Unix-based machine, the easiest way to download
166 and install Git is through a package manager such as @command{rpm}
167 or @command{apt-get}---the installation is generally automatic.
168 The only required package is (usually) called @command{git-core},
169 although some of the auxiliary @command{git@var{*}} packages are
170 also useful (such as @command{gitk}).
172 Alternatively, you can visit the Git website
173 (@uref{http://git-scm.com/}) for downloadable binaries and
176 FIXME: add Windows installation instructions (or @@ref@{Git on
180 @node Initializing a repository
181 @unnumberedsubsubsec Initializing a repository
184 Once Git is installed, you'll need to create a new directory where
185 your initial repository will be stored (the example below uses
186 @file{~/lilypond-git/}, where @code{~} represents your home
187 directory). Run @command{git@tie{}init} from within the new
188 directory to initialize an empty repository:
191 mkdir ~/lilypond-git/; cd ~/lilypond-git/
195 @subsubheading Technical details
197 This creates (within the @file{~/lilypond-git/} directory) a
198 subdirectory called @file{.git/}, which Git uses to keep track of
199 changes to the repository, among other things. Normally you don't
200 need to access it, but it's good to know it's there.
203 @node Configuring Git
204 @unnumberedsubsubsec Configuring Git
206 @warning{Throughout the rest of this manual, all command-line
207 input should be entered from the top directory of the Git
208 repository being discussed (eg. @file{~/lilypond-git/}). This is
209 referred to as a @emph{top source directory}.}
211 Before downloading a copy of the main LilyPond repository, you
212 should configure some basic settings with the
213 @command{git@tie{}config} command. Git allows you to set both
214 global and repository-specific options.
216 To configure settings that affect all repositories, use the
217 @command{--global} command line option. For example, the first
218 two options that you should always set are your @var{name} and
219 @var{email}, since Git needs these to keep track of commit
223 git config --global user.name "@var{John Smith}"
224 git config --global user.email @var{john@@example.com}
227 To configure Git to use colored output where possible, use:
230 git config --global color.ui auto
233 The text editor that opens when using @command{git@tie{}commit}
234 can also be changed. If none of your editor-related environment
235 variables are set ($GIT_EDITOR, $VISUAL, or $EDITOR), the default
236 editor is usually @command{vi} or @command{vim}. If you're not
237 familiar with either of these, you should probably change the
238 default to an editor that you know how to use. For example, to
239 change the default editor to @command{nano}, enter:
242 git config --global core.editor @var{nano}
245 FIXME: Add instructions for changing the editor on Windows, which
246 is a little different, I think. -mp
248 @subsubheading Technical details
250 Git stores the information entered with
251 @command{git@tie{}config@tie{}--global} in the file
252 @file{.gitconfig}, located in your home directory. This file can
253 also be modified directly, without using
254 @command{git@tie{}config}. The @file{.gitconfig} file generated
255 by the above commands would look like this:
260 email = john@@example.com
267 Using the @command{git@tie{}config} command @emph{without} the
268 @command{--global} option configures repository-specific settings,
269 which are stored in the file @file{.git/config}. This file is
270 created when a repository is initialized (using
271 @command{git@tie{}init}), and by default contains these lines:
275 repositoryformatversion = 0
278 logallrefupdates = true
281 However, since different repository-specific options are
282 recommended for different development tasks, it is best to avoid
283 setting any now. Specific recommendations will be mentioned later
287 @node Downloading remote branches
288 @subsection Downloading remote branches
292 * Organization of remote branches::
293 * LilyPond repository sources::
294 * Downloading individual branches::
295 * Downloading all remote branches::
300 @node Organization of remote branches
301 @unnumberedsubsubsec Organization of remote branches
304 The main LilyPond repository is organized into @emph{branches} to
305 facilitate development. These are often called @emph{remote}
306 branches to distinguish them from @emph{local} branches you might
307 create yourself (see @ref{Using local branches}).
309 The @code{master} branch contains all the source files used to
310 build LilyPond, which includes the program itself (both stable and
311 development releases), the documentation (and its translations),
312 and the website. Generally, the @code{master} branch is expected
313 to compile successfully.
315 The @code{lilypond/translation} branch is a side branch that
316 allows translators to work without needing to worry about
317 compilation problems. Periodically, the Translation Meister
318 (after verifying that it doesn't break compilation), will
319 @emph{merge} this branch back into @code{master} to incorporate
320 recent translations. Similarly, the @code{master} branch is
321 usually merged into the @code{lilypond/translation} branch after
322 significant changes to the English documentation. See
323 @ref{Translating the documentation} for details.
326 @node LilyPond repository sources
327 @unnumberedsubsubsec LilyPond repository sources
330 The recommended source for downloading a copy of the main
334 git://git.sv.gnu.org/lilypond.git
337 However, if your internet router filters out connections using the
338 GIT protocol, or if you experience difficulty connecting via GIT,
339 you can try these other sources:
342 ssh://git.sv.gnu.org/srv/git/lilypond.git
343 http://git.sv.gnu.org/r/lilypond.git
346 The SSH protocol can only be used if your system is properly set
347 up to use it. Also, the HTTP protocol is slowest, so it should
348 only be used as a last resort.
351 @node Downloading individual branches
352 @unnumberedsubsubsec Downloading individual branches
355 Once you have initialized an empty Git repository on your system
356 (see @ref{Initializing a repository}), you can download a remote
357 branch into it. Make sure you know which branch you want to start
360 To download the @code{master} branch, enter the following:
363 git remote add -ft master -m master \
364 origin git://git.sv.gnu.org/lilypond.git/
367 To download the @code{lilypond/translation} branch, enter:
370 git remote add -ft lilypond/translation -m \
371 lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
374 The @command{git@tie{}remote@tie{}add} process could take up to
375 ten minutes, depending on the speed of your connection. The
376 output will be something like this:
380 remote: Counting objects: 235967, done.
381 remote: Compressing objects: 100% (42721/42721), done.
382 remote: Total 235967 (delta 195098), reused 233311 (delta 192772)
383 Receiving objects: 100% (235967/235967), 68.37 MiB | 479 KiB/s, done.
384 Resolving deltas: 100% (195098/195098), done.
385 From git://git.sv.gnu.org/lilypond
386 * [new branch] master -> origin/master
387 From git://git.sv.gnu.org/lilypond
388 * [new tag] flower/1.0.1 -> flower/1.0.1
389 * [new tag] flower/1.0.10 -> flower/1.0.10
391 * [new tag] release/2.9.6 -> release/2.9.6
392 * [new tag] release/2.9.7 -> release/2.9.7
395 When @command{git@tie{}remote@tie{}add} is finished, the remote
396 branch should be downloaded into your repository---though not yet
397 in a form that you can use. In order to browse the source code
398 files, you need to @emph{create} and @emph{checkout} your own
399 local branch. In this case, however, it is easier to have Git
400 create the branch automatically by using the @command{checkout}
401 command on a non-existent branch. Enter the following:
404 git checkout -b @var{branch} origin/@var{branch}
408 where @code{@var{branch}} is the name of your tracking branch,
409 either @code{master} or @code{lilypond/translation}.
411 Git will issue some warnings; this is normal:
414 warning: You appear to be on a branch yet to be born.
415 warning: Forcing checkout of origin/master.
416 Branch master set up to track remote branch master from origin.
420 By now the source files should be accessible---you should be able
421 to edit any files in the @file{lilypond-git/} directory using a
422 text editor of your choice. But don't start just yet! Before
423 editing any source files, learn how to keep your changes organized
424 and prevent problems later---read @ref{Basic Git procedures}.
426 @subsubheading Technical Details
428 The @command{git@tie{}remote@tie{}add} command should add some
429 lines to your local repository's @file{.git/config} file:
433 url = git://git.sv.gnu.org/lilypond.git/
434 fetch = +refs/heads/master:refs/remotes/origin/master
438 @node Downloading all remote branches
439 @unnumberedsubsubsec Downloading all remote branches
442 To download all remote branches at once, you can @command{clone}
443 the entire repository:
446 git clone git://git.sv.gnu.org/lilypond.git
451 @unnumberedsubsubsec Other branches
453 Most contributors will never need to touch the other branches. If
454 you wish to do so, you will need more familiarity with Git; please
455 see @ref{Other Git documentation}.
458 @item @code{dev/XYZ}:
459 These branches are for individual developers. They store code
460 which is not yet stable enough to be added to the @code{master}
463 @item @code{stable/XYZ}:
464 The branches are kept for archival reasons.
468 Another item of interest might be the Grand Unified Builder, our
469 cross-platform building tool. Since it is used by projects as
470 well, it is not stored in our gub repository. For more info, see
471 @uref{http://lilypond.org/gub}. The git location is
472 @uref{http://github.com/janneke/gub}.
475 @node Basic Git procedures
476 @section Basic Git procedures
480 * The Git contributor's cycle::
481 * Pulling and rebasing::
482 * Using local branches::
483 * Commits and patches::
487 @node The Git contributor's cycle
488 @subsection The Git contributor's cycle
491 Here is a simplified view of the contribution process on Git:
495 Update your local repository by @emph{pulling} the most recent
496 updates from the remote repository.
499 Edit source files within your local repository's @emph{working
503 @emph{Commit} the changes you've made to a local @emph{branch}.
506 Generate a @emph{patch} to share your changes with the developers.
510 @node Pulling and rebasing
511 @subsection Pulling and rebasing
514 When developers push new patches to the @code{git.sv.gnu.org}
515 repository, your local repository is @strong{not} automatically
516 updated. It is important to keep your repository up-to-date by
517 periodically @emph{pulling} the most recent @emph{commits} from
518 the remote branch. Developers expect patches to be as current as
519 possible, since outdated patches require extra work before they
522 Occasionally you may need to rework some of your own modifications
523 to match changes made to the remote branch (see @ref{Resolving
524 conflicts}), and it's considerably easier to rework things
525 incrementally. If you don't update your repository along the way,
526 you may have to spend a lot of time resolving branch conflicts and
527 reconfiguring much of the work you've already done.
529 Fortunately, Git is able to resolve certain types of branch
530 conflicts automatically with a process called @emph{rebasing}.
531 When rebasing, Git tries to modify your old commits so they appear
532 as new commits (based on the latest updates). For a more involved
533 explanation, see the @command{git-rebase} man page.
535 To pull without rebasing (recommended for translators), use the
539 git pull # recommended for translators
542 If you're tracking the remote @code{master} branch, you should add
543 the @code{-r} option (short for @code{--rebase}) to keep commits
544 on your local branch current:
547 git pull -r # use with caution when translating
550 If you don't edit translated documentation and don't want to type
551 @code{-r} every time, configure the master branch to rebase by
552 default with this command:
555 git config branch.master.rebase true
558 If pull fails because of a message like
561 error: Your local changes to 'Documentation/learning/tutorial.itely'
562 would be overwritten by merge. Aborting.
569 Documentation/learning/tutorial.itely: needs update
570 refusing to pull with rebase: your working tree is not up-to-date
574 it means that you have modified some files in you working tree
575 without committing changes (see @ref{Commits and patches}); you
576 can use the @command{git@tie{}stash} command to work around this:
579 git stash # save uncommitted changes
580 git pull -r # pull using rebase (translators omit "-r")
581 git stash pop # reapply previously saved changes
584 Note that @command{git@tie{}stash@tie{}pop} will try to apply a
585 patch, and this may create a conflict. If this happens, see
586 @ref{Resolving conflicts}.
588 FIXME: I think the next paragraph is confusing. Perhaps prepare
589 the reader for new terms `committish' and `head'? -mp
591 @warning{translators and documentation editors, if you have
592 changed committishes in the head of translated files using commits
593 you have not yet pushed to @code{git.sv.gnu.org}, please do not
594 rebase. If you want to avoid wondering whether you should rebase
595 each time you pull, please always use committishes from master
596 and/or lilypond/translation branch on @code{git.sv.gnu.org}, which
597 in particular implies that you must push your changes to
598 documentation except committishes updates (possibly after having
599 rebased), then update the committishes and push them.}
601 FIXME: when committishes automatic conditional update have been
602 tested and documented, append the following to the warning above:
603 Note that using update-committishes make target generally touches
606 @subsubheading Technical details
608 The @command{git@tie{}config} command mentioned above adds the
609 line @code{rebase = true} to the master branch in your local
610 repository's @file{.git/config} file:
615 merge = refs/heads/master
620 @node Using local branches
621 @subsection Using local branches
625 * Creating and removing branches::
626 * Listing branches and remotes::
627 * Checking out branches::
632 @node Creating and removing branches
633 @unnumberedsubsubsec Creating and removing branches
636 Local branches are useful when you're working on several different
637 projects concurrently. To create a new branch, enter:
640 git branch @var{name}
643 To delete a branch, enter:
646 git branch -d @var{name}
649 Git will ask you for confirmation if it sees that data would be
650 lost by deleting the branch. Use @code{-D} instead of @code{-d}
651 to bypass this. Note that you cannot delete a branch if it is
652 currently checked out.
655 @node Listing branches and remotes
656 @unnumberedsubsubsec Listing branches and remotes
658 You can get the exact path or URL of all remote branches by
665 To list Git branches on your local repositories, run
668 git branch # list local branches only
669 git branch -r # list remote branches
670 git branch -a # list all branches
674 @node Checking out branches
675 @unnumberedsubsubsec Checking out branches
677 To know the currently checked out branch, i.e. the branch whose
678 source files are present in your working tree, read the first line
686 The currently checked out branch is also marked with an asterisk
687 in the output of @command{git branch}.
689 You can check out another branch @code{@var{other_branch}}, i.e.
690 check out @code{@var{other_branch}} to the working tree, by
694 git checkout @var{other_branch}
697 Note that it is possible to check out another branch while having
698 uncommitted changes, but it is not recommended unless you know
699 what you are doing; it is recommended to run @command{git status}
700 to check this kind of issue before checking out another branch.
702 @node Merging branches
703 @unnumberedsubsubsec Merging branches
705 To merge branch @code{@var{foo}} into branch @code{@var{bar}},
706 i.e. to @qq{add} all changes made in branch @code{@var{foo}} to
707 branch @code{@var{bar}}, run
710 git checkout @var{bar}
714 If any conflict happens, see @ref{Resolving conflicts}.
716 There are common usage cases for merging: as a translator, you
717 will often want to merge @code{master} into
718 @code{lilypond/translation}; on the other hand, the Translations
719 meister wants to merge @code{lilypond/translation} into
720 @code{master} whenever he has checked that
721 @code{lilypond/translation} builds successfully.
724 @node Commits and patches
725 @subsection Commits and patches
729 * Understanding commits::
736 @node Understanding commits
737 @unnumberedsubsubsec Understanding commits
739 Technically, a @emph{commit} is a single point in the history of a
740 branch, but most developers use the term to mean a @emph{commit
741 object}, which stores information about a particular revision. A
742 single commit can record changes to multiple source files, and
743 typically represents one logical set of related changes (such as a
744 bug-fix). You can list the ten most recent commits in your
745 current branch with this command:
748 git log -10 --oneline
751 If you're using an older version of Git and get an @q{unrecognized
752 argument} error, use this instead:
755 git log -10 --pretty=oneline --abbrev-commit
758 More interactive lists of the commits on the remote @code{master}
759 branch are available at
760 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=shortlog} and
761 @uref{http://git.sv.gnu.org/cgit/lilypond.git/log/}.
765 @unnumberedsubsubsec Making commits
768 Once you have modified some source files in your working
769 directory, you can make a commit with the following procedure:
773 Make sure you've configured Git properly (see @ref{Configuring
774 Git}). Check that your changes meet the requirements described in
775 @ref{Code style} and/or @ref{Documentation policy}. For advanced
776 edits, you may also want to verify that the changes don't break
777 the compilation process.
780 Run the following command:
787 to make sure you're on the right branch, and to see which files
788 have been modified, added or removed, etc. You may need to tell
789 Git about any files you've added by running one of these:
792 git add @var{file} # add untracked @var{file} individually
793 git add . # add all untracked files in current directory
797 After @command{git@tie{}add}, run @command{git@tie{}status} again
798 to make sure you got everything. You may also need to modify
802 Preview the changes about to be committed (to make sure everything
810 The @code{HEAD} argument refers to the most recent commit on the
811 currently checked-out branch.
814 Generate the commit with:
821 The @code{-a} is short for @code{--all} which includes modified
822 and deleted files, but only those newly created files that have
823 previously been added.
828 @node Commit messages
829 @unnumberedsubsubsec Commit messages
832 When you run the @command{git@tie{}commit@tie{}-a} command, Git
833 automatically opens the default text editor so you can enter a
834 @emph{commit message}. If you find yourself in a foreign editing
835 environment, you're probably in @command{vi} or @command{vim}. If
836 you want to switch to an editor you're more familiar with, quit by
837 typing @code{:q!} and pressing @code{<Enter>}. See
838 @ref{Configuring Git} for instructions on changing the default
841 In any case, Git will open a text file for your commit message
842 that looks like this:
846 # Please enter the commit message for your changes. Lines starting
847 # with '#' will be ignored, and an empty message aborts the commit.
849 # Changes to be committed:
850 # (use "git reset HEAD <file>..." to unstage)
852 # modified: working.itexi
856 Your commit message should begin with a one-line summary
857 describing the change (no more than 50 characters long), and if
858 necessary a blank line followed by several lines giving the
861 @c $ git log -1 --pretty=medium 4d6f1e5
863 Doc: add Baerenreiter and Henle solo cello suites
865 Added comparison of solo cello suite engravings to new essay with
866 high-res images, fixed cropping on Finale example.
869 Commit messages often start with a short prefix describing the
870 general location of the changes. If a commit affects the
871 documentation in English (or in several languages simultaneously)
872 the commit message should be prefixed with @qq{Doc:@tie{}}. If
873 the commit affects only one of the translations, the commit
874 message should be prefixed with @qq{Doc-@var{**}:@tie{}}, where
875 @var{**} is the two-letter language code. Commits that affect the
876 website should use @qq{Web:@tie{}} for English, and
877 @qq{Web-@var{**}:@tie{}} for the other languages. Also, changes
878 to a single file are often prefixed with the name of the file
879 involved. Visit the links listed in @ref{Understanding commits}
884 @unnumberedsubsubsec Making patches
887 If you want to share your changes with other contributors and
888 developers, you need to generate @emph{patches} from your commits.
889 You should always run @command{git@tie{}pull@tie{}-r} (translators
890 should leave off the @code{-r}) before doing this to ensure that
891 your patches are as current as possible.
893 Once you have made one or more commits in your local repository,
894 and pulled the most recent commits from the remote branch, you can
895 generate patches from your local commits with the command:
898 git format-patch origin
901 The @code{origin} argument refers to the remote tracking branch at
902 @code{git.sv.gnu.org}. This command generates a separate patch
903 for each commit that's in the current branch but not in the remote
904 branch. Patches are placed in the current working directory and
905 will have names that look something like this:
908 0001-Doc-Fix-typos.patch
909 0002-Web-Remove-dead-links.patch
913 Send an email to @email{lilypond-devel@@gnu.org} briefly
914 explaining your work, with the patch files attached. Translators
915 should send patches to @email{translations@@lilynet.net}. After
916 your patches are reviewed, the developers may push one or more of
917 them to the main repository or discuss them with you.
921 If your patch includes a significant amount of code, you may want
922 to see @ref{Adding or modifying features}, especially @emph{Post
926 @node Advanced Git procedures
927 @section Advanced Git procedures
930 @warning{This section is not necessary for normal contributors;
931 these commands are presented for information for people interested
932 in learning more about git.}
934 It is possible to work with several branches on the same local Git
935 repository; this is especially useful for translators who may have
936 to deal with both @code{lilypond/translation} and a stable branch,
937 e.g. @code{stable/2.12}.
939 Some Git commands are introduced first, then a workflow with
940 several Git branches of LilyPond source code is presented.
944 * Advanced Git concepts::
945 * Resolving conflicts::
946 * Reverting all local changes::
947 * Working with remote branches::
949 * Applying remote patches::
950 * Sending and receiving patches via email::
955 @node Advanced Git concepts
956 @subsection Advanced Git concepts
959 A bit of Git vocabulary will be explained below. The following is
960 only introductory; for a better understanding of Git concepts, you
961 may wish to read @ref{Other Git documentation}.
963 The @code{git@tie{}pull@tie{}origin} command above is just a
964 shortcut for this command:
967 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
971 where @code{@var{branch}} is typically @code{master} or
972 @code{lilypond/translation}; if you do not know or remember, see
973 @ref{Downloading remote branches} to remember which commands you
974 issued or which source code you wanted to get.
976 A @emph{commit} is a set of changes made to the sources; it also
977 includes the committish of the parent commit, the name and e-mail
978 of the @emph{author} (the person who wrote the changes), the name
979 and e-mail of the @emph{committer} (the person who brings these
980 changes into the Git repository), and a commit message.
982 A @emph{committish} is the SHA1 checksum of a commit, a number
983 made of 40 hexadecimal digits, which acts as the internal unique
984 identifier for this commit. To refer to a particular revision,
985 don't use vague references like the (approximative) date, simply
986 copy and paste the committish.
988 A @emph{branch} is nothing more than a pointer to a particular
989 commit, which is called the @emph{head} of the branch; when
990 referring to a branch, one often acutally thinks about its head
991 and the ancestor commits of the head.
993 Now we will explain the two last commands you used to get the
994 source code from Git---see @ref{Downloading individual branches}.
997 git remote add -ft @var{branch} -m @var{branch} \
998 origin git://git.sv.gnu.org/lilypond.git/
1000 git checkout -b @var{branch} origin/@var{branch}
1003 The @command{git@tie{}remote} has created a branch called
1004 @code{origin/@var{branch}} in your local Git repository. As this
1005 branch is a copy of the remote branch web from git.sv.gnu.org
1006 LilyPond repository, it is called a @emph{remote branch}, and is
1007 meant to track the changes on the branch from git.sv.gnu.org: it
1008 will be updated every time you run
1009 @command{git@tie{}pull@tie{}origin} or
1010 @command{git@tie{}fetch@tie{}origin}.
1012 The @command{git@tie{}checkout} command has created a branch named
1013 @code{@var{branch}}. At the beginning, this branch is identical
1014 to @code{origin/@var{branch}}, but it will differ as soon as you
1015 make changes, e.g. adding newly translated pages or editing some
1016 documentation or code source file. Whenever you pull, you merge
1017 the changes from @code{origin/@var{branch}} and
1018 @code{@var{branch}} since the last pulling. If you do not have
1019 push (i.e. @qq{write}) access on git.sv.gnu.org, your
1020 @code{@var{branch}} will always differ from
1021 @code{origin/@var{branch}}. In this case, remember that other
1022 people working like you with the remote branch @code{@var{branch}}
1023 of git://git.sv.gnu.org/lilypond.git/ (called
1024 @code{origin/@var{branch}} on your local repository) know nothing
1025 about your own @code{@var{branch}}: this means that whenever you
1026 use a committish or make a patch, others expect you to take the
1027 latest commit of @code{origin/@var{branch}} as a reference.
1029 Finally, please remember to read the man page of every Git command
1030 you will find in this manual in case you want to discover
1031 alternate methods or just understand how it works.
1034 @node Resolving conflicts
1035 @subsection Resolving conflicts
1038 Occasionally an update may result in conflicts -- this happens
1039 when you and somebody else have modified the same part of the same
1040 file and git cannot figure out how to merge the two versions
1041 together. When this happens, you must manually merge the two
1044 If you need some documentation to understand and resolve
1045 conflicts, see paragraphs @emph{How conflicts are presented} and
1046 @emph{How to resolve conflicts} in @command{git merge} man page.
1048 If all else fails, you can follow the instructions in
1049 @ref{Reverting all local changes}. Be aware that this eliminates
1050 any changes you have made!
1053 @node Reverting all local changes
1054 @subsection Reverting all local changes
1056 Sometimes git will become hopelessly confused, and you just want
1057 to get back to a known, stable state. This command destroys any
1058 local changes you have made, but at least you get back to the
1059 current online version:
1062 git reset --hard origin/master
1066 @node Working with remote branches
1067 @subsection Working with remote branches
1070 @subsubheading Fetching new branches from git.sv.gnu.org
1072 To fetch and check out a new branch named @code{@var{branch}} on
1073 git.sv.gnu.org, run from top of the Git repository
1076 git config --add remote.origin.fetch \
1077 +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
1079 git checkout --track -b @var{branch} origin/@var{branch}
1082 After this, you can pull @code{@var{branch}} from git.sv.gnu.org
1089 Note that this command generally fetches all branches you added
1090 with @command{git@tie{}remote@tie{}add} (when you initialized the
1091 repository) or @command{git@tie{}config@tie{}--add}, i.e. it
1092 updates all remote branches from remote @code{origin}, then it
1093 merges the remote branch tracked by the current branch into the
1094 current branch. For example, if your current branch is
1095 @code{master}, @code{origin/master} will be merged into
1099 @subsubheading Local clones, or having several working trees
1101 If you play with several Git branches, e.g. @code{master},
1102 @code{lilypond/translation}, @code{stable/2.12}), you may want to
1103 have one source and build tree for each branch; this is possible
1104 with subdirectories of your local Git repository, used as local
1105 cloned subrepositories. To create a local clone for the branch
1106 named @code{@var{branch}}, run
1109 git checkout @var{branch}
1110 git clone -lsn . @var{subdir}
1115 Note that @code{@var{subdir}} must be a directory name which does
1116 not already exist. In @code{@var{subdir}}, you can use all Git
1117 commands to browse revisions history, commit and uncommit changes;
1118 to update the cloned subrepository with changes made on the main
1119 repository, cd into @code{@var{subdir}} and run
1120 @command{git@tie{}pull}; to send changes made on the subrepository
1121 back to the main repository, run @command{git@tie{}push} from
1122 @code{@var{subdir}}. Note that only one branch (the currently
1123 checked out branch) is created in the subrepository by default; it
1124 is possible to have several branches in a subrepository and do
1125 usual operations (checkout, merge, create, delete...) on these
1126 branches, but this possibility is not detailed here.
1128 When you push @code{@var{branch}} from @code{@var{subdir}} to the
1129 main repository, and @code{@var{branch}} is checked out in the
1130 main repository, you must save uncommitted changes (see
1131 @command{git@tie{}stash}) and do
1132 @command{git@tie{}reset@tie{}--hard} in the main repository in
1133 order to apply pushed changes in the working tree of the main
1141 The commands above don't only bring you the latest version of the
1142 sources, but also the full history of revisions (revisons, also
1143 called commits, are changes made to the sources), stored in the
1144 @file{.git} directory. You can browse this history with
1147 git log # only shows the logs (author, committish and commit message)
1148 git log -p # also shows diffs
1149 gitk # shows history graphically
1152 @warning{The @code{gitk} command may require a separate
1153 @code{gitk} package, available in the appropriate distribution's
1157 @node Applying remote patches
1158 @subsection Applying remote patches
1161 FIXME: Explain how to determine if a patch was created with
1162 @code{git@tie{}format-patch}.
1164 Well-formed git patches created with @code{git@tie{}format-patch}
1165 should be committed with the following command:
1171 Patches created without @code{git@tie{}format-patch} can be
1172 applied in two steps. The first step is to apply the patch to the
1176 git apply @var{patch}
1180 The second step is to commit the changes and give credit to the
1181 author of the patch. This can be done with the following command:
1184 git commit -a --author="@var{John Smith} <@var{john@@example.com}>"
1188 @node Sending and receiving patches via email
1189 @subsection Sending and receiving patches via email
1192 The default @code{x-diff} MIME type associated with patch files
1193 (i.e., files whose name ends in @code{.patch}) means that the
1194 encoding of line endings may be changed from UNIX to DOS format
1195 when they are sent as attachments. Attempting to apply such an
1196 inadvertently altered patch will cause git to fail with a message
1197 about @q{whitespace errors}.
1199 The solution to such problems is surprisingly simple---just change
1200 the default file extension of patches generated by git to end in
1201 @code{.txt}, for example:
1204 git config format.suffix '.patch.txt'
1207 This should cause email programs to apply the correct base64
1208 encoding to attached patches.
1210 If you receive a patch with DOS instead of UNIX line-endings, it
1211 can be converted back using the @code{dos2unix} utility.
1213 Lots of useful information on email complications with patches is
1214 provided on the Wine wiki at
1215 @uref{http://wiki.winehq.org/GitWine}.
1219 @subsection Commit access
1222 Most contributors are not able to commit patches directly to the
1223 main repository---only members of the LilyPond development team
1224 have @emph{commit access}. If you are a contributor and are
1225 interested in joining the development team, contact the Project
1226 Manager through the mailing list
1227 (@email{lilypond-devel@@gnu.org}). Generally, only contributors
1228 who have already provided a number of patches which have been
1229 pushed to the main repository will be considered for membership.
1231 If you have been approved by the Project Manager, use the
1232 following procedure to obtain commit access:
1236 If you don't already have one, set up a Savannah user account at
1237 @uref{https://savannah.gnu.org/account/register.php}. If your web
1238 browser responds with an @qq{untrusted connection} message when
1239 you visit the link, follow the steps for including the CAcert root
1240 certificate in your browser, given at
1241 @uref{http://savannah.gnu.org/tls/tutorial/}.
1244 After registering, if you are not logged in automatically, login
1245 at @uref{https://savannah.gnu.org/account/login.php}---this should
1246 take you to your @qq{my} page
1247 (@uref{https://savannah.gnu.org/my/}).
1250 Click on the @qq{My Groups} link to access the @qq{My Group
1251 Membership} page. From there, find the @qq{Request for Inclusion}
1252 box and search for @qq{LilyPond}. Among the search results, check
1253 the box labeled @qq{GNU LilyPond Music Typesetter} and write a
1254 brief (required) message for the Project Manager (@qq{Hey it's
1255 me!} should be fine).
1257 Note that you will not have commit access until the Project
1258 Manager activates your membership. Once your membership is
1259 activated, LilyPond should appear under the heading @qq{Groups I'm
1260 Contributor of} on your @qq{My Group Membership} page.
1263 Go to the @qq{My Account Configuration} page. From there, click
1264 on @qq{Edit SSH Keys} and follow the instructions given.
1266 FIXME: Explain the confusing warning I always get. -mp
1268 FIXME: Maybe add a note about enabling/disabling SSH passphrase?
1271 Configure Git to use the SSH protocol (instead of the GIT
1272 protocol). From your local Git repository, enter:
1275 git config remote.origin.url \
1276 ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1280 where @var{user} is your username on Savannah.
1283 After your membership has been activated and you've configured Git
1284 to use SSH, try doing a @command{git@tie{}pull} or
1285 @command{git@tie{}pull@tie{}-r}. If that succeeds, this indicates
1286 that your SSH key stored at Savannah is working properly.
1288 FIXME: show what success/failure look like.
1291 Test your commit access with a dry run:
1294 git push --dry-run --verbose
1297 Note that recent versions of Git (Git 1.6.3 or later) will issue a
1298 big warning if the above command is used. The simplest solution
1299 is to tell Git to push all matching branches by default:
1302 git config push.default matching
1306 Then @code{git@tie{}push} should work as before. For more
1307 details, consult the @code{git@tie{}push} man page.
1311 @subsubheading Technical details
1315 On Firefox, to view or remove the CAcert root certificate, go to:
1316 Edit > Preferences > Advanced > Encryption > View Certificates >
1317 Authorities > Certificate Name > Root CA > CA Cert Signing
1321 The @command{git@tie{}config} commands above should modify your
1322 local repository's @file{.git/config} file. These lines:
1326 url = git://git.sv.gnu.org/lilypond.git/
1330 should now be changed to:
1334 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1338 where @var{user} is your login name on Savannah.
1342 @command{git@tie{}config@tie{}push.default@tie{}matching} command
1343 should add these lines to @file{.git/config}:
1351 @node Git on Windows
1352 @section Git on Windows
1354 @c Some of this may duplicate stuff in other sections
1355 @c But it is probably best for windows users to have it all together
1356 @c If necessary, clear this up later -td
1358 FIXME: Decide what to do with this... Pare it down? Move
1359 paragraphs next to analogous Unix instructions? -mp
1361 @subsection Background to nomenclature
1363 Git is a system for tracking the changes made to source files by a
1364 distributed set of editors. It is designed to work without a
1365 master repository, but we have chosen to have a master respository
1366 for LilyPond files. Editors hold a local copy of the master
1367 repository together with any changes they have made locally.
1368 Local changes are held in a local @q{branch}, of which there may
1369 be several, but these instructions assume you are using just one.
1370 The files visible in the local repository always correspond to
1371 those on the currently @q{checked out} local branch.
1373 Files are edited on a local branch, and in that state the changes
1374 are said to be @q{unstaged}. When editing is complete, the
1375 changes are moved to being @q{staged for commit}, and finally the
1376 changes are @q{committed} to the local branch. Once committed,
1377 the changes (called a @q{commit}) are given a unique 40-digit
1378 hexadecimal reference number called the @q{Committish} or @q{SHA1
1379 ID} which identifies the commit to Git. Such committed changes
1380 can be sent to the master repository by @q{pushing} them (if you
1381 have write permission) or by sending them by email to someone who
1382 has, either as a complete file or as a @q{diff} or @q{patch}
1383 (which send just the differences from the master repository).
1385 @subsection Installing git
1388 @uref{http://code.google.com/p/msysgit/downloads/list} (note, not
1389 msysGit, which is for Git developers and not PortableGit, which is
1390 not a full git installation) and install it.
1392 Note that most users will not need to install SSH. That is not
1393 required until you have been granted direct push permissions to
1394 the master git repository.
1396 Start Git by clicking on the desktop icon. This will bring up a
1397 command line bash shell. This may be unfamiliar to Windows users.
1398 If so, follow these instructions carefully. Commands are entered
1399 at a $ prompt and are terminated by keying a newline.
1401 @subsection Initialising Git
1403 Decide where you wish to place your local Git repository, creating
1404 the folders in Windows as necessary. Here we call the folder to
1405 contain the repository @code{[path]/Git}, but if you intend using
1406 Git for other projects a directory name like @code{lilypond-git}
1407 might be better. You will need to have space for around
1410 Start the Git bash shell by clicking on the desk-top icon
1411 installed with Git and type
1417 to position the shell at your new Git repository.
1419 Note: if [path] contains folders with names containing spaces use
1431 to initialize your Git repository.
1433 Then type (all on one line; the shell will wrap automatically)
1436 git remote add -ft master origin git://git.sv.gnu.org/lilypond.git
1439 to download the lilypond master files.
1441 @warning{Be patient! Even on a broadband connection this can take
1442 10 minutes or more. Wait for lots of [new tag] messages and the $
1445 We now need to generate a local copy of the downloaded files in a
1446 new local branch. Your local branch needs to have a name. It is
1447 usual to call it @q{master} and we shall do that here.
1452 git checkout -b master origin/master
1455 This creates a second branch called @q{master}. You will see two
1456 warnings (ignore these), and a message advising you that your
1457 local branch @q{master} has been set up to track the remote
1458 branch. You now have two branches, a local branch called
1459 @q{master}, and a tracking branch called @q{origin/master}, which
1460 is a shortened form of @q{remotes/origin/master}.
1462 Return to Windows Explorer and look in your Git repository. You
1463 should see lots of folders. For example, the LilyPond
1464 documentation can be found in [path]/Git/Documentation/.
1466 The Git bash shell is terminated by typing @code{exit} or by
1467 clicking on the usual Windows close-window widget.
1471 Almost all subsequent work will use the Git Graphical User
1472 Interface, which avoids having to type command line commands. To
1473 start Git GUI first start the Git bash shell by clicking on the
1474 desktop icon, and type
1481 The Git GUI will open in a new window. It contains four panels
1482 and 7 pull-down menus. At this stage do not use any of the
1483 commands under Branch, Commit, Merge or Remote. These will be
1486 The top panel on the left contains the names of files which you
1487 are in the process of editing (Unstaged Changes), and the lower
1488 panel on the left contains the names of files you have finished
1489 editing and have staged ready for committing (Staged Changes). At
1490 present, these panels will be empty as you have not yet made any
1491 changes to any file. After a file has been edited and saved the
1492 top panel on the right will display the differences between the
1493 edited file selected in one of the panels on the left and the last
1494 version committed on the current branch.
1496 The panel at bottom right is used to enter a descriptive message
1497 about the change before committing it.
1499 The Git GUI is terminated by entering CNTL-Q while it is the
1500 active window or by clicking on the usual Windows close-window
1503 @subsection Personalising your local git repository
1505 Open the Git GUI, click on
1511 and enter your name and email address in the left-hand (Git
1512 Repository) panel. Leave everything else unchanged and save it.
1514 Note that Windows users must leave the default setting for line
1515 endings unchanged. All files in a git repository must have lines
1516 terminated by just a LF, as this is required for Merge to work,
1517 but Windows files are terminated by CRLF by default. The git
1518 default setting causes the line endings of files in a Windows git
1519 repository to be flipped automatically between LF and CRLF as
1520 required. This enables files to be edited by any Windows editor
1521 without causing problems in the git repository.
1523 @subsection Checking out a branch
1525 At this stage you have two branches in your local repository,
1526 both identical. To see them click on
1532 You should have one local branch called @q{master} and one
1533 tracking branch called @q{origin/master}. The latter is your
1534 local copy of the @q{remotes/origin/master} branch in the master
1535 LilyPond repository. The local @q{master} branch is where you
1536 will make your local changes.
1538 When a particular branch is selected, i.e., checked out, the files
1539 visible in your repository are changed to reflect the state of the
1540 files on that branch.
1542 @subsection Updating files from @q{remote/origin/master}
1544 Before starting the editing of a file, ensure your local
1545 repository contains the latest version of the files in the remote
1546 repository by first clicking
1549 Remote -> Fetch from -> origin
1555 This will place the latest version of every file, including all
1556 the changes made by others, into the @q{origin/master} branch of
1557 the tracking branches in your git repository. You can see these
1558 files by checking out this branch, but you must @emph{never} edit
1559 any files while this branch is checked out. Check out your local
1560 @q{master} branch again.
1562 You then need to merge these fetched files into your local
1563 @q{master} branch by clicking on
1566 Merge -> Local Merge
1570 and if necessary select the local @q{master} branch.
1572 Note that a merge cannot be completed if you have made any local
1573 changes which have not yet been committed.
1575 This merge will update all the files in the @q{master} branch to
1576 reflect the current state of the @q{origin/master} branch. If any
1577 of the changes conflict with changes you have made yourself
1578 recently you will be notified of the conflict (see below).
1580 @subsection Editing files
1582 First ensure your @q{master} branch is checked out, then simply
1583 edit the files in your local Git repository with your favourite
1584 editor and save them back there. If any file contains non-ASCII
1585 characters ensure you save it in UTF-8 format. Git will detect
1586 any changes whenever you restart Git GUI and the file names will
1587 then be listed in the Unstaged Changes panel. Or you can click
1588 the Rescan button to refresh the panel contents at any time. You
1589 may break off and resume editing any time.
1591 The changes you have made may be displayed in diff form in the top
1592 right-hand panel of Git GUI by clicking on the file name shown in
1593 one of the left panels.
1595 When your editing is complete, move the files from being Unstaged
1596 to Staged by clicking the document symbol to the left of each
1597 name. If you change your mind it can be moved back by clicking on
1598 the ticked box to the left of the name.
1600 Finally the changes you have made may be committed to your
1601 @q{master} branch by entering a brief message in the Commit
1602 Message box and clicking the Commit button.
1604 If you wish to amend your changes after a commit has been made,
1605 the original version and the changes you made in that commit may
1606 be recovered by selecting
1609 Commit -> Amend Last Commit
1613 or by checking the Amend Last Commit radio button at bottom right.
1614 This will return the changes to the Staged state, so further
1615 editing made be carried out within that commit. This must only be
1616 done @emph{before} the changes have been Pushed or sent to your
1617 mentor for Pushing - after that it is too late and corrections
1618 have to be made as a separate commit.
1621 @subsection Sending changes to @q{remotes/origin/master}
1623 If you do not have write access to @q{remotes/origin/master} you
1624 will need to send your changes by email to someone who does.
1626 First you need to create a diff or patch file containing your
1627 changes. To create this, the file must first be committed. Then
1628 terminate the Git GUI. In the git bash shell first cd to your Git
1635 if necessary, then produce the patch with
1638 git format-patch origin
1641 This will create a patch file for all the locally committed files
1642 which differ from @q{origin/master}. The patch file can be found
1643 in [path]/Git and will have a name formed from the commit message.
1645 @subsection Resolving merge conflicts
1647 As soon as you have committed a changed file your local
1648 @code{master} branch has diverged from @code{origin/master}, and
1649 will remain diverged until your changes have been committed in
1650 @code{remotes/origin/master} and Fetched back into your
1651 @code{origin/master} branch. Similarly, if a new commit has been
1652 made to @code{remotes/origin/master} by someone else and Fetched,
1653 your local @code{master} branch is divergent. You can detect a
1654 divergent branch by clicking on
1657 Repository -> Visualise all branch history
1660 This opens up a very useful new window called @q{gitk}. Use this
1661 to browse all the commits made by yourself and others.
1663 If the diagram at top left of the resulting window does not show
1664 your @code{master} tag on the same node as the
1665 @code{remotes/origin/master} tag your branch has diverged from
1666 @code{origin/master}. This is quite normal if files you have
1667 modified yourself have not yet been Pushed to
1668 @code{remotes/origin/master} and Fetched, or if files modified and
1669 committed by others have been Fetched since you last Merged
1670 @code{origin/master} into your local @code{master} branch.
1672 If a file being merged from @code{origin/master} differs from one
1673 you have modified in a way that cannot be resolved automatically
1674 by git, Merge will report a Conflict which you must resolve by
1675 editing the file to create the version you wish to keep.
1677 This could happen if the person updating
1678 @code{remotes/origin/master} for you has added some changes of his
1679 own before committing your changes to
1680 @code{remotes/origin/master}, or if someone else has changed the
1681 same file since you last fetched the file from
1682 @code{remotes/origin/master}.
1684 Open the file in your editor and look for sections which are
1687 [to be completed when I next have a merge conflict to be sure I
1688 give the right instructions -td]
1691 @subsection Other actions
1693 The instructions above describe the simplest way of using git on
1694 Windows. Other git facilities which may usefully supplement these
1698 @item Using multiple local branches (Create, Rename, Delete)
1699 @item Resetting branches
1700 @item Cherry-picking commits
1701 @item Pushing commits to @w{remote/origin/master}
1702 @item Using gitk to review history
1705 Once familiarity with using git on Windows has been gained the
1706 standard git manuals can be used to learn about these.
1709 @node Repository directory structure
1710 @section Repository directory structure
1713 @c TODO: integrate the roadmap better
1714 @verbatiminclude ROADMAP
1717 @node Other Git documentation
1718 @section Other Git documentation
1722 Official git man pages:
1723 @uref{http://www.kernel.org/pub/software/scm/git/docs/}
1726 More in-depth tutorials: @uref{http://git-scm.com/documentation}
1729 Book about git: @uref{http://progit.org/,Pro Git}