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 FIXME: Add instructions for using @command{lily-git} here.
26 @node Starting with Git
27 @section Starting with Git
30 Using the Git program directly (as opposed to using the
31 @command{lily-git} GUI) allows you to have much greater control
32 over the contributing process. You should consider using Git if
33 you want to work on complex projects, or if you want to work on
34 multiple projects concurrently.
39 * Downloading remote branches::
44 @subsection Setting up
47 FIXME: Remove this note if incorporating Windows instructions
48 throughout this section:
50 @warning{These instructions assume that you are using the
51 command-line version of Git 1.5 or higher. Windows users should
52 skip to @ref{Git on Windows}.}
56 * Initializing a repository::
62 @unnumberedsubsubsec Installing Git
65 If you are using a Unix-based machine, the easiest way to download
66 and install Git is through a package manager such as @command{rpm}
67 or @command{apt-get}---the installation is generally automatic.
68 The only required package is (usually) called @command{git-core},
69 although some of the auxiliary @command{git@var{*}} packages are
70 also useful (such as @command{gitk}).
72 Alternatively, you can visit the Git website
73 (@uref{http://git-scm.com/}) for downloadable binaries and
76 FIXME: add Windows installation instructions (or @@ref@{Git on
80 @node Initializing a repository
81 @unnumberedsubsubsec Initializing a repository
84 Once Git is installed, you'll need to create a new directory where
85 your initial repository will be stored (the example below uses
86 @file{~/lilypond-git/}, where @code{~} represents your home
87 directory). Run @command{git@tie{}init} from within the new
88 directory to initialize an empty repository:
91 mkdir ~/lilypond-git/; cd ~/lilypond-git/
95 @subsubheading Technical details
97 This creates (within the @file{~/lilypond-git/} directory) a
98 subdirectory called @file{.git/}, which Git uses to keep track of
99 changes to the repository, among other things. Normally you don't
100 need to access it, but it's good to know it's there.
103 @node Configuring Git
104 @unnumberedsubsubsec Configuring Git
106 @warning{Throughout the rest of this manual, all command-line
107 input should be entered from the top directory of the Git
108 repository being discussed (eg. @file{~/lilypond-git/}). This is
109 referred to as a @emph{top source directory}.}
111 Before downloading a copy of the main LilyPond repository, you
112 should configure some basic settings with the
113 @command{git@tie{}config} command. Git allows you to set both
114 global and repository-specific options.
116 To configure settings that affect all repositories, use the
117 @command{--global} command line option. For example, the first
118 two options that you should always set are your @var{name} and
119 @var{email}, since Git needs these to keep track of commit
123 git config --global user.name "@var{John Smith}"
124 git config --global user.email @var{john@@example.com}
127 To configure Git to use colored output where possible, use:
130 git config --global color.ui auto
133 The text editor that opens when using @command{git@tie{}commit}
134 can also be changed. If none of your editor-related environment
135 variables are set ($GIT_EDITOR, $VISUAL, or $EDITOR), the default
136 editor is usually @command{vi} or @command{vim}. If you're not
137 familiar with either of these, you should probably change the
138 default to an editor that you know how to use. For example, to
139 change the default editor to @command{nano}, enter:
142 git config --global core.editor @var{nano}
145 FIXME: Add instructions for changing the editor on Windows, which
146 is a little different, I think. -mp
148 @subsubheading Technical details
150 Git stores the information entered with
151 @command{git@tie{}config@tie{}--global} in the file
152 @file{.gitconfig}, located in your home directory. This file can
153 also be modified directly, without using
154 @command{git@tie{}config}. The @file{.gitconfig} file generated
155 by the above commands would look like this:
160 email = john@@example.com
167 Using the @command{git@tie{}config} command @emph{without} the
168 @command{--global} option configures repository-specific settings,
169 which are stored in the file @file{.git/config}. This file is
170 created when a repository is initialized (using
171 @command{git@tie{}init}), and by default contains these lines:
175 repositoryformatversion = 0
178 logallrefupdates = true
181 However, since different repository-specific options are
182 recommended for different development tasks, it is best to avoid
183 setting any now. Specific recommendations will be mentioned later
187 @node Downloading remote branches
188 @subsection Downloading remote branches
192 * Organization of remote branches::
193 * LilyPond repository sources::
194 * Downloading individual branches::
195 * Downloading all remote branches::
200 @node Organization of remote branches
201 @unnumberedsubsubsec Organization of remote branches
204 The main LilyPond repository is organized into @emph{branches} to
205 facilitate development. These are often called @emph{remote}
206 branches to distinguish them from @emph{local} branches you might
207 create yourself (see @ref{Using local branches}).
209 The @code{master} branch contains all the source files used to
210 build LilyPond, which includes the program itself (both stable and
211 development releases), the documentation (and its translations),
212 and the website. Generally, the @code{master} branch is expected
213 to compile successfully.
215 The @code{lilypond/translation} branch is a side branch that
216 allows translators to work without needing to worry about
217 compilation problems. Periodically, the Translation Meister
218 (after verifying that it doesn't break compilation), will
219 @emph{merge} this branch back into @code{master} to incorporate
220 recent translations. Similarly, the @code{master} branch is
221 usually merged into the @code{lilypond/translation} branch after
222 significant changes to the English documentation. See
223 @ref{Translating the documentation} for details.
226 @node LilyPond repository sources
227 @unnumberedsubsubsec LilyPond repository sources
230 The recommended source for downloading a copy of the main
234 git://git.sv.gnu.org/lilypond.git
237 However, if your internet router filters out connections using the
238 GIT protocol, or if you experience difficulty connecting via GIT,
239 you can try these other sources:
242 ssh://git.sv.gnu.org/srv/git/lilypond.git
243 http://git.sv.gnu.org/r/lilypond.git
246 The SSH protocol can only be used if your system is properly set
247 up to use it. Also, the HTTP protocol is slowest, so it should
248 only be used as a last resort.
251 @node Downloading individual branches
252 @unnumberedsubsubsec Downloading individual branches
255 Once you have initialized an empty Git repository on your system
256 (see @ref{Initializing a repository}), you can download a remote
257 branch into it. Make sure you know which branch you want to start
260 To download the @code{master} branch, enter the following:
263 git remote add -ft master -m master \
264 origin git://git.sv.gnu.org/lilypond.git/
267 To download the @code{lilypond/translation} branch, enter:
270 git remote add -ft lilypond/translation -m \
271 lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
274 The @command{git@tie{}remote@tie{}add} process could take up to
275 ten minutes, depending on the speed of your connection. The
276 output will be something like this:
280 remote: Counting objects: 235967, done.
281 remote: Compressing objects: 100% (42721/42721), done.
282 remote: Total 235967 (delta 195098), reused 233311 (delta 192772)
283 Receiving objects: 100% (235967/235967), 68.37 MiB | 479 KiB/s, done.
284 Resolving deltas: 100% (195098/195098), done.
285 From git://git.sv.gnu.org/lilypond
286 * [new branch] master -> origin/master
287 From git://git.sv.gnu.org/lilypond
288 * [new tag] flower/1.0.1 -> flower/1.0.1
289 * [new tag] flower/1.0.10 -> flower/1.0.10
291 * [new tag] release/2.9.6 -> release/2.9.6
292 * [new tag] release/2.9.7 -> release/2.9.7
295 When @command{git@tie{}remote@tie{}add} is finished, the remote
296 branch should be downloaded into your repository---though not yet
297 in a form that you can use. In order to browse the source code
298 files, you need to @emph{create} and @emph{checkout} your own
299 local branch. In this case, however, it is easier to have Git
300 create the branch automatically by using the @command{checkout}
301 command on a non-existent branch. Enter the following:
304 git checkout -b @var{branch} origin/@var{branch}
308 where @code{@var{branch}} is the name of your tracking branch,
309 either @code{master} or @code{lilypond/translation}.
311 Git will issue some warnings; this is normal:
314 warning: You appear to be on a branch yet to be born.
315 warning: Forcing checkout of origin/master.
316 Branch master set up to track remote branch master from origin.
320 By now the source files should be accessible---you should be able
321 to edit any files in the @file{lilypond-git/} directory using a
322 text editor of your choice. But don't start just yet! Before
323 editing any source files, learn how to keep your changes organized
324 and prevent problems later---read @ref{Basic Git procedures}.
326 @subsubheading Technical Details
328 The @command{git@tie{}remote@tie{}add} command should add some
329 lines to your local repository's @file{.git/config} file:
333 url = git://git.sv.gnu.org/lilypond.git/
334 fetch = +refs/heads/master:refs/remotes/origin/master
338 @node Downloading all remote branches
339 @unnumberedsubsubsec Downloading all remote branches
342 To download all remote branches at once, you can @command{clone}
343 the entire repository:
346 git clone git://git.sv.gnu.org/lilypond.git
351 @unnumberedsubsubsec Other branches
353 Most contributors will never need to touch the other branches. If
354 you wish to do so, you will need more familiarity with Git; please
355 see @ref{Other Git documentation}.
358 @item @code{dev/XYZ}:
359 These branches are for individual developers. They store code
360 which is not yet stable enough to be added to the @code{master}
363 @item @code{stable/XYZ}:
364 The branches are kept for archival reasons.
368 Another item of interest might be the Grand Unified Builder, our
369 cross-platform building tool. Since it is used by projects as
370 well, it is not stored in our gub repository. For more info, see
371 @uref{http://lilypond.org/gub}. The git location is
372 @uref{http://github.com/janneke/gub}.
375 @node Basic Git procedures
376 @section Basic Git procedures
380 * The Git contributor's cycle::
381 * Pulling and rebasing::
382 * Using local branches::
383 * Commits and patches::
387 @node The Git contributor's cycle
388 @subsection The Git contributor's cycle
391 Here is a simplified view of the contribution process on Git:
395 Update your local repository by @emph{pulling} the most recent
396 updates from the remote repository.
399 Edit source files within your local repository's @emph{working
403 @emph{Commit} the changes you've made to a local @emph{branch}.
406 Generate a @emph{patch} to share your changes with the developers.
410 @node Pulling and rebasing
411 @subsection Pulling and rebasing
414 When developers push new patches to the @code{git.sv.gnu.org}
415 repository, your local repository is @strong{not} automatically
416 updated. It is important to keep your repository up-to-date by
417 periodically @emph{pulling} the most recent @emph{commits} from
418 the remote branch. Developers expect patches to be as current as
419 possible, since outdated patches require extra work before they
422 Occasionally you may need to rework some of your own modifications
423 to match changes made to the remote branch (see @ref{Resolving
424 conflicts}), and it's considerably easier to rework things
425 incrementally. If you don't update your repository along the way,
426 you may have to spend a lot of time resolving branch conflicts and
427 reconfiguring much of the work you've already done.
429 Fortunately, Git is able to resolve certain types of branch
430 conflicts automatically with a process called @emph{rebasing}.
431 When rebasing, Git tries to modify your old commits so they appear
432 as new commits (based on the latest updates). For a more involved
433 explanation, see the @command{git-rebase} man page.
435 To pull without rebasing (recommended for translators), use the
439 git pull # recommended for translators
442 If you're tracking the remote @code{master} branch, you should add
443 the @code{-r} option (short for @code{--rebase}) to keep commits
444 on your local branch current:
447 git pull -r # use with caution when translating
450 If you don't edit translated documentation and don't want to type
451 @code{-r} every time, configure the master branch to rebase by
452 default with this command:
455 git config branch.master.rebase true
458 If pull fails because of a message like
461 error: Your local changes to 'Documentation/learning/tutorial.itely'
462 would be overwritten by merge. Aborting.
469 Documentation/learning/tutorial.itely: needs update
470 refusing to pull with rebase: your working tree is not up-to-date
474 it means that you have modified some files in you working tree
475 without committing changes (see @ref{Commits and patches}); you
476 can use the @command{git@tie{}stash} command to work around this:
479 git stash # save uncommitted changes
480 git pull -r # pull using rebase (translators omit "-r")
481 git stash pop # reapply previously saved changes
484 Note that @command{git@tie{}stash@tie{}pop} will try to apply a
485 patch, and this may create a conflict. If this happens, see
486 @ref{Resolving conflicts}.
488 FIXME: I think the next paragraph is confusing. Perhaps prepare
489 the reader for new terms `committish' and `head'? -mp
491 @warning{translators and documentation editors, if you have
492 changed committishes in the head of translated files using commits
493 you have not yet pushed to @code{git.sv.gnu.org}, please do not
494 rebase. If you want to avoid wondering whether you should rebase
495 each time you pull, please always use committishes from master
496 and/or lilypond/translation branch on @code{git.sv.gnu.org}, which
497 in particular implies that you must push your changes to
498 documentation except committishes updates (possibly after having
499 rebased), then update the committishes and push them.}
501 FIXME: when committishes automatic conditional update have been
502 tested and documented, append the following to the warning above:
503 Note that using update-committishes make target generally touches
506 @subsubheading Technical details
508 The @command{git@tie{}config} command mentioned above adds the
509 line @code{rebase = true} to the master branch in your local
510 repository's @file{.git/config} file:
515 merge = refs/heads/master
520 @node Using local branches
521 @subsection Using local branches
525 * Creating and removing branches::
526 * Listing branches and remotes::
527 * Checking out branches::
532 @node Creating and removing branches
533 @unnumberedsubsubsec Creating and removing branches
536 Local branches are useful when you're working on several different
537 projects concurrently. To create a new branch, enter:
540 git branch @var{name}
543 To delete a branch, enter:
546 git branch -d @var{name}
549 Git will ask you for confirmation if it sees that data would be
550 lost by deleting the branch. Use @code{-D} instead of @code{-d}
551 to bypass this. Note that you cannot delete a branch if it is
552 currently checked out.
555 @node Listing branches and remotes
556 @unnumberedsubsubsec Listing branches and remotes
558 You can get the exact path or URL of all remote branches by
565 To list Git branches on your local repositories, run
568 git branch # list local branches only
569 git branch -r # list remote branches
570 git branch -a # list all branches
574 @node Checking out branches
575 @unnumberedsubsubsec Checking out branches
577 To know the currently checked out branch, i.e. the branch whose
578 source files are present in your working tree, read the first line
586 The currently checked out branch is also marked with an asterisk
587 in the output of @command{git branch}.
589 You can check out another branch @code{@var{other_branch}}, i.e.
590 check out @code{@var{other_branch}} to the working tree, by
594 git checkout @var{other_branch}
597 Note that it is possible to check out another branch while having
598 uncommitted changes, but it is not recommended unless you know
599 what you are doing; it is recommended to run @command{git status}
600 to check this kind of issue before checking out another branch.
602 @node Merging branches
603 @unnumberedsubsubsec Merging branches
605 To merge branch @code{@var{foo}} into branch @code{@var{bar}},
606 i.e. to @qq{add} all changes made in branch @code{@var{foo}} to
607 branch @code{@var{bar}}, run
610 git checkout @var{bar}
614 If any conflict happens, see @ref{Resolving conflicts}.
616 There are common usage cases for merging: as a translator, you
617 will often want to merge @code{master} into
618 @code{lilypond/translation}; on the other hand, the Translations
619 meister wants to merge @code{lilypond/translation} into
620 @code{master} whenever he has checked that
621 @code{lilypond/translation} builds successfully.
624 @node Commits and patches
625 @subsection Commits and patches
629 * Understanding commits::
636 @node Understanding commits
637 @unnumberedsubsubsec Understanding commits
639 Technically, a @emph{commit} is a single point in the history of a
640 branch, but most developers use the term to mean a @emph{commit
641 object}, which stores information about a particular revision. A
642 single commit can record changes to multiple source files, and
643 typically represents one logical set of related changes (such as a
644 bug-fix). You can list the ten most recent commits in your
645 current branch with this command:
648 git log -10 --oneline
651 If you're using an older version of Git and get an @q{unrecognized
652 argument} error, use this instead:
655 git log -10 --pretty=oneline --abbrev-commit
658 More interactive lists of the commits on the remote @code{master}
659 branch are available at
660 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=shortlog} and
661 @uref{http://git.sv.gnu.org/cgit/lilypond.git/log/}.
665 @unnumberedsubsubsec Making commits
668 Once you have modified some source files in your working
669 directory, you can make a commit with the following procedure:
673 Make sure you've configured Git properly (see @ref{Configuring
674 Git}). Check that your changes meet the requirements described in
675 @ref{Code style} and/or @ref{Documentation policy}. For advanced
676 edits, you may also want to verify that the changes don't break
677 the compilation process.
680 Run the following command:
687 to make sure you're on the right branch, and to see which files
688 have been modified, added or removed, etc. You may need to tell
689 Git about any files you've added by running one of these:
692 git add @var{file} # add untracked @var{file} individually
693 git add . # add all untracked files in current directory
697 After @command{git@tie{}add}, run @command{git@tie{}status} again
698 to make sure you got everything. You may also need to modify
702 Preview the changes about to be committed (to make sure everything
710 The @code{HEAD} argument refers to the most recent commit on the
711 currently checked-out branch.
714 Generate the commit with:
721 The @code{-a} is short for @code{--all} which includes modified
722 and deleted files, but only those newly created files that have
723 previously been added.
728 @node Commit messages
729 @unnumberedsubsubsec Commit messages
732 When you run the @command{git@tie{}commit@tie{}-a} command, Git
733 automatically opens the default text editor so you can enter a
734 @emph{commit message}. If you find yourself in a foreign editing
735 environment, you're probably in @command{vi} or @command{vim}. If
736 you want to switch to an editor you're more familiar with, quit by
737 typing @code{:q!} and pressing @code{<Enter>}. See
738 @ref{Configuring Git} for instructions on changing the default
741 In any case, Git will open a text file for your commit message
742 that looks like this:
746 # Please enter the commit message for your changes. Lines starting
747 # with '#' will be ignored, and an empty message aborts the commit.
749 # Changes to be committed:
750 # (use "git reset HEAD <file>..." to unstage)
752 # modified: working.itexi
756 Your commit message should begin with a one-line summary
757 describing the change (no more than 50 characters long), and if
758 necessary a blank line followed by several lines giving the
761 @c $ git log -1 --pretty=medium 4d6f1e5
763 Doc: add Baerenreiter and Henle solo cello suites
765 Added comparison of solo cello suite engravings to new essay with
766 high-res images, fixed cropping on Finale example.
769 Commit messages often start with a short prefix describing the
770 general location of the changes. If a commit affects the
771 documentation in English (or in several languages simultaneously)
772 the commit message should be prefixed with @qq{Doc:@tie{}}. If
773 the commit affects only one of the translations, the commit
774 message should be prefixed with @qq{Doc-@var{**}:@tie{}}, where
775 @var{**} is the two-letter language code. Commits that affect the
776 website should use @qq{Web:@tie{}} for English, and
777 @qq{Web-@var{**}:@tie{}} for the other languages. Also, changes
778 to a single file are often prefixed with the name of the file
779 involved. Visit the links listed in @ref{Understanding commits}
784 @unnumberedsubsubsec Making patches
787 If you want to share your changes with other contributors and
788 developers, you need to generate @emph{patches} from your commits.
789 You should always run @command{git@tie{}pull@tie{}-r} (translators
790 should leave off the @code{-r}) before doing this to ensure that
791 your patches are as current as possible.
793 Once you have made one or more commits in your local repository,
794 and pulled the most recent commits from the remote branch, you can
795 generate patches from your local commits with the command:
798 git format-patch origin
801 The @code{origin} argument refers to the remote tracking branch at
802 @code{git.sv.gnu.org}. This command generates a separate patch
803 for each commit that's in the current branch but not in the remote
804 branch. Patches are placed in the current working directory and
805 will have names that look something like this:
808 0001-Doc-Fix-typos.patch
809 0002-Web-Remove-dead-links.patch
813 Send an email to @email{lilypond-devel@@gnu.org} briefly
814 explaining your work, with the patch files attached. Translators
815 should send patches to @email{translations@@lilynet.net}. After
816 your patches are reviewed, the developers may push one or more of
817 them to the main repository or discuss them with you.
821 If your patch includes a significant amount of code, you may want
822 to see @ref{Adding or modifying features}, especially @emph{Post
826 @node Advanced Git procedures
827 @section Advanced Git procedures
830 @warning{This section is not necessary for normal contributors;
831 these commands are presented for information for people interested
832 in learning more about git.}
834 It is possible to work with several branches on the same local Git
835 repository; this is especially useful for translators who may have
836 to deal with both @code{lilypond/translation} and a stable branch,
837 e.g. @code{stable/2.12}.
839 Some Git commands are introduced first, then a workflow with
840 several Git branches of LilyPond source code is presented.
844 * Advanced Git concepts::
845 * Resolving conflicts::
846 * Reverting all local changes::
847 * Working with remote branches::
849 * Applying remote patches::
850 * Sending and receiving patches via email::
855 @node Advanced Git concepts
856 @subsection Advanced Git concepts
859 A bit of Git vocabulary will be explained below. The following is
860 only introductory; for a better understanding of Git concepts, you
861 may wish to read @ref{Other Git documentation}.
863 The @code{git@tie{}pull@tie{}origin} command above is just a
864 shortcut for this command:
867 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
871 where @code{@var{branch}} is typically @code{master} or
872 @code{lilypond/translation}; if you do not know or remember, see
873 @ref{Downloading remote branches} to remember which commands you
874 issued or which source code you wanted to get.
876 A @emph{commit} is a set of changes made to the sources; it also
877 includes the committish of the parent commit, the name and e-mail
878 of the @emph{author} (the person who wrote the changes), the name
879 and e-mail of the @emph{committer} (the person who brings these
880 changes into the Git repository), and a commit message.
882 A @emph{committish} is the SHA1 checksum of a commit, a number
883 made of 40 hexadecimal digits, which acts as the internal unique
884 identifier for this commit. To refer to a particular revision,
885 don't use vague references like the (approximative) date, simply
886 copy and paste the committish.
888 A @emph{branch} is nothing more than a pointer to a particular
889 commit, which is called the @emph{head} of the branch; when
890 referring to a branch, one often acutally thinks about its head
891 and the ancestor commits of the head.
893 Now we will explain the two last commands you used to get the
894 source code from Git---see @ref{Downloading individual branches}.
897 git remote add -ft @var{branch} -m @var{branch} \
898 origin git://git.sv.gnu.org/lilypond.git/
900 git checkout -b @var{branch} origin/@var{branch}
903 The @command{git@tie{}remote} has created a branch called
904 @code{origin/@var{branch}} in your local Git repository. As this
905 branch is a copy of the remote branch web from git.sv.gnu.org
906 LilyPond repository, it is called a @emph{remote branch}, and is
907 meant to track the changes on the branch from git.sv.gnu.org: it
908 will be updated every time you run
909 @command{git@tie{}pull@tie{}origin} or
910 @command{git@tie{}fetch@tie{}origin}.
912 The @command{git@tie{}checkout} command has created a branch named
913 @code{@var{branch}}. At the beginning, this branch is identical
914 to @code{origin/@var{branch}}, but it will differ as soon as you
915 make changes, e.g. adding newly translated pages or editing some
916 documentation or code source file. Whenever you pull, you merge
917 the changes from @code{origin/@var{branch}} and
918 @code{@var{branch}} since the last pulling. If you do not have
919 push (i.e. @qq{write}) access on git.sv.gnu.org, your
920 @code{@var{branch}} will always differ from
921 @code{origin/@var{branch}}. In this case, remember that other
922 people working like you with the remote branch @code{@var{branch}}
923 of git://git.sv.gnu.org/lilypond.git/ (called
924 @code{origin/@var{branch}} on your local repository) know nothing
925 about your own @code{@var{branch}}: this means that whenever you
926 use a committish or make a patch, others expect you to take the
927 latest commit of @code{origin/@var{branch}} as a reference.
929 Finally, please remember to read the man page of every Git command
930 you will find in this manual in case you want to discover
931 alternate methods or just understand how it works.
934 @node Resolving conflicts
935 @subsection Resolving conflicts
938 Occasionally an update may result in conflicts -- this happens
939 when you and somebody else have modified the same part of the same
940 file and git cannot figure out how to merge the two versions
941 together. When this happens, you must manually merge the two
944 If you need some documentation to understand and resolve
945 conflicts, see paragraphs @emph{How conflicts are presented} and
946 @emph{How to resolve conflicts} in @command{git merge} man page.
948 If all else fails, you can follow the instructions in
949 @ref{Reverting all local changes}. Be aware that this eliminates
950 any changes you have made!
953 @node Reverting all local changes
954 @subsection Reverting all local changes
956 Sometimes git will become hopelessly confused, and you just want
957 to get back to a known, stable state. This command destroys any
958 local changes you have made, but at least you get back to the
959 current online version:
962 git reset --hard origin/master
966 @node Working with remote branches
967 @subsection Working with remote branches
970 @subsubheading Fetching new branches from git.sv.gnu.org
972 To fetch and check out a new branch named @code{@var{branch}} on
973 git.sv.gnu.org, run from top of the Git repository
976 git config --add remote.origin.fetch \
977 +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
979 git checkout --track -b @var{branch} origin/@var{branch}
982 After this, you can pull @code{@var{branch}} from git.sv.gnu.org
989 Note that this command generally fetches all branches you added
990 with @command{git@tie{}remote@tie{}add} (when you initialized the
991 repository) or @command{git@tie{}config@tie{}--add}, i.e. it
992 updates all remote branches from remote @code{origin}, then it
993 merges the remote branch tracked by the current branch into the
994 current branch. For example, if your current branch is
995 @code{master}, @code{origin/master} will be merged into
999 @subsubheading Local clones, or having several working trees
1001 If you play with several Git branches, e.g. @code{master},
1002 @code{lilypond/translation}, @code{stable/2.12}), you may want to
1003 have one source and build tree for each branch; this is possible
1004 with subdirectories of your local Git repository, used as local
1005 cloned subrepositories. To create a local clone for the branch
1006 named @code{@var{branch}}, run
1009 git checkout @var{branch}
1010 git clone -lsn . @var{subdir}
1015 Note that @code{@var{subdir}} must be a directory name which does
1016 not already exist. In @code{@var{subdir}}, you can use all Git
1017 commands to browse revisions history, commit and uncommit changes;
1018 to update the cloned subrepository with changes made on the main
1019 repository, cd into @code{@var{subdir}} and run
1020 @command{git@tie{}pull}; to send changes made on the subrepository
1021 back to the main repository, run @command{git@tie{}push} from
1022 @code{@var{subdir}}. Note that only one branch (the currently
1023 checked out branch) is created in the subrepository by default; it
1024 is possible to have several branches in a subrepository and do
1025 usual operations (checkout, merge, create, delete...) on these
1026 branches, but this possibility is not detailed here.
1028 When you push @code{@var{branch}} from @code{@var{subdir}} to the
1029 main repository, and @code{@var{branch}} is checked out in the
1030 main repository, you must save uncommitted changes (see
1031 @command{git@tie{}stash}) and do
1032 @command{git@tie{}reset@tie{}--hard} in the main repository in
1033 order to apply pushed changes in the working tree of the main
1041 The commands above don't only bring you the latest version of the
1042 sources, but also the full history of revisions (revisons, also
1043 called commits, are changes made to the sources), stored in the
1044 @file{.git} directory. You can browse this history with
1047 git log # only shows the logs (author, committish and commit message)
1048 git log -p # also shows diffs
1049 gitk # shows history graphically
1052 @warning{The @code{gitk} command may require a separate
1053 @code{gitk} package, available in the appropriate distribution's
1057 @node Applying remote patches
1058 @subsection Applying remote patches
1061 FIXME: Explain how to determine if a patch was created with
1062 @code{git@tie{}format-patch}.
1064 Well-formed git patches created with @code{git@tie{}format-patch}
1065 should be committed with the following command:
1071 Patches created without @code{git@tie{}format-patch} can be
1072 applied in two steps. The first step is to apply the patch to the
1076 git apply @var{patch}
1080 The second step is to commit the changes and give credit to the
1081 author of the patch. This can be done with the following command:
1084 git commit -a --author="@var{John Smith} <@var{john@@example.com}>"
1088 @node Sending and receiving patches via email
1089 @subsection Sending and receiving patches via email
1092 The default @code{x-diff} MIME type associated with patch files
1093 (i.e., files whose name ends in @code{.patch}) means that the
1094 encoding of line endings may be changed from UNIX to DOS format
1095 when they are sent as attachments. Attempting to apply such an
1096 inadvertently altered patch will cause git to fail with a message
1097 about @q{whitespace errors}.
1099 The solution to such problems is surprisingly simple---just change
1100 the default file extension of patches generated by git to end in
1101 @code{.txt}, for example:
1104 git config format.suffix '.patch.txt'
1107 This should cause email programs to apply the correct base64
1108 encoding to attached patches.
1110 If you receive a patch with DOS instead of UNIX line-endings, it
1111 can be converted back using the @code{dos2unix} utility.
1113 Lots of useful information on email complications with patches is
1114 provided on the Wine wiki at
1115 @uref{http://wiki.winehq.org/GitWine}.
1119 @subsection Commit access
1122 Most contributors are not able to commit patches directly to the
1123 main repository---only members of the LilyPond development team
1124 have @emph{commit access}. If you are a contributor and are
1125 interested in joining the development team, contact the Project
1126 Manager through the mailing list
1127 (@email{lilypond-devel@@gnu.org}). Generally, only contributors
1128 who have already provided a number of patches which have been
1129 pushed to the main repository will be considered for membership.
1131 If you have been approved by the Project Manager, use the
1132 following procedure to obtain commit access:
1136 If you don't already have one, set up a Savannah user account at
1137 @uref{https://savannah.gnu.org/account/register.php}. If your web
1138 browser responds with an @qq{untrusted connection} message when
1139 you visit the link, follow the steps for including the CAcert root
1140 certificate in your browser, given at
1141 @uref{http://savannah.gnu.org/tls/tutorial/}.
1144 After registering, if you are not logged in automatically, login
1145 at @uref{https://savannah.gnu.org/account/login.php}---this should
1146 take you to your @qq{my} page
1147 (@uref{https://savannah.gnu.org/my/}).
1150 Click on the @qq{My Groups} link to access the @qq{My Group
1151 Membership} page. From there, find the @qq{Request for Inclusion}
1152 box and search for @qq{LilyPond}. Among the search results, check
1153 the box labeled @qq{GNU LilyPond Music Typesetter} and write a
1154 brief (required) message for the Project Manager (@qq{Hey it's
1155 me!} should be fine).
1157 Note that you will not have commit access until the Project
1158 Manager activates your membership. Once your membership is
1159 activated, LilyPond should appear under the heading @qq{Groups I'm
1160 Contributor of} on your @qq{My Group Membership} page.
1163 Go to the @qq{My Account Configuration} page. From there, click
1164 on @qq{Edit SSH Keys} and follow the instructions given.
1166 FIXME: Explain the confusing warning I always get. -mp
1168 FIXME: Maybe add a note about enabling/disabling SSH passphrase?
1171 Configure Git to use the SSH protocol (instead of the GIT
1172 protocol). From your local Git repository, enter:
1175 git config remote.origin.url \
1176 ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1180 where @var{user} is your username on Savannah.
1183 After your membership has been activated and you've configured Git
1184 to use SSH, try doing a @command{git@tie{}pull} or
1185 @command{git@tie{}pull@tie{}-r}. If that succeeds, this indicates
1186 that your SSH key stored at Savannah is working properly.
1188 FIXME: show what success/failure look like.
1191 Test your commit access with a dry run:
1194 git push --dry-run --verbose
1197 Note that recent versions of Git (Git 1.6.3 or later) will issue a
1198 big warning if the above command is used. The simplest solution
1199 is to tell Git to push all matching branches by default:
1202 git config push.default matching
1206 Then @code{git@tie{}push} should work as before. For more
1207 details, consult the @code{git@tie{}push} man page.
1211 @subsubheading Technical details
1215 On Firefox, to view or remove the CAcert root certificate, go to:
1216 Edit > Preferences > Advanced > Encryption > View Certificates >
1217 Authorities > Certificate Name > Root CA > CA Cert Signing
1221 The @command{git@tie{}config} commands above should modify your
1222 local repository's @file{.git/config} file. These lines:
1226 url = git://git.sv.gnu.org/lilypond.git/
1230 should now be changed to:
1234 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1238 where @var{user} is your login name on Savannah.
1242 @command{git@tie{}config@tie{}push.default@tie{}matching} command
1243 should add these lines to @file{.git/config}:
1251 @node Git on Windows
1252 @section Git on Windows
1254 @c Some of this may duplicate stuff in other sections
1255 @c But it is probably best for windows users to have it all together
1256 @c If necessary, clear this up later -td
1258 FIXME: Decide what to do with this... Pare it down? Move
1259 paragraphs next to analogous Unix instructions? -mp
1261 @subsection Background to nomenclature
1263 Git is a system for tracking the changes made to source files by a
1264 distributed set of editors. It is designed to work without a
1265 master repository, but we have chosen to have a master respository
1266 for LilyPond files. Editors hold a local copy of the master
1267 repository together with any changes they have made locally.
1268 Local changes are held in a local @q{branch}, of which there may
1269 be several, but these instructions assume you are using just one.
1270 The files visible in the local repository always correspond to
1271 those on the currently @q{checked out} local branch.
1273 Files are edited on a local branch, and in that state the changes
1274 are said to be @q{unstaged}. When editing is complete, the
1275 changes are moved to being @q{staged for commit}, and finally the
1276 changes are @q{committed} to the local branch. Once committed,
1277 the changes (called a @q{commit}) are given a unique 40-digit
1278 hexadecimal reference number called the @q{Committish} or @q{SHA1
1279 ID} which identifies the commit to Git. Such committed changes
1280 can be sent to the master repository by @q{pushing} them (if you
1281 have write permission) or by sending them by email to someone who
1282 has, either as a complete file or as a @q{diff} or @q{patch}
1283 (which send just the differences from the master repository).
1285 @subsection Installing git
1288 @uref{http://code.google.com/p/msysgit/downloads/list} (note, not
1289 msysGit, which is for Git developers and not PortableGit, which is
1290 not a full git installation) and install it.
1292 Note that most users will not need to install SSH. That is not
1293 required until you have been granted direct push permissions to
1294 the master git repository.
1296 Start Git by clicking on the desktop icon. This will bring up a
1297 command line bash shell. This may be unfamiliar to Windows users.
1298 If so, follow these instructions carefully. Commands are entered
1299 at a $ prompt and are terminated by keying a newline.
1301 @subsection Initialising Git
1303 Decide where you wish to place your local Git repository, creating
1304 the folders in Windows as necessary. Here we call the folder to
1305 contain the repository @code{[path]/Git}, but if you intend using
1306 Git for other projects a directory name like @code{lilypond-git}
1307 might be better. You will need to have space for around
1310 Start the Git bash shell by clicking on the desk-top icon
1311 installed with Git and type
1317 to position the shell at your new Git repository.
1319 Note: if [path] contains folders with names containing spaces use
1331 to initialize your Git repository.
1333 Then type (all on one line; the shell will wrap automatically)
1336 git remote add -ft master origin git://git.sv.gnu.org/lilypond.git
1339 to download the lilypond master files.
1341 @warning{Be patient! Even on a broadband connection this can take
1342 10 minutes or more. Wait for lots of [new tag] messages and the $
1345 We now need to generate a local copy of the downloaded files in a
1346 new local branch. Your local branch needs to have a name. It is
1347 usual to call it @q{master} and we shall do that here.
1352 git checkout -b master origin/master
1355 This creates a second branch called @q{master}. You will see two
1356 warnings (ignore these), and a message advising you that your
1357 local branch @q{master} has been set up to track the remote
1358 branch. You now have two branches, a local branch called
1359 @q{master}, and a tracking branch called @q{origin/master}, which
1360 is a shortened form of @q{remotes/origin/master}.
1362 Return to Windows Explorer and look in your Git repository. You
1363 should see lots of folders. For example, the LilyPond
1364 documentation can be found in [path]/Git/Documentation/.
1366 The Git bash shell is terminated by typing @code{exit} or by
1367 clicking on the usual Windows close-window widget.
1371 Almost all subsequent work will use the Git Graphical User
1372 Interface, which avoids having to type command line commands. To
1373 start Git GUI first start the Git bash shell by clicking on the
1374 desktop icon, and type
1381 The Git GUI will open in a new window. It contains four panels
1382 and 7 pull-down menus. At this stage do not use any of the
1383 commands under Branch, Commit, Merge or Remote. These will be
1386 The top panel on the left contains the names of files which you
1387 are in the process of editing (Unstaged Changes), and the lower
1388 panel on the left contains the names of files you have finished
1389 editing and have staged ready for committing (Staged Changes). At
1390 present, these panels will be empty as you have not yet made any
1391 changes to any file. After a file has been edited and saved the
1392 top panel on the right will display the differences between the
1393 edited file selected in one of the panels on the left and the last
1394 version committed on the current branch.
1396 The panel at bottom right is used to enter a descriptive message
1397 about the change before committing it.
1399 The Git GUI is terminated by entering CNTL-Q while it is the
1400 active window or by clicking on the usual Windows close-window
1403 @subsection Personalising your local git repository
1405 Open the Git GUI, click on
1411 and enter your name and email address in the left-hand (Git
1412 Repository) panel. Leave everything else unchanged and save it.
1414 Note that Windows users must leave the default setting for line
1415 endings unchanged. All files in a git repository must have lines
1416 terminated by just a LF, as this is required for Merge to work,
1417 but Windows files are terminated by CRLF by default. The git
1418 default setting causes the line endings of files in a Windows git
1419 repository to be flipped automatically between LF and CRLF as
1420 required. This enables files to be edited by any Windows editor
1421 without causing problems in the git repository.
1423 @subsection Checking out a branch
1425 At this stage you have two branches in your local repository,
1426 both identical. To see them click on
1432 You should have one local branch called @q{master} and one
1433 tracking branch called @q{origin/master}. The latter is your
1434 local copy of the @q{remotes/origin/master} branch in the master
1435 LilyPond repository. The local @q{master} branch is where you
1436 will make your local changes.
1438 When a particular branch is selected, i.e., checked out, the files
1439 visible in your repository are changed to reflect the state of the
1440 files on that branch.
1442 @subsection Updating files from @q{remote/origin/master}
1444 Before starting the editing of a file, ensure your local
1445 repository contains the latest version of the files in the remote
1446 repository by first clicking
1449 Remote -> Fetch from -> origin
1455 This will place the latest version of every file, including all
1456 the changes made by others, into the @q{origin/master} branch of
1457 the tracking branches in your git repository. You can see these
1458 files by checking out this branch, but you must @emph{never} edit
1459 any files while this branch is checked out. Check out your local
1460 @q{master} branch again.
1462 You then need to merge these fetched files into your local
1463 @q{master} branch by clicking on
1466 Merge -> Local Merge
1470 and if necessary select the local @q{master} branch.
1472 Note that a merge cannot be completed if you have made any local
1473 changes which have not yet been committed.
1475 This merge will update all the files in the @q{master} branch to
1476 reflect the current state of the @q{origin/master} branch. If any
1477 of the changes conflict with changes you have made yourself
1478 recently you will be notified of the conflict (see below).
1480 @subsection Editing files
1482 First ensure your @q{master} branch is checked out, then simply
1483 edit the files in your local Git repository with your favourite
1484 editor and save them back there. If any file contains non-ASCII
1485 characters ensure you save it in UTF-8 format. Git will detect
1486 any changes whenever you restart Git GUI and the file names will
1487 then be listed in the Unstaged Changes panel. Or you can click
1488 the Rescan button to refresh the panel contents at any time. You
1489 may break off and resume editing any time.
1491 The changes you have made may be displayed in diff form in the top
1492 right-hand panel of Git GUI by clicking on the file name shown in
1493 one of the left panels.
1495 When your editing is complete, move the files from being Unstaged
1496 to Staged by clicking the document symbol to the left of each
1497 name. If you change your mind it can be moved back by clicking on
1498 the ticked box to the left of the name.
1500 Finally the changes you have made may be committed to your
1501 @q{master} branch by entering a brief message in the Commit
1502 Message box and clicking the Commit button.
1504 If you wish to amend your changes after a commit has been made,
1505 the original version and the changes you made in that commit may
1506 be recovered by selecting
1509 Commit -> Amend Last Commit
1513 or by checking the Amend Last Commit radio button at bottom right.
1514 This will return the changes to the Staged state, so further
1515 editing made be carried out within that commit. This must only be
1516 done @emph{before} the changes have been Pushed or sent to your
1517 mentor for Pushing - after that it is too late and corrections
1518 have to be made as a separate commit.
1521 @subsection Sending changes to @q{remotes/origin/master}
1523 If you do not have write access to @q{remotes/origin/master} you
1524 will need to send your changes by email to someone who does.
1526 First you need to create a diff or patch file containing your
1527 changes. To create this, the file must first be committed. Then
1528 terminate the Git GUI. In the git bash shell first cd to your Git
1535 if necessary, then produce the patch with
1538 git format-patch origin
1541 This will create a patch file for all the locally committed files
1542 which differ from @q{origin/master}. The patch file can be found
1543 in [path]/Git and will have a name formed from the commit message.
1545 @subsection Resolving merge conflicts
1547 As soon as you have committed a changed file your local
1548 @code{master} branch has diverged from @code{origin/master}, and
1549 will remain diverged until your changes have been committed in
1550 @code{remotes/origin/master} and Fetched back into your
1551 @code{origin/master} branch. Similarly, if a new commit has been
1552 made to @code{remotes/origin/master} by someone else and Fetched,
1553 your local @code{master} branch is divergent. You can detect a
1554 divergent branch by clicking on
1557 Repository -> Visualise all branch history
1560 This opens up a very useful new window called @q{gitk}. Use this
1561 to browse all the commits made by yourself and others.
1563 If the diagram at top left of the resulting window does not show
1564 your @code{master} tag on the same node as the
1565 @code{remotes/origin/master} tag your branch has diverged from
1566 @code{origin/master}. This is quite normal if files you have
1567 modified yourself have not yet been Pushed to
1568 @code{remotes/origin/master} and Fetched, or if files modified and
1569 committed by others have been Fetched since you last Merged
1570 @code{origin/master} into your local @code{master} branch.
1572 If a file being merged from @code{origin/master} differs from one
1573 you have modified in a way that cannot be resolved automatically
1574 by git, Merge will report a Conflict which you must resolve by
1575 editing the file to create the version you wish to keep.
1577 This could happen if the person updating
1578 @code{remotes/origin/master} for you has added some changes of his
1579 own before committing your changes to
1580 @code{remotes/origin/master}, or if someone else has changed the
1581 same file since you last fetched the file from
1582 @code{remotes/origin/master}.
1584 Open the file in your editor and look for sections which are
1587 [to be completed when I next have a merge conflict to be sure I
1588 give the right instructions -td]
1591 @subsection Other actions
1593 The instructions above describe the simplest way of using git on
1594 Windows. Other git facilities which may usefully supplement these
1598 @item Using multiple local branches (Create, Rename, Delete)
1599 @item Resetting branches
1600 @item Cherry-picking commits
1601 @item Pushing commits to @w{remote/origin/master}
1602 @item Using gitk to review history
1605 Once familiarity with using git on Windows has been gained the
1606 standard git manuals can be used to learn about these.
1609 @node Repository directory structure
1610 @section Repository directory structure
1613 @c TODO: integrate the roadmap better
1614 @verbatiminclude ROADMAP
1617 @node Other Git documentation
1618 @section Other Git documentation
1622 Official git man pages:
1623 @uref{http://www.kernel.org/pub/software/scm/git/docs/}
1626 More in-depth tutorials: @uref{http://git-scm.com/documentation}
1629 Book about git: @uref{http://progit.org/,Pro Git}