1 @c -*- coding: utf-8; mode: texinfo; -*-
4 @node Working with source code
5 @chapter Working with source code
9 * Downloading the source code as an archive::
12 * Basic Git procedures::
13 * Advanced Git procedures::
15 * Repository directory structure::
16 * Other Git documentation::
20 @node Downloading the source code as an archive
21 @section Downloading the source code as an archive
24 An easy way to get the complete source code is to download it
25 as a @qq{tarball} archive, that can be extracted on any operating
26 system (Windows users may have to download and install the free-software
27 @uref{http://www.7-zip.org, 7zip archiver} to extract it.
29 Such a tarball is directly available on the LilyPond website: see
30 @rweb{Source}. This source code matches the proposed binaries on
31 the same page (i.e. the latest stable or development release).
33 Another way to retrieve the latest LilyPond snapshot from its
34 GNU Savannah Git server is to click on the following link:
35 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=snapshot}.
37 However, please note that this will not allow you to submit your
38 modifications to the code in a proper way. Therefore the recommended
39 way of getting the source code (alongside with its complete history log)
40 is by using Git, as explained in this section.
44 @section Using lily-git
47 If you haven't already, download and install Git. Go to
48 @uref{http://git-scm.com/download}, and in the @qq{Binaries}
49 section, select the appropriate package for your operating system.
50 Windows users should visit
51 @uref{http://code.google.com/p/msysgit/downloads/list} and
52 download the @file{.exe} file labeled @qq{Full installer for
55 Download the lily-git script from:
57 @c don't change the cgit link below to gitweb; gitweb uses
58 @c long filenames like "scripts_auxiliar_lily-git.tcl"
61 @uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
64 To run the program from the command line, navigate to the
65 directory containing @file{lily-git.tcl} and enter:
72 @subsubheading Get source / Update source
74 When you click the @qq{Get source} button, @command{lily-git} will
75 create a directory called @file{lilypond-git/} within your home
76 directory, and will download the complete source code into that
77 directory (around 55Mb). When the process is finished, the
78 @qq{Command output} window will display @qq{Done}, and the button
79 label will change to say @qq{Update source}.
81 Navigate to the @file{lilypond-git/} directory to view the source
82 files. You should now be able to modify the source files using
83 your normal text editor.
87 The @qq{Get source} button does not fetch the entire history of
88 the git repository, so utilities like @command{gitk} will only
89 be able to display the most recent additions. As you continue to
90 work with @command{lily-git}, the @qq{Update source} button will take
91 any new additions and add it to whatever is currently in your repository's
95 @subsubheading New local commit
97 A single commit typically represents one logical set of related
98 changes (such as a bug-fix), and may incorporate changes to
99 multiple files at the same time.
101 When you're finished making the changes for your first commit,
102 click the @qq{New local commit} button. This will open the
103 @qq{Git Commit Message} window. The message header is required,
104 and the message body is optional. See @ref{Commits and patches}
105 for more information regarding commits and commit messages.
107 After entering a commit message, click @qq{OK} to finalize the
111 @subsubheading Amend previous commit
113 You can go back and make changes to the most recent commit with
114 the @qq{Amend previous commit} button. This is useful if a
115 mistake is found after you have clicked the @qq{New local commit}
118 To amend the most recent commit, re-edit the source files as
119 needed and then click the @qq{Amend previous commit} button. The
120 earlier version of the commit is not saved, but is replaced by the
123 Note that this does not update the patch @strong{files}; if you
124 have a patch file from an earlier version of the commit, you will
125 need to make another patch set when using this feature. The old
126 patch file will not be saved, but will be replaced by the new one
127 after you click on @qq{Make patch set}.
130 @subsubheading Make patch set
132 Before making a patch set from any commits, you should click the
133 @qq{Update source} button to make sure the commits are based on
134 the most recent remote snapshot.
136 When you click the @qq{Make patch set} button, @command{lily-git}
137 will produce patch files for any new commits, saving them to the
138 current directory. The command output will display the name of
139 the new patch files near the end of the output:
142 0001-CG-add-lily-git-instructions.patch
146 Send patch files to your mentor if you have one. Otherwise, write
147 an email (must be less than 64 KB) to
148 @email{lilypond-devel@@gnu.org} briefly explaining your work, with
149 the patch files attached. Translators should send patches to
150 @email{translations@@lilynet.net}.
153 @subsubheading The @qq{Abort changes -- Reset to origin} button
155 @warning{Only use this if your local commit history gets
156 hopelessly confused!}
158 The button labeled @qq{Abort changes -- Reset to origin} will copy
159 all changed files to a subdirectory of @file{lilypond-git/} named
160 @file{aborted_edits/}, and will reset the repository to the
161 current state of the remote repository (at @code{git.sv.gnu.org}).
164 @node Starting with Git
165 @section Starting with Git
168 Using the Git program directly (as opposed to using the
169 @command{lily-git} GUI) allows you to have much greater control
170 over the contributing process. You should consider using Git if
171 you want to work on complex projects, or if you want to work on
172 multiple projects concurrently.
177 * Downloading remote branches::
182 @subsection Setting up
185 TODO: Remove this note if incorporating Windows instructions
186 throughout this section:
188 @warning{These instructions assume that you are using the
189 command-line version of Git 1.5 or higher. Windows users should
190 skip to @ref{Git on Windows}.}
194 * Initializing a repository::
200 @unnumberedsubsubsec Installing Git
203 If you are using a Unix-based machine, the easiest way to download
204 and install Git is through a package manager such as @command{rpm}
205 or @command{apt-get}---the installation is generally automatic.
206 The only required package is (usually) called @command{git-core},
207 although some of the auxiliary @command{git@var{*}} packages are
208 also useful (such as @command{gitk}).
210 Alternatively, you can visit the Git website
211 (@uref{http://git-scm.com/}) for downloadable binaries and
214 TODO: add Windows installation instructions (or @@ref@{Git on
218 @node Initializing a repository
219 @unnumberedsubsubsec Initializing a repository
222 Once Git is installed, you'll need to create a new directory where
223 your initial repository will be stored (the example below uses
224 @file{~/lilypond-git/}, where @code{~} represents your home
225 directory). Run @command{git@tie{}init} from within the new
226 directory to initialize an empty repository:
229 mkdir ~/lilypond-git/; cd ~/lilypond-git/
233 @subsubheading Technical details
235 This creates (within the @file{~/lilypond-git/} directory) a
236 subdirectory called @file{.git/}, which Git uses to keep track of
237 changes to the repository, among other things. Normally you don't
238 need to access it, but it's good to know it's there.
241 @node Configuring Git
242 @unnumberedsubsubsec Configuring Git
244 @warning{Throughout the rest of this manual, all command-line
245 input should be entered from the top directory of the Git
246 repository being discussed (eg. @file{~/lilypond-git/}). This is
247 referred to as a @emph{top source directory}.}
249 Before downloading a copy of the main LilyPond repository, you
250 should configure some basic settings with the
251 @command{git@tie{}config} command. Git allows you to set both
252 global and repository-specific options.
254 To configure settings that affect all repositories, use the
255 @command{--global} command line option. For example, the first
256 two options that you should always set are your @var{name} and
257 @var{email}, since Git needs these to keep track of commit
261 git config --global user.name "@var{John Smith}"
262 git config --global user.email @var{john@@example.com}
265 To configure Git to use colored output where possible, use:
268 git config --global color.ui auto
271 The text editor that opens when using @command{git@tie{}commit}
272 can also be changed. If none of your editor-related environment
273 variables are set ($GIT_EDITOR, $VISUAL, or $EDITOR), the default
274 editor is usually @command{vi} or @command{vim}. If you're not
275 familiar with either of these, you should probably change the
276 default to an editor that you know how to use. For example, to
277 change the default editor to @command{nano}, enter:
280 git config --global core.editor @var{nano}
283 TODO: Add instructions for changing the editor on Windows, which
284 is a little different, I think. -mp
286 @subsubheading Technical details
288 Git stores the information entered with
289 @command{git@tie{}config@tie{}--global} in the file
290 @file{.gitconfig}, located in your home directory. This file can
291 also be modified directly, without using
292 @command{git@tie{}config}. The @file{.gitconfig} file generated
293 by the above commands would look like this:
298 email = john@@example.com
305 Using the @command{git@tie{}config} command @emph{without} the
306 @command{--global} option configures repository-specific settings,
307 which are stored in the file @file{.git/config}. This file is
308 created when a repository is initialized (using
309 @command{git@tie{}init}), and by default contains these lines:
313 repositoryformatversion = 0
316 logallrefupdates = true
319 However, since different repository-specific options are
320 recommended for different development tasks, it is best to avoid
321 setting any now. Specific recommendations will be mentioned later
325 @node Downloading remote branches
326 @subsection Downloading remote branches
330 * Organization of remote branches::
331 * LilyPond repository sources::
332 * Downloading individual branches::
333 * Downloading all remote branches::
338 @node Organization of remote branches
339 @unnumberedsubsubsec Organization of remote branches
342 The main LilyPond repository is organized into @emph{branches} to
343 facilitate development. These are often called @emph{remote}
344 branches to distinguish them from @emph{local} branches you might
345 create yourself (see @ref{Using local branches}).
347 The @code{master} branch contains all the source files used to
348 build LilyPond, which includes the program itself (both stable and
349 development releases), the documentation (and its translations),
350 and the website. Generally, the @code{master} branch is expected
351 to compile successfully.
353 The @code{lilypond/translation} branch is a side branch that
354 allows translators to work without needing to worry about
355 compilation problems. Periodically, the Translation Meister
356 (after verifying that it doesn't break compilation), will
357 @emph{merge} this branch back into @code{master} to incorporate
358 recent translations. Similarly, the @code{master} branch is
359 usually merged into the @code{lilypond/translation} branch after
360 significant changes to the English documentation. See
361 @ref{Translating the documentation} for details.
364 @node LilyPond repository sources
365 @unnumberedsubsubsec LilyPond repository sources
368 The recommended source for downloading a copy of the main
372 git://git.sv.gnu.org/lilypond.git
375 However, if your internet router filters out connections using the
376 GIT protocol, or if you experience difficulty connecting via GIT,
377 you can try these other sources:
380 ssh://git.sv.gnu.org/srv/git/lilypond.git
381 http://git.sv.gnu.org/r/lilypond.git
384 The SSH protocol can only be used if your system is properly set
385 up to use it. Also, the HTTP protocol is slowest, so it should
386 only be used as a last resort.
389 @node Downloading individual branches
390 @unnumberedsubsubsec Downloading individual branches
393 Once you have initialized an empty Git repository on your system
394 (see @ref{Initializing a repository}), you can download a remote
395 branch into it. Make sure you know which branch you want to start
398 To download the @code{master} branch, enter the following:
401 git remote add -ft master -m master \
402 origin git://git.sv.gnu.org/lilypond.git/
405 To download the @code{lilypond/translation} branch, enter:
408 git remote add -ft lilypond/translation -m \
409 lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
412 The @command{git@tie{}remote@tie{}add} process could take up to
413 ten minutes, depending on the speed of your connection. The
414 output will be something like this:
418 remote: Counting objects: 235967, done.
419 remote: Compressing objects: 100% (42721/42721), done.
420 remote: Total 235967 (delta 195098), reused 233311 (delta 192772)
421 Receiving objects: 100% (235967/235967), 68.37 MiB | 479 KiB/s, done.
422 Resolving deltas: 100% (195098/195098), done.
423 From git://git.sv.gnu.org/lilypond
424 * [new branch] master -> origin/master
425 From git://git.sv.gnu.org/lilypond
426 * [new tag] flower/1.0.1 -> flower/1.0.1
427 * [new tag] flower/1.0.10 -> flower/1.0.10
429 * [new tag] release/2.9.6 -> release/2.9.6
430 * [new tag] release/2.9.7 -> release/2.9.7
433 When @command{git@tie{}remote@tie{}add} is finished, the remote
434 branch should be downloaded into your repository---though not yet
435 in a form that you can use. In order to browse the source code
436 files, you need to @emph{create} and @emph{checkout} your own
437 local branch. In this case, however, it is easier to have Git
438 create the branch automatically by using the @command{checkout}
439 command on a non-existent branch. Enter the following:
442 git checkout -b @var{branch} origin/@var{branch}
446 where @code{@var{branch}} is the name of your tracking branch,
447 either @code{master} or @code{lilypond/translation}.
449 Git will issue some warnings; this is normal:
452 warning: You appear to be on a branch yet to be born.
453 warning: Forcing checkout of origin/master.
454 Branch master set up to track remote branch master from origin.
458 By now the source files should be accessible---you should be able
459 to edit any files in the @file{lilypond-git/} directory using a
460 text editor of your choice. But don't start just yet! Before
461 editing any source files, learn how to keep your changes organized
462 and prevent problems later---read @ref{Basic Git procedures}.
464 @subsubheading Technical Details
466 The @command{git@tie{}remote@tie{}add} command should add some
467 lines to your local repository's @file{.git/config} file:
471 url = git://git.sv.gnu.org/lilypond.git/
472 fetch = +refs/heads/master:refs/remotes/origin/master
476 @node Downloading all remote branches
477 @unnumberedsubsubsec Downloading all remote branches
480 To download all remote branches at once, you can @command{clone}
481 the entire repository:
484 git clone git://git.sv.gnu.org/lilypond.git
489 @unnumberedsubsubsec Other branches
491 Most contributors will never need to touch the other branches. If
492 you wish to do so, you will need more familiarity with Git; please
493 see @ref{Other Git documentation}.
496 @item @code{dev/XYZ}:
497 These branches are for individual developers. They store code
498 which is not yet stable enough to be added to the @code{master}
501 @item @code{stable/XYZ}:
502 The branches are kept for archival reasons.
506 Another item of interest might be the Grand Unified Builder, our
507 cross-platform building tool. Since it is used by projects as
508 well, it is not stored in our gub repository. For more info, see
509 @uref{http://lilypond.org/gub}. The git location is
510 @uref{http://github.com/janneke/gub}.
513 @node Basic Git procedures
514 @section Basic Git procedures
518 * The Git contributor's cycle::
519 * Pulling and rebasing::
520 * Using local branches::
521 * Commits and patches::
525 @node The Git contributor's cycle
526 @subsection The Git contributor's cycle
529 Here is a simplified view of the contribution process on Git:
533 Update your local repository by @emph{pulling} the most recent
534 updates from the remote repository.
537 Edit source files within your local repository's @emph{working
541 @emph{Commit} the changes you've made to a local @emph{branch}.
544 Generate a @emph{patch} to share your changes with the developers.
548 @node Pulling and rebasing
549 @subsection Pulling and rebasing
552 When developers push new patches to the @code{git.sv.gnu.org}
553 repository, your local repository is @strong{not} automatically
554 updated. It is important to keep your repository up-to-date by
555 periodically @emph{pulling} the most recent @emph{commits} from
556 the remote branch. Developers expect patches to be as current as
557 possible, since outdated patches require extra work before they
560 Occasionally you may need to rework some of your own modifications
561 to match changes made to the remote branch (see @ref{Resolving
562 conflicts}), and it's considerably easier to rework things
563 incrementally. If you don't update your repository along the way,
564 you may have to spend a lot of time resolving branch conflicts and
565 reconfiguring much of the work you've already done.
567 Fortunately, Git is able to resolve certain types of branch
568 conflicts automatically with a process called @emph{rebasing}.
569 When rebasing, Git tries to modify your old commits so they appear
570 as new commits (based on the latest updates). For a more involved
571 explanation, see the @command{git-rebase} man page.
573 To pull without rebasing (recommended for translators), use the
577 git pull # recommended for translators
580 If you're tracking the remote @code{master} branch, you should add
581 the @code{-r} option (short for @code{--rebase}) to keep commits
582 on your local branch current:
585 git pull -r # use with caution when translating
588 If you don't edit translated documentation and don't want to type
589 @code{-r} every time, configure the master branch to rebase by
590 default with this command:
593 git config branch.master.rebase true
596 If pull fails because of a message like
599 error: Your local changes to 'Documentation/learning/tutorial.itely'
600 would be overwritten by merge. Aborting.
607 Documentation/learning/tutorial.itely: needs update
608 refusing to pull with rebase: your working tree is not up-to-date
612 it means that you have modified some files in you working tree
613 without committing changes (see @ref{Commits and patches}); you
614 can use the @command{git@tie{}stash} command to work around this:
617 git stash # save uncommitted changes
618 git pull -r # pull using rebase (translators omit "-r")
619 git stash pop # reapply previously saved changes
622 Note that @command{git@tie{}stash@tie{}pop} will try to apply a
623 patch, and this may create a conflict. If this happens, see
624 @ref{Resolving conflicts}.
626 TODO: I think the next paragraph is confusing. Perhaps prepare
627 the reader for new terms `committish' and `head'? -mp
629 @warning{translators and documentation editors, if you have
630 changed committishes in the head of translated files using commits
631 you have not yet pushed to @code{git.sv.gnu.org}, please do not
632 rebase. If you want to avoid wondering whether you should rebase
633 each time you pull, please always use committishes from master
634 and/or lilypond/translation branch on @code{git.sv.gnu.org}, which
635 in particular implies that you must push your changes to
636 documentation except committishes updates (possibly after having
637 rebased), then update the committishes and push them.}
639 TODO: when committishes automatic conditional update have been
640 tested and documented, append the following to the warning above:
641 Note that using update-committishes make target generally touches
644 @subsubheading Technical details
646 The @command{git@tie{}config} command mentioned above adds the
647 line @code{rebase = true} to the master branch in your local
648 repository's @file{.git/config} file:
653 merge = refs/heads/master
658 @node Using local branches
659 @subsection Using local branches
663 * Creating and removing branches::
664 * Listing branches and remotes::
665 * Checking out branches::
670 @node Creating and removing branches
671 @unnumberedsubsubsec Creating and removing branches
674 Local branches are useful when you're working on several different
675 projects concurrently. To create a new branch, enter:
678 git branch @var{name}
681 To delete a branch, enter:
684 git branch -d @var{name}
687 Git will ask you for confirmation if it sees that data would be
688 lost by deleting the branch. Use @code{-D} instead of @code{-d}
689 to bypass this. Note that you cannot delete a branch if it is
690 currently checked out.
693 @node Listing branches and remotes
694 @unnumberedsubsubsec Listing branches and remotes
696 You can get the exact path or URL of all remote branches by
703 To list Git branches on your local repositories, run
706 git branch # list local branches only
707 git branch -r # list remote branches
708 git branch -a # list all branches
712 @node Checking out branches
713 @unnumberedsubsubsec Checking out branches
715 To know the currently checked out branch, i.e. the branch whose
716 source files are present in your working tree, read the first line
724 The currently checked out branch is also marked with an asterisk
725 in the output of @command{git branch}.
727 You can check out another branch @code{@var{other_branch}}, i.e.
728 check out @code{@var{other_branch}} to the working tree, by
732 git checkout @var{other_branch}
735 Note that it is possible to check out another branch while having
736 uncommitted changes, but it is not recommended unless you know
737 what you are doing; it is recommended to run @command{git status}
738 to check this kind of issue before checking out another branch.
740 @node Merging branches
741 @unnumberedsubsubsec Merging branches
743 To merge branch @code{@var{foo}} into branch @code{@var{bar}},
744 i.e. to @qq{add} all changes made in branch @code{@var{foo}} to
745 branch @code{@var{bar}}, run
748 git checkout @var{bar}
752 If any conflict happens, see @ref{Resolving conflicts}.
754 There are common usage cases for merging: as a translator, you
755 will often want to merge @code{master} into
756 @code{lilypond/translation}; on the other hand, the Translations
757 meister wants to merge @code{lilypond/translation} into
758 @code{master} whenever he has checked that
759 @code{lilypond/translation} builds successfully.
762 @node Commits and patches
763 @subsection Commits and patches
767 * Understanding commits::
774 @node Understanding commits
775 @unnumberedsubsubsec Understanding commits
777 Technically, a @emph{commit} is a single point in the history of a
778 branch, but most developers use the term to mean a @emph{commit
779 object}, which stores information about a particular revision. A
780 single commit can record changes to multiple source files, and
781 typically represents one logical set of related changes (such as a
782 bug-fix). You can list the ten most recent commits in your
783 current branch with this command:
786 git log -10 --oneline
789 If you're using an older version of Git and get an @q{unrecognized
790 argument} error, use this instead:
793 git log -10 --pretty=oneline --abbrev-commit
796 More interactive lists of the commits on the remote @code{master}
797 branch are available at
798 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=shortlog} and
799 @uref{http://git.sv.gnu.org/cgit/lilypond.git/log/}.
803 @unnumberedsubsubsec Making commits
806 Once you have modified some source files in your working
807 directory, you can make a commit with the following procedure:
811 Make sure you've configured Git properly (see @ref{Configuring
812 Git}). Check that your changes meet the requirements described in
813 @ref{Code style} and/or @ref{Documentation policy}. For advanced
814 edits, you may also want to verify that the changes don't break
815 the compilation process.
818 Run the following command:
825 to make sure you're on the right branch, and to see which files
826 have been modified, added or removed, etc. You may need to tell
827 Git about any files you've added by running one of these:
830 git add @var{file} # add untracked @var{file} individually
831 git add . # add all untracked files in current directory
835 After @command{git@tie{}add}, run @command{git@tie{}status} again
836 to make sure you got everything. You may also need to modify
840 Preview the changes about to be committed (to make sure everything
848 The @code{HEAD} argument refers to the most recent commit on the
849 currently checked-out branch.
852 Generate the commit with:
859 The @code{-a} is short for @code{--all} which includes modified
860 and deleted files, but only those newly created files that have
861 previously been added.
866 @node Commit messages
867 @unnumberedsubsubsec Commit messages
870 When you run the @command{git@tie{}commit@tie{}-a} command, Git
871 automatically opens the default text editor so you can enter a
872 @emph{commit message}. If you find yourself in a foreign editing
873 environment, you're probably in @command{vi} or @command{vim}. If
874 you want to switch to an editor you're more familiar with, quit by
875 typing @code{:q!} and pressing @code{<Enter>}. See
876 @ref{Configuring Git} for instructions on changing the default
879 In any case, Git will open a text file for your commit message
880 that looks like this:
884 # Please enter the commit message for your changes. Lines starting
885 # with '#' will be ignored, and an empty message aborts the commit.
887 # Changes to be committed:
888 # (use "git reset HEAD <file>..." to unstage)
890 # modified: working.itexi
894 Your commit message should begin with a one-line summary
895 describing the change (no more than 50 characters long), and if
896 necessary a blank line followed by several lines giving the
899 @c $ git log -1 --pretty=medium 4d6f1e5
901 Doc: add Baerenreiter and Henle solo cello suites
903 Added comparison of solo cello suite engravings to new essay with
904 high-res images, fixed cropping on Finale example.
907 Commit messages often start with a short prefix describing the
908 general location of the changes. If a commit affects the
909 documentation in English (or in several languages simultaneously)
910 the commit message should be prefixed with @qq{Doc:@tie{}}. If
911 the commit affects only one of the translations, the commit
912 message should be prefixed with @qq{Doc-@var{**}:@tie{}}, where
913 @var{**} is the two-letter language code. Commits that affect the
914 website should use @qq{Web:@tie{}} for English, and
915 @qq{Web-@var{**}:@tie{}} for the other languages. Also, changes
916 to a single file are often prefixed with the name of the file
917 involved. Visit the links listed in @ref{Understanding commits}
922 @unnumberedsubsubsec Making patches
925 If you want to share your changes with other contributors and
926 developers, you need to generate @emph{patches} from your commits.
927 You should always run @command{git@tie{}pull@tie{}-r} (translators
928 should leave off the @code{-r}) before doing this to ensure that
929 your patches are as current as possible.
931 Once you have made one or more commits in your local repository,
932 and pulled the most recent commits from the remote branch, you can
933 generate patches from your local commits with the command:
936 git format-patch origin
939 The @code{origin} argument refers to the remote tracking branch at
940 @code{git.sv.gnu.org}. This command generates a separate patch
941 for each commit that's in the current branch but not in the remote
942 branch. Patches are placed in the current working directory and
943 will have names that look something like this:
946 0001-Doc-Fix-typos.patch
947 0002-Web-Remove-dead-links.patch
951 Send an email (must be less than 64 KB) to
952 @email{lilypond-devel@@gnu.org} briefly explaining your work, with
953 the patch files attached. Translators should send patches to
954 @email{translations@@lilynet.net}. After your patches are
955 reviewed, the developers may push one or more of them to the main
956 repository or discuss them with you.
960 If your patch includes a significant amount of code, you may want
961 to see @ref{Adding or modifying features}, especially @emph{Post
965 @node Advanced Git procedures
966 @section Advanced Git procedures
969 @warning{This section is not necessary for normal contributors;
970 these commands are presented for information for people interested
971 in learning more about git.}
973 It is possible to work with several branches on the same local Git
974 repository; this is especially useful for translators who may have
975 to deal with both @code{lilypond/translation} and a stable branch,
976 e.g. @code{stable/2.12}.
978 Some Git commands are introduced first, then a workflow with
979 several Git branches of LilyPond source code is presented.
983 * Advanced Git concepts::
984 * Resolving conflicts::
985 * Reverting all local changes::
986 * Working with remote branches::
988 * Applying remote patches::
989 * Sending and receiving patches via email::
994 @node Advanced Git concepts
995 @subsection Advanced Git concepts
998 A bit of Git vocabulary will be explained below. The following is
999 only introductory; for a better understanding of Git concepts, you
1000 may wish to read @ref{Other Git documentation}.
1002 The @code{git@tie{}pull@tie{}origin} command above is just a
1003 shortcut for this command:
1006 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
1010 where @code{@var{branch}} is typically @code{master} or
1011 @code{lilypond/translation}; if you do not know or remember, see
1012 @ref{Downloading remote branches} to remember which commands you
1013 issued or which source code you wanted to get.
1015 A @emph{commit} is a set of changes made to the sources; it also
1016 includes the committish of the parent commit, the name and e-mail
1017 of the @emph{author} (the person who wrote the changes), the name
1018 and e-mail of the @emph{committer} (the person who brings these
1019 changes into the Git repository), and a commit message.
1021 A @emph{committish} is the SHA1 checksum of a commit, a number
1022 made of 40 hexadecimal digits, which acts as the internal unique
1023 identifier for this commit. To refer to a particular revision,
1024 don't use vague references like the (approximative) date, simply
1025 copy and paste the committish.
1027 A @emph{branch} is nothing more than a pointer to a particular
1028 commit, which is called the @emph{head} of the branch; when
1029 referring to a branch, one often acutally thinks about its head
1030 and the ancestor commits of the head.
1032 Now we will explain the two last commands you used to get the
1033 source code from Git---see @ref{Downloading individual branches}.
1036 git remote add -ft @var{branch} -m @var{branch} \
1037 origin git://git.sv.gnu.org/lilypond.git/
1039 git checkout -b @var{branch} origin/@var{branch}
1042 The @command{git@tie{}remote} has created a branch called
1043 @code{origin/@var{branch}} in your local Git repository. As this
1044 branch is a copy of the remote branch web from git.sv.gnu.org
1045 LilyPond repository, it is called a @emph{remote branch}, and is
1046 meant to track the changes on the branch from git.sv.gnu.org: it
1047 will be updated every time you run
1048 @command{git@tie{}pull@tie{}origin} or
1049 @command{git@tie{}fetch@tie{}origin}.
1051 The @command{git@tie{}checkout} command has created a branch named
1052 @code{@var{branch}}. At the beginning, this branch is identical
1053 to @code{origin/@var{branch}}, but it will differ as soon as you
1054 make changes, e.g. adding newly translated pages or editing some
1055 documentation or code source file. Whenever you pull, you merge
1056 the changes from @code{origin/@var{branch}} and
1057 @code{@var{branch}} since the last pulling. If you do not have
1058 push (i.e. @qq{write}) access on git.sv.gnu.org, your
1059 @code{@var{branch}} will always differ from
1060 @code{origin/@var{branch}}. In this case, remember that other
1061 people working like you with the remote branch @code{@var{branch}}
1062 of git://git.sv.gnu.org/lilypond.git/ (called
1063 @code{origin/@var{branch}} on your local repository) know nothing
1064 about your own @code{@var{branch}}: this means that whenever you
1065 use a committish or make a patch, others expect you to take the
1066 latest commit of @code{origin/@var{branch}} as a reference.
1068 Finally, please remember to read the man page of every Git command
1069 you will find in this manual in case you want to discover
1070 alternate methods or just understand how it works.
1073 @node Resolving conflicts
1074 @subsection Resolving conflicts
1077 Occasionally an update may result in conflicts -- this happens
1078 when you and somebody else have modified the same part of the same
1079 file and git cannot figure out how to merge the two versions
1080 together. When this happens, you must manually merge the two
1083 If you need some documentation to understand and resolve
1084 conflicts, see paragraphs @emph{How conflicts are presented} and
1085 @emph{How to resolve conflicts} in @command{git merge} man page.
1087 If all else fails, you can follow the instructions in
1088 @ref{Reverting all local changes}. Be aware that this eliminates
1089 any changes you have made!
1092 @node Reverting all local changes
1093 @subsection Reverting all local changes
1095 Sometimes git will become hopelessly confused, and you just want
1096 to get back to a known, stable state. This command destroys any
1097 local changes you have made, but at least you get back to the
1098 current online version:
1101 git reset --hard origin/master
1105 @node Working with remote branches
1106 @subsection Working with remote branches
1109 @subsubheading Fetching new branches from git.sv.gnu.org
1111 To fetch and check out a new branch named @code{@var{branch}} on
1112 git.sv.gnu.org, run from top of the Git repository
1115 git config --add remote.origin.fetch \
1116 +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
1118 git checkout --track -b @var{branch} origin/@var{branch}
1121 After this, you can pull @code{@var{branch}} from git.sv.gnu.org
1128 Note that this command generally fetches all branches you added
1129 with @command{git@tie{}remote@tie{}add} (when you initialized the
1130 repository) or @command{git@tie{}config@tie{}--add}, i.e. it
1131 updates all remote branches from remote @code{origin}, then it
1132 merges the remote branch tracked by the current branch into the
1133 current branch. For example, if your current branch is
1134 @code{master}, @code{origin/master} will be merged into
1138 @subsubheading Local clones, or having several working trees
1140 If you play with several Git branches, e.g. @code{master},
1141 @code{lilypond/translation}, @code{stable/2.12}), you may want to
1142 have one source and build tree for each branch; this is possible
1143 with subdirectories of your local Git repository, used as local
1144 cloned subrepositories. To create a local clone for the branch
1145 named @code{@var{branch}}, run
1148 git checkout @var{branch}
1149 git clone -lsn . @var{subdir}
1154 Note that @code{@var{subdir}} must be a directory name which does
1155 not already exist. In @code{@var{subdir}}, you can use all Git
1156 commands to browse revisions history, commit and uncommit changes;
1157 to update the cloned subrepository with changes made on the main
1158 repository, cd into @code{@var{subdir}} and run
1159 @command{git@tie{}pull}; to send changes made on the subrepository
1160 back to the main repository, run @command{git@tie{}push} from
1161 @code{@var{subdir}}. Note that only one branch (the currently
1162 checked out branch) is created in the subrepository by default; it
1163 is possible to have several branches in a subrepository and do
1164 usual operations (checkout, merge, create, delete...) on these
1165 branches, but this possibility is not detailed here.
1167 When you push @code{@var{branch}} from @code{@var{subdir}} to the
1168 main repository, and @code{@var{branch}} is checked out in the
1169 main repository, you must save uncommitted changes (see
1170 @command{git@tie{}stash}) and do
1171 @command{git@tie{}reset@tie{}--hard} in the main repository in
1172 order to apply pushed changes in the working tree of the main
1180 The commands above don't only bring you the latest version of the
1181 sources, but also the full history of revisions (revisons, also
1182 called commits, are changes made to the sources), stored in the
1183 @file{.git} directory. You can browse this history with
1186 git log # only shows the logs (author, committish and commit message)
1187 git log -p # also shows diffs
1188 gitk # shows history graphically
1191 @warning{The @code{gitk} command may require a separate
1192 @code{gitk} package, available in the appropriate distribution's
1196 @node Applying remote patches
1197 @subsection Applying remote patches
1200 TODO: Explain how to determine if a patch was created with
1201 @code{git@tie{}format-patch}.
1203 Well-formed git patches created with @code{git@tie{}format-patch}
1204 should be committed with the following command:
1210 Patches created without @code{git@tie{}format-patch} can be
1211 applied in two steps. The first step is to apply the patch to the
1215 git apply @var{patch}
1219 The second step is to commit the changes and give credit to the
1220 author of the patch. This can be done with the following command:
1223 git commit -a --author="@var{John Smith} <@var{john@@example.com}>"
1227 @node Sending and receiving patches via email
1228 @subsection Sending and receiving patches via email
1231 The default @code{x-diff} MIME type associated with patch files
1232 (i.e., files whose name ends in @code{.patch}) means that the
1233 encoding of line endings may be changed from UNIX to DOS format
1234 when they are sent as attachments. Attempting to apply such an
1235 inadvertently altered patch will cause git to fail with a message
1236 about @q{whitespace errors}.
1238 The solution to such problems is surprisingly simple---just change
1239 the default file extension of patches generated by git to end in
1240 @code{.txt}, for example:
1243 git config format.suffix '.patch.txt'
1246 This should cause email programs to apply the correct base64
1247 encoding to attached patches.
1249 If you receive a patch with DOS instead of UNIX line-endings, it
1250 can be converted back using the @code{dos2unix} utility.
1252 Lots of useful information on email complications with patches is
1253 provided on the Wine wiki at
1254 @uref{http://wiki.winehq.org/GitWine}.
1258 @subsection Commit access
1261 Most contributors are not able to commit patches directly to the
1262 main repository---only members of the LilyPond development team
1263 have @emph{commit access}. If you are a contributor and are
1264 interested in joining the development team, contact the Project
1265 Manager through the mailing list
1266 (@email{lilypond-devel@@gnu.org}). Generally, only contributors
1267 who have already provided a number of patches which have been
1268 pushed to the main repository will be considered for membership.
1270 If you have been approved by the Project Manager, use the
1271 following procedure to obtain commit access:
1275 If you don't already have one, set up a Savannah user account at
1276 @uref{https://savannah.gnu.org/account/register.php}. If your web
1277 browser responds with an @qq{untrusted connection} message when
1278 you visit the link, follow the steps for including the CAcert root
1279 certificate in your browser, given at
1280 @uref{http://savannah.gnu.org/tls/tutorial/}.
1284 After registering, if you are not logged in automatically, login
1285 at @uref{https://savannah.gnu.org/account/login.php}---this should
1286 take you to your @qq{my} page
1287 (@uref{https://savannah.gnu.org/my/}).
1291 Click on the @qq{My Groups} link to access the @qq{My Group
1292 Membership} page. From there, find the @qq{Request for Inclusion}
1293 box and search for @qq{LilyPond}. Among the search results, check
1294 the box labeled @qq{GNU LilyPond Music Typesetter} and write a
1295 brief (required) message for the Project Manager (@qq{Hey it's
1296 me!} should be fine).
1298 Note that you will not have commit access until the Project
1299 Manager activates your membership. Once your membership is
1300 activated, LilyPond should appear under the heading @qq{Groups I'm
1301 Contributor of} on your @qq{My Group Membership} page.
1305 Generate an SSH @q{dsa} key pair. Enter the following at the
1312 When prompted for a location to save the key, press <ENTER> to
1313 accept the default location (@file{~/.ssh/id_dsa}).
1315 Next you are asked to enter an optional passphrase. On most
1316 systems, if you use a passphrase, you will likely be prompted for
1317 it every time you use @command{git@tie{}push} or
1318 @command{git@tie{}pull}. You may prefer this since it can protect
1319 you from your own mistakes (like pushing when you mean to pull),
1320 though you may find it tedious to keep re-entering it.
1322 You can change/enable/disable your passphrase at any time with:
1325 ssh-keygen -f ~/.ssh/id_dsa -p
1328 Note that the GNOME desktop has a feature which stores your
1329 passphrase for you for an entire GNOME session. If you use a
1330 passphrase to @qq{protect you from yourself}, you will want to
1331 disable this feature, since you'll only be prompted once. Run the
1332 following command, then logout of GNOME and log back in:
1335 gconftool-2 --set -t bool \
1336 /apps/gnome-keyring/daemon-components/ssh false
1339 After setting up your passphrase, your private key is saved as
1340 @file{~/.ssh/id_dsa} and your public key is saved as
1341 @file{~/.ssh/id_dsa.pub}.
1345 Register your public SSH @q{dsa} key with Savannah. From the
1346 @qq{My Account Configuration} page, click on @qq{Edit SSH Keys},
1347 then paste the contents of your @file{~/.ssh/id_dsa.pub} file into
1348 one of the @qq{Authorized keys} text fields, and click
1351 Savannah should respond with something like:
1354 Success: Key #1 seen Keys registered
1359 Configure Git to use the SSH protocol (instead of the GIT
1360 protocol). From your local Git repository, enter:
1363 git config remote.origin.url \
1364 ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1368 where @var{user} is your username on Savannah.
1372 After your membership has been activated and you’ve configured Git
1373 to use SSH, test the connection with:
1379 SSH should issue the following warning:
1382 The authenticity of host 'git.sv.gnu.org (140.186.70.72)' can't
1384 RSA key fingerprint is
1385 80:5a:b0:0c:ec:93:66:29:49:7e:04:2b:fd:ba:2c:d5.
1386 Are you sure you want to continue connecting (yes/no)?
1389 Make sure the RSA key fingerprint displayed matches the one above.
1390 If it doesn't, respond @qq{no} and check that you configured Git
1391 properly in the previous step. If it does match, respond
1392 @qq{yes}. SSH should then issue another warning:
1395 Warning: Permanently added 'git.sv.gnu.org,140.186.70.72' (RSA) to
1396 the list of known hosts.
1399 The list of known hosts is stored in the file
1400 @file{~/.ssh/known_hosts}.
1402 At this point, you are prompted for your passphrase if you have
1403 one, then Git will attempt a pull.
1405 If @command{git@tie{}pull@tie{}--verbose} fails, you should see
1406 error messages like these:
1409 Permission denied (publickey).
1410 fatal: The remote end hung up unexpectedly
1413 If you get the above error, you may have made a mistake when
1414 registering your SSH key at Savannah. If the key is properly
1415 registered, you probably just need to wait for the Savannah server
1416 to activate it. It usually takes a few minutes for the key to be
1417 active after registering it, but if it still doesn't work after an
1418 hour, ask for help on the mailing list.
1420 If @command{git@tie{}pull@tie{}--verbose} succeeds, the output
1421 will include a @q{From} line that shows @q{ssh} as the protocol:
1424 From ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond
1427 If the protocol shown is not @q{ssh}, check that you configured
1428 Git properly in the previous step.
1432 Test your commit access with a dry run:
1435 git push --dry-run --verbose
1438 Note that recent versions of Git (Git 1.6.3 or later) will issue a
1439 big warning if the above command is used. The simplest solution
1440 is to tell Git to push all matching branches by default:
1443 git config push.default matching
1447 Then @code{git@tie{}push} should work as before. For more
1448 details, consult the @code{git@tie{}push} man page.
1452 @subsubheading Technical details
1456 On Firefox, to view or remove the CAcert root certificate, go to:
1457 Edit > Preferences > Advanced > Encryption > View Certificates >
1458 Authorities > Certificate Name > Root CA > CA Cert Signing
1462 The @command{git@tie{}config} commands above should modify your
1463 local repository's @file{.git/config} file. These lines:
1467 url = git://git.sv.gnu.org/lilypond.git/
1471 should now be changed to:
1475 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1479 where @var{user} is your login name on Savannah.
1483 @command{git@tie{}config@tie{}push.default@tie{}matching} command
1484 should add these lines to @file{.git/config}:
1493 Encryption protocols, including ssh, generally do not permit packet
1494 fragmentation to avoid introducing a point of insecurity. This
1495 means that the maximum packet size must not exceed the smallest
1496 MTU (Maximum Transmission Unit) set in the routers along the path.
1497 This smallest MTU is determined by a procedure during call set-up
1498 which relies on the transmission over the path of ICMP packets.
1499 If any of the routers in the path block ICMP packets this mechanism
1500 fails, resulting in the possibility of packets being transmitted
1501 which exceed the MTU of one of the routers. If this happens the
1502 packet is discarded, causing the ssh session to hang, timeout or
1503 terminate with the error message
1506 ssh: connect to host <host ip addr> port 22: Bad file number
1507 fatal: The remote end hung up unexpectedly
1510 depending on precisely when in the proceedings the first large
1511 packet is transmitted. Most routers on the internet have MTU
1512 set to 1500, but routers installed in homes to connect via
1513 broadband may use a slightly smaller MTU for efficient transmission
1514 over ATM. If this problem is encountered a possible work-around is
1515 to set the MTU in the local router to 1500.
1517 @node Git on Windows
1518 @section Git on Windows
1520 @c Some of this may duplicate stuff in other sections
1521 @c But it is probably best for windows users to have it all together
1522 @c If necessary, clear this up later -td
1524 TODO: Decide what to do with this... Pare it down? Move
1525 paragraphs next to analogous Unix instructions? -mp
1527 @subsection Background to nomenclature
1529 Git is a system for tracking the changes made to source files by a
1530 distributed set of editors. It is designed to work without a
1531 master repository, but we have chosen to have a master respository
1532 for LilyPond files. Editors hold a local copy of the master
1533 repository together with any changes they have made locally.
1534 Local changes are held in a local @q{branch}, of which there may
1535 be several, but these instructions assume you are using just one.
1536 The files visible in the local repository always correspond to
1537 those on the currently @q{checked out} local branch.
1539 Files are edited on a local branch, and in that state the changes
1540 are said to be @q{unstaged}. When editing is complete, the
1541 changes are moved to being @q{staged for commit}, and finally the
1542 changes are @q{committed} to the local branch. Once committed,
1543 the changes (called a @q{commit}) are given a unique 40-digit
1544 hexadecimal reference number called the @q{Committish} or @q{SHA1
1545 ID} which identifies the commit to Git. Such committed changes
1546 can be sent to the master repository by @q{pushing} them (if you
1547 have write permission) or by sending them by email to someone who
1548 has, either as a complete file or as a @q{diff} or @q{patch}
1549 (which send just the differences from the master repository).
1551 @subsection Installing git
1554 @uref{http://code.google.com/p/msysgit/downloads/list} (note, not
1555 msysGit, which is for Git developers and not PortableGit, which is
1556 not a full git installation) and install it.
1558 Note that most users will not need to install SSH. That is not
1559 required until you have been granted direct push permissions to
1560 the master git repository.
1562 Start Git by clicking on the desktop icon. This will bring up a
1563 command line bash shell. This may be unfamiliar to Windows users.
1564 If so, follow these instructions carefully. Commands are entered
1565 at a $ prompt and are terminated by keying a newline.
1567 @subsection Initialising Git
1569 Decide where you wish to place your local Git repository, creating
1570 the folders in Windows as necessary. Here we call the folder to
1571 contain the repository @code{[path]/Git}, but if you intend using
1572 Git for other projects a directory name like @code{lilypond-git}
1573 might be better. You will need to have space for around
1576 Start the Git bash shell by clicking on the desk-top icon
1577 installed with Git and type
1583 to position the shell at your new Git repository.
1585 Note: if [path] contains folders with names containing spaces use
1597 to initialize your Git repository.
1599 Then type (all on one line; the shell will wrap automatically)
1602 git remote add -ft master origin git://git.sv.gnu.org/lilypond.git
1605 to download the lilypond master files.
1607 @warning{Be patient! Even on a broadband connection this can take
1608 10 minutes or more. Wait for lots of [new tag] messages and the $
1611 We now need to generate a local copy of the downloaded files in a
1612 new local branch. Your local branch needs to have a name. It is
1613 usual to call it @q{master} and we shall do that here.
1618 git checkout -b master origin/master
1621 This creates a second branch called @q{master}. You will see two
1622 warnings (ignore these), and a message advising you that your
1623 local branch @q{master} has been set up to track the remote
1624 branch. You now have two branches, a local branch called
1625 @q{master}, and a tracking branch called @q{origin/master}, which
1626 is a shortened form of @q{remotes/origin/master}.
1628 Return to Windows Explorer and look in your Git repository. You
1629 should see lots of folders. For example, the LilyPond
1630 documentation can be found in [path]/Git/Documentation/.
1632 The Git bash shell is terminated by typing @code{exit} or by
1633 clicking on the usual Windows close-window widget.
1637 Almost all subsequent work will use the Git Graphical User
1638 Interface, which avoids having to type command line commands. To
1639 start Git GUI first start the Git bash shell by clicking on the
1640 desktop icon, and type
1647 The Git GUI will open in a new window. It contains four panels
1648 and 7 pull-down menus. At this stage do not use any of the
1649 commands under Branch, Commit, Merge or Remote. These will be
1652 The top panel on the left contains the names of files which you
1653 are in the process of editing (Unstaged Changes), and the lower
1654 panel on the left contains the names of files you have finished
1655 editing and have staged ready for committing (Staged Changes). At
1656 present, these panels will be empty as you have not yet made any
1657 changes to any file. After a file has been edited and saved the
1658 top panel on the right will display the differences between the
1659 edited file selected in one of the panels on the left and the last
1660 version committed on the current branch.
1662 The panel at bottom right is used to enter a descriptive message
1663 about the change before committing it.
1665 The Git GUI is terminated by entering CNTL-Q while it is the
1666 active window or by clicking on the usual Windows close-window
1669 @subsection Personalising your local git repository
1671 Open the Git GUI, click on
1677 and enter your name and email address in the left-hand (Git
1678 Repository) panel. Leave everything else unchanged and save it.
1680 Note that Windows users must leave the default setting for line
1681 endings unchanged. All files in a git repository must have lines
1682 terminated by just a LF, as this is required for Merge to work,
1683 but Windows files are terminated by CRLF by default. The git
1684 default setting causes the line endings of files in a Windows git
1685 repository to be flipped automatically between LF and CRLF as
1686 required. This enables files to be edited by any Windows editor
1687 without causing problems in the git repository.
1689 @subsection Checking out a branch
1691 At this stage you have two branches in your local repository,
1692 both identical. To see them click on
1698 You should have one local branch called @q{master} and one
1699 tracking branch called @q{origin/master}. The latter is your
1700 local copy of the @q{remotes/origin/master} branch in the master
1701 LilyPond repository. The local @q{master} branch is where you
1702 will make your local changes.
1704 When a particular branch is selected, i.e., checked out, the files
1705 visible in your repository are changed to reflect the state of the
1706 files on that branch.
1708 @subsection Updating files from @q{remote/origin/master}
1710 Before starting the editing of a file, ensure your local
1711 repository contains the latest version of the files in the remote
1712 repository by first clicking
1715 Remote -> Fetch from -> origin
1721 This will place the latest version of every file, including all
1722 the changes made by others, into the @q{origin/master} branch of
1723 the tracking branches in your git repository. You can see these
1724 files by checking out this branch, but you must @emph{never} edit
1725 any files while this branch is checked out. Check out your local
1726 @q{master} branch again.
1728 You then need to merge these fetched files into your local
1729 @q{master} branch by clicking on
1732 Merge -> Local Merge
1736 and if necessary select the local @q{master} branch.
1738 Note that a merge cannot be completed if you have made any local
1739 changes which have not yet been committed.
1741 This merge will update all the files in the @q{master} branch to
1742 reflect the current state of the @q{origin/master} branch. If any
1743 of the changes conflict with changes you have made yourself
1744 recently you will be notified of the conflict (see below).
1746 @subsection Editing files
1748 First ensure your @q{master} branch is checked out, then simply
1749 edit the files in your local Git repository with your favourite
1750 editor and save them back there. If any file contains non-ASCII
1751 characters ensure you save it in UTF-8 format. Git will detect
1752 any changes whenever you restart Git GUI and the file names will
1753 then be listed in the Unstaged Changes panel. Or you can click
1754 the Rescan button to refresh the panel contents at any time. You
1755 may break off and resume editing any time.
1757 The changes you have made may be displayed in diff form in the top
1758 right-hand panel of Git GUI by clicking on the file name shown in
1759 one of the left panels.
1761 When your editing is complete, move the files from being Unstaged
1762 to Staged by clicking the document symbol to the left of each
1763 name. If you change your mind it can be moved back by clicking on
1764 the ticked box to the left of the name.
1766 Finally the changes you have made may be committed to your
1767 @q{master} branch by entering a brief message in the Commit
1768 Message box and clicking the Commit button.
1770 If you wish to amend your changes after a commit has been made,
1771 the original version and the changes you made in that commit may
1772 be recovered by selecting
1775 Commit -> Amend Last Commit
1779 or by checking the Amend Last Commit radio button at bottom right.
1780 This will return the changes to the Staged state, so further
1781 editing made be carried out within that commit. This must only be
1782 done @emph{before} the changes have been Pushed or sent to your
1783 mentor for Pushing - after that it is too late and corrections
1784 have to be made as a separate commit.
1787 @subsection Sending changes to @q{remotes/origin/master}
1789 If you do not have write access to @q{remotes/origin/master} you
1790 will need to send your changes by email to someone who does.
1792 First you need to create a diff or patch file containing your
1793 changes. To create this, the file must first be committed. Then
1794 terminate the Git GUI. In the git bash shell first cd to your Git
1801 if necessary, then produce the patch with
1804 git format-patch origin
1807 This will create a patch file for all the locally committed files
1808 which differ from @q{origin/master}. The patch file can be found
1809 in [path]/Git and will have a name formed from the commit message.
1811 @subsection Resolving merge conflicts
1813 As soon as you have committed a changed file your local
1814 @code{master} branch has diverged from @code{origin/master}, and
1815 will remain diverged until your changes have been committed in
1816 @code{remotes/origin/master} and Fetched back into your
1817 @code{origin/master} branch. Similarly, if a new commit has been
1818 made to @code{remotes/origin/master} by someone else and Fetched,
1819 your local @code{master} branch is divergent. You can detect a
1820 divergent branch by clicking on
1823 Repository -> Visualise all branch history
1826 This opens up a very useful new window called @q{gitk}. Use this
1827 to browse all the commits made by yourself and others.
1829 If the diagram at top left of the resulting window does not show
1830 your @code{master} tag on the same node as the
1831 @code{remotes/origin/master} tag your branch has diverged from
1832 @code{origin/master}. This is quite normal if files you have
1833 modified yourself have not yet been Pushed to
1834 @code{remotes/origin/master} and Fetched, or if files modified and
1835 committed by others have been Fetched since you last Merged
1836 @code{origin/master} into your local @code{master} branch.
1838 If a file being merged from @code{origin/master} differs from one
1839 you have modified in a way that cannot be resolved automatically
1840 by git, Merge will report a Conflict which you must resolve by
1841 editing the file to create the version you wish to keep.
1843 This could happen if the person updating
1844 @code{remotes/origin/master} for you has added some changes of his
1845 own before committing your changes to
1846 @code{remotes/origin/master}, or if someone else has changed the
1847 same file since you last fetched the file from
1848 @code{remotes/origin/master}.
1850 Open the file in your editor and look for sections which are
1853 [to be completed when I next have a merge conflict to be sure I
1854 give the right instructions -td]
1857 @subsection Other actions
1859 The instructions above describe the simplest way of using git on
1860 Windows. Other git facilities which may usefully supplement these
1864 @item Using multiple local branches (Create, Rename, Delete)
1865 @item Resetting branches
1866 @item Cherry-picking commits
1867 @item Pushing commits to @w{remote/origin/master}
1868 @item Using gitk to review history
1871 Once familiarity with using git on Windows has been gained the
1872 standard git manuals can be used to learn about these.
1875 @node Repository directory structure
1876 @section Repository directory structure
1879 @c TODO: integrate the roadmap better
1880 @verbatiminclude ROADMAP
1883 @node Other Git documentation
1884 @section Other Git documentation
1888 Official git man pages:
1889 @uref{http://www.kernel.org/pub/software/scm/git/docs/}
1892 More in-depth tutorials: @uref{http://git-scm.com/documentation}
1895 Book about git: @uref{http://progit.org/,Pro Git}