1 @c -*- coding: utf-8; mode: texinfo; -*-
4 @node Working with source code
5 @chapter Working with source code
11 * Basic Git procedures::
12 * Advanced Git procedures::
14 * Repository directory structure::
15 * Other Git documentation::
20 @section Using lily-git
23 If you haven't already, download and install Git. Go to
24 @uref{http://git-scm.com/download}, and in the @qq{Binaries}
25 section, select the appropriate package for your operating system.
26 Windows users should visit
27 @uref{http://code.google.com/p/msysgit/downloads/list} and
28 download the @file{.exe} file labeled @qq{Full installer for
31 Download the lily-git script from:
33 @c don't change the cgit link below to gitweb; gitweb uses
34 @c long filenames like "scripts_auxiliar_lily-git.tcl"
37 @uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
40 To run the program from the command line, navigate to the
41 directory containing @file{lily-git.tcl} and enter:
48 @subsubheading Get source / Update source
50 When you click the @qq{Get source} button, @command{lily-git} will
51 create a directory called @file{lilypond-git/} within your home
52 directory, and will download the complete source code into that
53 directory (around 55Mb). When the process is finished, the
54 @qq{Command output} window will display @qq{Done}, and the button
55 label will change to say @qq{Update source}.
57 Navigate to the @file{lilypond-git/} directory to view the source
58 files. You should now be able to modify the source files using
59 your normal text editor.
63 The @qq{Get source} button does not fetch the entire history of
64 the git repository, so utilities like @command{gitk} will only
65 be able to display the most recent additions. As you continue to
66 work with @command{lily-git}, the @qq{Update source} button will take
67 any new additions and add it to whatever is currently in your repository's
71 @subsubheading New local commit
73 A single commit typically represents one logical set of related
74 changes (such as a bug-fix), and may incorporate changes to
75 multiple files at the same time.
77 When you're finished making the changes for your first commit,
78 click the @qq{New local commit} button. This will open the
79 @qq{Git Commit Message} window. The message header is required,
80 and the message body is optional. See @ref{Commits and patches}
81 for more information regarding commits and commit messages.
83 After entering a commit message, click @qq{OK} to finalize the
87 @subsubheading Amend previous commit
89 You can go back and make changes to the most recent commit with
90 the @qq{Amend previous commit} button. This is useful if a
91 mistake is found after you've clicked the @qq{New local commit}
92 button. To amend the most recent commit, edit the source files as
93 needed and click the button. The earlier version of the commit is
94 not saved, but is replaced by the new one.
96 Note that this does not update patch files; if you have a patch
97 file from an earlier version of the commit, you will need to make
98 another patch set when using this feature. The old patch file is
99 not saved, but is replaced by the new one.
102 @subsubheading Make patch set
104 Before making a patch set from any commits, you should click the
105 @qq{Update source} button to make sure the commits are based on
106 the most recent remote snapshot.
108 When you click the @qq{Make patch set} button, @command{lily-git}
109 will produce patch files for any new commits, saving them to the
110 current directory. The command output will display the name of
111 the new patch files near the end of the output:
114 0001-CG-add-lily-git-instructions.patch
118 Send patch files to your mentor if you have one. Otherwise, write
119 an email (must be less than 64 KB) to
120 @email{lilypond-devel@@gnu.org} briefly explaining your work, with
121 the patch files attached. Translators should send patches to
122 @email{translations@@lilynet.net}.
125 @subsubheading The @qq{Abort changes -- Reset to origin} button
127 @warning{Only use this if your local commit history gets
128 hopelessly confused!}
130 The button labeled @qq{Abort changes -- Reset to origin} will copy
131 all changed files to a subdirectory of @file{lilypond-git/} named
132 @file{aborted_edits/}, and will reset the repository to the
133 current state of the remote repository (at @code{git.sv.gnu.org}).
136 @node Starting with Git
137 @section Starting with Git
140 Using the Git program directly (as opposed to using the
141 @command{lily-git} GUI) allows you to have much greater control
142 over the contributing process. You should consider using Git if
143 you want to work on complex projects, or if you want to work on
144 multiple projects concurrently.
149 * Downloading remote branches::
154 @subsection Setting up
157 TODO: Remove this note if incorporating Windows instructions
158 throughout this section:
160 @warning{These instructions assume that you are using the
161 command-line version of Git 1.5 or higher. Windows users should
162 skip to @ref{Git on Windows}.}
166 * Initializing a repository::
172 @unnumberedsubsubsec Installing Git
175 If you are using a Unix-based machine, the easiest way to download
176 and install Git is through a package manager such as @command{rpm}
177 or @command{apt-get}---the installation is generally automatic.
178 The only required package is (usually) called @command{git-core},
179 although some of the auxiliary @command{git@var{*}} packages are
180 also useful (such as @command{gitk}).
182 Alternatively, you can visit the Git website
183 (@uref{http://git-scm.com/}) for downloadable binaries and
186 TODO: add Windows installation instructions (or @@ref@{Git on
190 @node Initializing a repository
191 @unnumberedsubsubsec Initializing a repository
194 Once Git is installed, you'll need to create a new directory where
195 your initial repository will be stored (the example below uses
196 @file{~/lilypond-git/}, where @code{~} represents your home
197 directory). Run @command{git@tie{}init} from within the new
198 directory to initialize an empty repository:
201 mkdir ~/lilypond-git/; cd ~/lilypond-git/
205 @subsubheading Technical details
207 This creates (within the @file{~/lilypond-git/} directory) a
208 subdirectory called @file{.git/}, which Git uses to keep track of
209 changes to the repository, among other things. Normally you don't
210 need to access it, but it's good to know it's there.
213 @node Configuring Git
214 @unnumberedsubsubsec Configuring Git
216 @warning{Throughout the rest of this manual, all command-line
217 input should be entered from the top directory of the Git
218 repository being discussed (eg. @file{~/lilypond-git/}). This is
219 referred to as a @emph{top source directory}.}
221 Before downloading a copy of the main LilyPond repository, you
222 should configure some basic settings with the
223 @command{git@tie{}config} command. Git allows you to set both
224 global and repository-specific options.
226 To configure settings that affect all repositories, use the
227 @command{--global} command line option. For example, the first
228 two options that you should always set are your @var{name} and
229 @var{email}, since Git needs these to keep track of commit
233 git config --global user.name "@var{John Smith}"
234 git config --global user.email @var{john@@example.com}
237 To configure Git to use colored output where possible, use:
240 git config --global color.ui auto
243 The text editor that opens when using @command{git@tie{}commit}
244 can also be changed. If none of your editor-related environment
245 variables are set ($GIT_EDITOR, $VISUAL, or $EDITOR), the default
246 editor is usually @command{vi} or @command{vim}. If you're not
247 familiar with either of these, you should probably change the
248 default to an editor that you know how to use. For example, to
249 change the default editor to @command{nano}, enter:
252 git config --global core.editor @var{nano}
255 TODO: Add instructions for changing the editor on Windows, which
256 is a little different, I think. -mp
258 @subsubheading Technical details
260 Git stores the information entered with
261 @command{git@tie{}config@tie{}--global} in the file
262 @file{.gitconfig}, located in your home directory. This file can
263 also be modified directly, without using
264 @command{git@tie{}config}. The @file{.gitconfig} file generated
265 by the above commands would look like this:
270 email = john@@example.com
277 Using the @command{git@tie{}config} command @emph{without} the
278 @command{--global} option configures repository-specific settings,
279 which are stored in the file @file{.git/config}. This file is
280 created when a repository is initialized (using
281 @command{git@tie{}init}), and by default contains these lines:
285 repositoryformatversion = 0
288 logallrefupdates = true
291 However, since different repository-specific options are
292 recommended for different development tasks, it is best to avoid
293 setting any now. Specific recommendations will be mentioned later
297 @node Downloading remote branches
298 @subsection Downloading remote branches
302 * Organization of remote branches::
303 * LilyPond repository sources::
304 * Downloading individual branches::
305 * Downloading all remote branches::
310 @node Organization of remote branches
311 @unnumberedsubsubsec Organization of remote branches
314 The main LilyPond repository is organized into @emph{branches} to
315 facilitate development. These are often called @emph{remote}
316 branches to distinguish them from @emph{local} branches you might
317 create yourself (see @ref{Using local branches}).
319 The @code{master} branch contains all the source files used to
320 build LilyPond, which includes the program itself (both stable and
321 development releases), the documentation (and its translations),
322 and the website. Generally, the @code{master} branch is expected
323 to compile successfully.
325 The @code{lilypond/translation} branch is a side branch that
326 allows translators to work without needing to worry about
327 compilation problems. Periodically, the Translation Meister
328 (after verifying that it doesn't break compilation), will
329 @emph{merge} this branch back into @code{master} to incorporate
330 recent translations. Similarly, the @code{master} branch is
331 usually merged into the @code{lilypond/translation} branch after
332 significant changes to the English documentation. See
333 @ref{Translating the documentation} for details.
336 @node LilyPond repository sources
337 @unnumberedsubsubsec LilyPond repository sources
340 The recommended source for downloading a copy of the main
344 git://git.sv.gnu.org/lilypond.git
347 However, if your internet router filters out connections using the
348 GIT protocol, or if you experience difficulty connecting via GIT,
349 you can try these other sources:
352 ssh://git.sv.gnu.org/srv/git/lilypond.git
353 http://git.sv.gnu.org/r/lilypond.git
356 The SSH protocol can only be used if your system is properly set
357 up to use it. Also, the HTTP protocol is slowest, so it should
358 only be used as a last resort.
361 @node Downloading individual branches
362 @unnumberedsubsubsec Downloading individual branches
365 Once you have initialized an empty Git repository on your system
366 (see @ref{Initializing a repository}), you can download a remote
367 branch into it. Make sure you know which branch you want to start
370 To download the @code{master} branch, enter the following:
373 git remote add -ft master -m master \
374 origin git://git.sv.gnu.org/lilypond.git/
377 To download the @code{lilypond/translation} branch, enter:
380 git remote add -ft lilypond/translation -m \
381 lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
384 The @command{git@tie{}remote@tie{}add} process could take up to
385 ten minutes, depending on the speed of your connection. The
386 output will be something like this:
390 remote: Counting objects: 235967, done.
391 remote: Compressing objects: 100% (42721/42721), done.
392 remote: Total 235967 (delta 195098), reused 233311 (delta 192772)
393 Receiving objects: 100% (235967/235967), 68.37 MiB | 479 KiB/s, done.
394 Resolving deltas: 100% (195098/195098), done.
395 From git://git.sv.gnu.org/lilypond
396 * [new branch] master -> origin/master
397 From git://git.sv.gnu.org/lilypond
398 * [new tag] flower/1.0.1 -> flower/1.0.1
399 * [new tag] flower/1.0.10 -> flower/1.0.10
401 * [new tag] release/2.9.6 -> release/2.9.6
402 * [new tag] release/2.9.7 -> release/2.9.7
405 When @command{git@tie{}remote@tie{}add} is finished, the remote
406 branch should be downloaded into your repository---though not yet
407 in a form that you can use. In order to browse the source code
408 files, you need to @emph{create} and @emph{checkout} your own
409 local branch. In this case, however, it is easier to have Git
410 create the branch automatically by using the @command{checkout}
411 command on a non-existent branch. Enter the following:
414 git checkout -b @var{branch} origin/@var{branch}
418 where @code{@var{branch}} is the name of your tracking branch,
419 either @code{master} or @code{lilypond/translation}.
421 Git will issue some warnings; this is normal:
424 warning: You appear to be on a branch yet to be born.
425 warning: Forcing checkout of origin/master.
426 Branch master set up to track remote branch master from origin.
430 By now the source files should be accessible---you should be able
431 to edit any files in the @file{lilypond-git/} directory using a
432 text editor of your choice. But don't start just yet! Before
433 editing any source files, learn how to keep your changes organized
434 and prevent problems later---read @ref{Basic Git procedures}.
436 @subsubheading Technical Details
438 The @command{git@tie{}remote@tie{}add} command should add some
439 lines to your local repository's @file{.git/config} file:
443 url = git://git.sv.gnu.org/lilypond.git/
444 fetch = +refs/heads/master:refs/remotes/origin/master
448 @node Downloading all remote branches
449 @unnumberedsubsubsec Downloading all remote branches
452 To download all remote branches at once, you can @command{clone}
453 the entire repository:
456 git clone git://git.sv.gnu.org/lilypond.git
461 @unnumberedsubsubsec Other branches
463 Most contributors will never need to touch the other branches. If
464 you wish to do so, you will need more familiarity with Git; please
465 see @ref{Other Git documentation}.
468 @item @code{dev/XYZ}:
469 These branches are for individual developers. They store code
470 which is not yet stable enough to be added to the @code{master}
473 @item @code{stable/XYZ}:
474 The branches are kept for archival reasons.
478 Another item of interest might be the Grand Unified Builder, our
479 cross-platform building tool. Since it is used by projects as
480 well, it is not stored in our gub repository. For more info, see
481 @uref{http://lilypond.org/gub}. The git location is
482 @uref{http://github.com/janneke/gub}.
485 @node Basic Git procedures
486 @section Basic Git procedures
490 * The Git contributor's cycle::
491 * Pulling and rebasing::
492 * Using local branches::
493 * Commits and patches::
497 @node The Git contributor's cycle
498 @subsection The Git contributor's cycle
501 Here is a simplified view of the contribution process on Git:
505 Update your local repository by @emph{pulling} the most recent
506 updates from the remote repository.
509 Edit source files within your local repository's @emph{working
513 @emph{Commit} the changes you've made to a local @emph{branch}.
516 Generate a @emph{patch} to share your changes with the developers.
520 @node Pulling and rebasing
521 @subsection Pulling and rebasing
524 When developers push new patches to the @code{git.sv.gnu.org}
525 repository, your local repository is @strong{not} automatically
526 updated. It is important to keep your repository up-to-date by
527 periodically @emph{pulling} the most recent @emph{commits} from
528 the remote branch. Developers expect patches to be as current as
529 possible, since outdated patches require extra work before they
532 Occasionally you may need to rework some of your own modifications
533 to match changes made to the remote branch (see @ref{Resolving
534 conflicts}), and it's considerably easier to rework things
535 incrementally. If you don't update your repository along the way,
536 you may have to spend a lot of time resolving branch conflicts and
537 reconfiguring much of the work you've already done.
539 Fortunately, Git is able to resolve certain types of branch
540 conflicts automatically with a process called @emph{rebasing}.
541 When rebasing, Git tries to modify your old commits so they appear
542 as new commits (based on the latest updates). For a more involved
543 explanation, see the @command{git-rebase} man page.
545 To pull without rebasing (recommended for translators), use the
549 git pull # recommended for translators
552 If you're tracking the remote @code{master} branch, you should add
553 the @code{-r} option (short for @code{--rebase}) to keep commits
554 on your local branch current:
557 git pull -r # use with caution when translating
560 If you don't edit translated documentation and don't want to type
561 @code{-r} every time, configure the master branch to rebase by
562 default with this command:
565 git config branch.master.rebase true
568 If pull fails because of a message like
571 error: Your local changes to 'Documentation/learning/tutorial.itely'
572 would be overwritten by merge. Aborting.
579 Documentation/learning/tutorial.itely: needs update
580 refusing to pull with rebase: your working tree is not up-to-date
584 it means that you have modified some files in you working tree
585 without committing changes (see @ref{Commits and patches}); you
586 can use the @command{git@tie{}stash} command to work around this:
589 git stash # save uncommitted changes
590 git pull -r # pull using rebase (translators omit "-r")
591 git stash pop # reapply previously saved changes
594 Note that @command{git@tie{}stash@tie{}pop} will try to apply a
595 patch, and this may create a conflict. If this happens, see
596 @ref{Resolving conflicts}.
598 TODO: I think the next paragraph is confusing. Perhaps prepare
599 the reader for new terms `committish' and `head'? -mp
601 @warning{translators and documentation editors, if you have
602 changed committishes in the head of translated files using commits
603 you have not yet pushed to @code{git.sv.gnu.org}, please do not
604 rebase. If you want to avoid wondering whether you should rebase
605 each time you pull, please always use committishes from master
606 and/or lilypond/translation branch on @code{git.sv.gnu.org}, which
607 in particular implies that you must push your changes to
608 documentation except committishes updates (possibly after having
609 rebased), then update the committishes and push them.}
611 TODO: when committishes automatic conditional update have been
612 tested and documented, append the following to the warning above:
613 Note that using update-committishes make target generally touches
616 @subsubheading Technical details
618 The @command{git@tie{}config} command mentioned above adds the
619 line @code{rebase = true} to the master branch in your local
620 repository's @file{.git/config} file:
625 merge = refs/heads/master
630 @node Using local branches
631 @subsection Using local branches
635 * Creating and removing branches::
636 * Listing branches and remotes::
637 * Checking out branches::
642 @node Creating and removing branches
643 @unnumberedsubsubsec Creating and removing branches
646 Local branches are useful when you're working on several different
647 projects concurrently. To create a new branch, enter:
650 git branch @var{name}
653 To delete a branch, enter:
656 git branch -d @var{name}
659 Git will ask you for confirmation if it sees that data would be
660 lost by deleting the branch. Use @code{-D} instead of @code{-d}
661 to bypass this. Note that you cannot delete a branch if it is
662 currently checked out.
665 @node Listing branches and remotes
666 @unnumberedsubsubsec Listing branches and remotes
668 You can get the exact path or URL of all remote branches by
675 To list Git branches on your local repositories, run
678 git branch # list local branches only
679 git branch -r # list remote branches
680 git branch -a # list all branches
684 @node Checking out branches
685 @unnumberedsubsubsec Checking out branches
687 To know the currently checked out branch, i.e. the branch whose
688 source files are present in your working tree, read the first line
696 The currently checked out branch is also marked with an asterisk
697 in the output of @command{git branch}.
699 You can check out another branch @code{@var{other_branch}}, i.e.
700 check out @code{@var{other_branch}} to the working tree, by
704 git checkout @var{other_branch}
707 Note that it is possible to check out another branch while having
708 uncommitted changes, but it is not recommended unless you know
709 what you are doing; it is recommended to run @command{git status}
710 to check this kind of issue before checking out another branch.
712 @node Merging branches
713 @unnumberedsubsubsec Merging branches
715 To merge branch @code{@var{foo}} into branch @code{@var{bar}},
716 i.e. to @qq{add} all changes made in branch @code{@var{foo}} to
717 branch @code{@var{bar}}, run
720 git checkout @var{bar}
724 If any conflict happens, see @ref{Resolving conflicts}.
726 There are common usage cases for merging: as a translator, you
727 will often want to merge @code{master} into
728 @code{lilypond/translation}; on the other hand, the Translations
729 meister wants to merge @code{lilypond/translation} into
730 @code{master} whenever he has checked that
731 @code{lilypond/translation} builds successfully.
734 @node Commits and patches
735 @subsection Commits and patches
739 * Understanding commits::
746 @node Understanding commits
747 @unnumberedsubsubsec Understanding commits
749 Technically, a @emph{commit} is a single point in the history of a
750 branch, but most developers use the term to mean a @emph{commit
751 object}, which stores information about a particular revision. A
752 single commit can record changes to multiple source files, and
753 typically represents one logical set of related changes (such as a
754 bug-fix). You can list the ten most recent commits in your
755 current branch with this command:
758 git log -10 --oneline
761 If you're using an older version of Git and get an @q{unrecognized
762 argument} error, use this instead:
765 git log -10 --pretty=oneline --abbrev-commit
768 More interactive lists of the commits on the remote @code{master}
769 branch are available at
770 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=shortlog} and
771 @uref{http://git.sv.gnu.org/cgit/lilypond.git/log/}.
775 @unnumberedsubsubsec Making commits
778 Once you have modified some source files in your working
779 directory, you can make a commit with the following procedure:
783 Make sure you've configured Git properly (see @ref{Configuring
784 Git}). Check that your changes meet the requirements described in
785 @ref{Code style} and/or @ref{Documentation policy}. For advanced
786 edits, you may also want to verify that the changes don't break
787 the compilation process.
790 Run the following command:
797 to make sure you're on the right branch, and to see which files
798 have been modified, added or removed, etc. You may need to tell
799 Git about any files you've added by running one of these:
802 git add @var{file} # add untracked @var{file} individually
803 git add . # add all untracked files in current directory
807 After @command{git@tie{}add}, run @command{git@tie{}status} again
808 to make sure you got everything. You may also need to modify
812 Preview the changes about to be committed (to make sure everything
820 The @code{HEAD} argument refers to the most recent commit on the
821 currently checked-out branch.
824 Generate the commit with:
831 The @code{-a} is short for @code{--all} which includes modified
832 and deleted files, but only those newly created files that have
833 previously been added.
838 @node Commit messages
839 @unnumberedsubsubsec Commit messages
842 When you run the @command{git@tie{}commit@tie{}-a} command, Git
843 automatically opens the default text editor so you can enter a
844 @emph{commit message}. If you find yourself in a foreign editing
845 environment, you're probably in @command{vi} or @command{vim}. If
846 you want to switch to an editor you're more familiar with, quit by
847 typing @code{:q!} and pressing @code{<Enter>}. See
848 @ref{Configuring Git} for instructions on changing the default
851 In any case, Git will open a text file for your commit message
852 that looks like this:
856 # Please enter the commit message for your changes. Lines starting
857 # with '#' will be ignored, and an empty message aborts the commit.
859 # Changes to be committed:
860 # (use "git reset HEAD <file>..." to unstage)
862 # modified: working.itexi
866 Your commit message should begin with a one-line summary
867 describing the change (no more than 50 characters long), and if
868 necessary a blank line followed by several lines giving the
871 @c $ git log -1 --pretty=medium 4d6f1e5
873 Doc: add Baerenreiter and Henle solo cello suites
875 Added comparison of solo cello suite engravings to new essay with
876 high-res images, fixed cropping on Finale example.
879 Commit messages often start with a short prefix describing the
880 general location of the changes. If a commit affects the
881 documentation in English (or in several languages simultaneously)
882 the commit message should be prefixed with @qq{Doc:@tie{}}. If
883 the commit affects only one of the translations, the commit
884 message should be prefixed with @qq{Doc-@var{**}:@tie{}}, where
885 @var{**} is the two-letter language code. Commits that affect the
886 website should use @qq{Web:@tie{}} for English, and
887 @qq{Web-@var{**}:@tie{}} for the other languages. Also, changes
888 to a single file are often prefixed with the name of the file
889 involved. Visit the links listed in @ref{Understanding commits}
894 @unnumberedsubsubsec Making patches
897 If you want to share your changes with other contributors and
898 developers, you need to generate @emph{patches} from your commits.
899 You should always run @command{git@tie{}pull@tie{}-r} (translators
900 should leave off the @code{-r}) before doing this to ensure that
901 your patches are as current as possible.
903 Once you have made one or more commits in your local repository,
904 and pulled the most recent commits from the remote branch, you can
905 generate patches from your local commits with the command:
908 git format-patch origin
911 The @code{origin} argument refers to the remote tracking branch at
912 @code{git.sv.gnu.org}. This command generates a separate patch
913 for each commit that's in the current branch but not in the remote
914 branch. Patches are placed in the current working directory and
915 will have names that look something like this:
918 0001-Doc-Fix-typos.patch
919 0002-Web-Remove-dead-links.patch
923 Send an email (must be less than 64 KB) to
924 @email{lilypond-devel@@gnu.org} briefly explaining your work, with
925 the patch files attached. Translators should send patches to
926 @email{translations@@lilynet.net}. After your patches are
927 reviewed, the developers may push one or more of them to the main
928 repository or discuss them with you.
932 If your patch includes a significant amount of code, you may want
933 to see @ref{Adding or modifying features}, especially @emph{Post
937 @node Advanced Git procedures
938 @section Advanced Git procedures
941 @warning{This section is not necessary for normal contributors;
942 these commands are presented for information for people interested
943 in learning more about git.}
945 It is possible to work with several branches on the same local Git
946 repository; this is especially useful for translators who may have
947 to deal with both @code{lilypond/translation} and a stable branch,
948 e.g. @code{stable/2.12}.
950 Some Git commands are introduced first, then a workflow with
951 several Git branches of LilyPond source code is presented.
955 * Advanced Git concepts::
956 * Resolving conflicts::
957 * Reverting all local changes::
958 * Working with remote branches::
960 * Applying remote patches::
961 * Sending and receiving patches via email::
966 @node Advanced Git concepts
967 @subsection Advanced Git concepts
970 A bit of Git vocabulary will be explained below. The following is
971 only introductory; for a better understanding of Git concepts, you
972 may wish to read @ref{Other Git documentation}.
974 The @code{git@tie{}pull@tie{}origin} command above is just a
975 shortcut for this command:
978 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
982 where @code{@var{branch}} is typically @code{master} or
983 @code{lilypond/translation}; if you do not know or remember, see
984 @ref{Downloading remote branches} to remember which commands you
985 issued or which source code you wanted to get.
987 A @emph{commit} is a set of changes made to the sources; it also
988 includes the committish of the parent commit, the name and e-mail
989 of the @emph{author} (the person who wrote the changes), the name
990 and e-mail of the @emph{committer} (the person who brings these
991 changes into the Git repository), and a commit message.
993 A @emph{committish} is the SHA1 checksum of a commit, a number
994 made of 40 hexadecimal digits, which acts as the internal unique
995 identifier for this commit. To refer to a particular revision,
996 don't use vague references like the (approximative) date, simply
997 copy and paste the committish.
999 A @emph{branch} is nothing more than a pointer to a particular
1000 commit, which is called the @emph{head} of the branch; when
1001 referring to a branch, one often acutally thinks about its head
1002 and the ancestor commits of the head.
1004 Now we will explain the two last commands you used to get the
1005 source code from Git---see @ref{Downloading individual branches}.
1008 git remote add -ft @var{branch} -m @var{branch} \
1009 origin git://git.sv.gnu.org/lilypond.git/
1011 git checkout -b @var{branch} origin/@var{branch}
1014 The @command{git@tie{}remote} has created a branch called
1015 @code{origin/@var{branch}} in your local Git repository. As this
1016 branch is a copy of the remote branch web from git.sv.gnu.org
1017 LilyPond repository, it is called a @emph{remote branch}, and is
1018 meant to track the changes on the branch from git.sv.gnu.org: it
1019 will be updated every time you run
1020 @command{git@tie{}pull@tie{}origin} or
1021 @command{git@tie{}fetch@tie{}origin}.
1023 The @command{git@tie{}checkout} command has created a branch named
1024 @code{@var{branch}}. At the beginning, this branch is identical
1025 to @code{origin/@var{branch}}, but it will differ as soon as you
1026 make changes, e.g. adding newly translated pages or editing some
1027 documentation or code source file. Whenever you pull, you merge
1028 the changes from @code{origin/@var{branch}} and
1029 @code{@var{branch}} since the last pulling. If you do not have
1030 push (i.e. @qq{write}) access on git.sv.gnu.org, your
1031 @code{@var{branch}} will always differ from
1032 @code{origin/@var{branch}}. In this case, remember that other
1033 people working like you with the remote branch @code{@var{branch}}
1034 of git://git.sv.gnu.org/lilypond.git/ (called
1035 @code{origin/@var{branch}} on your local repository) know nothing
1036 about your own @code{@var{branch}}: this means that whenever you
1037 use a committish or make a patch, others expect you to take the
1038 latest commit of @code{origin/@var{branch}} as a reference.
1040 Finally, please remember to read the man page of every Git command
1041 you will find in this manual in case you want to discover
1042 alternate methods or just understand how it works.
1045 @node Resolving conflicts
1046 @subsection Resolving conflicts
1049 Occasionally an update may result in conflicts -- this happens
1050 when you and somebody else have modified the same part of the same
1051 file and git cannot figure out how to merge the two versions
1052 together. When this happens, you must manually merge the two
1055 If you need some documentation to understand and resolve
1056 conflicts, see paragraphs @emph{How conflicts are presented} and
1057 @emph{How to resolve conflicts} in @command{git merge} man page.
1059 If all else fails, you can follow the instructions in
1060 @ref{Reverting all local changes}. Be aware that this eliminates
1061 any changes you have made!
1064 @node Reverting all local changes
1065 @subsection Reverting all local changes
1067 Sometimes git will become hopelessly confused, and you just want
1068 to get back to a known, stable state. This command destroys any
1069 local changes you have made, but at least you get back to the
1070 current online version:
1073 git reset --hard origin/master
1077 @node Working with remote branches
1078 @subsection Working with remote branches
1081 @subsubheading Fetching new branches from git.sv.gnu.org
1083 To fetch and check out a new branch named @code{@var{branch}} on
1084 git.sv.gnu.org, run from top of the Git repository
1087 git config --add remote.origin.fetch \
1088 +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
1090 git checkout --track -b @var{branch} origin/@var{branch}
1093 After this, you can pull @code{@var{branch}} from git.sv.gnu.org
1100 Note that this command generally fetches all branches you added
1101 with @command{git@tie{}remote@tie{}add} (when you initialized the
1102 repository) or @command{git@tie{}config@tie{}--add}, i.e. it
1103 updates all remote branches from remote @code{origin}, then it
1104 merges the remote branch tracked by the current branch into the
1105 current branch. For example, if your current branch is
1106 @code{master}, @code{origin/master} will be merged into
1110 @subsubheading Local clones, or having several working trees
1112 If you play with several Git branches, e.g. @code{master},
1113 @code{lilypond/translation}, @code{stable/2.12}), you may want to
1114 have one source and build tree for each branch; this is possible
1115 with subdirectories of your local Git repository, used as local
1116 cloned subrepositories. To create a local clone for the branch
1117 named @code{@var{branch}}, run
1120 git checkout @var{branch}
1121 git clone -lsn . @var{subdir}
1126 Note that @code{@var{subdir}} must be a directory name which does
1127 not already exist. In @code{@var{subdir}}, you can use all Git
1128 commands to browse revisions history, commit and uncommit changes;
1129 to update the cloned subrepository with changes made on the main
1130 repository, cd into @code{@var{subdir}} and run
1131 @command{git@tie{}pull}; to send changes made on the subrepository
1132 back to the main repository, run @command{git@tie{}push} from
1133 @code{@var{subdir}}. Note that only one branch (the currently
1134 checked out branch) is created in the subrepository by default; it
1135 is possible to have several branches in a subrepository and do
1136 usual operations (checkout, merge, create, delete...) on these
1137 branches, but this possibility is not detailed here.
1139 When you push @code{@var{branch}} from @code{@var{subdir}} to the
1140 main repository, and @code{@var{branch}} is checked out in the
1141 main repository, you must save uncommitted changes (see
1142 @command{git@tie{}stash}) and do
1143 @command{git@tie{}reset@tie{}--hard} in the main repository in
1144 order to apply pushed changes in the working tree of the main
1152 The commands above don't only bring you the latest version of the
1153 sources, but also the full history of revisions (revisons, also
1154 called commits, are changes made to the sources), stored in the
1155 @file{.git} directory. You can browse this history with
1158 git log # only shows the logs (author, committish and commit message)
1159 git log -p # also shows diffs
1160 gitk # shows history graphically
1163 @warning{The @code{gitk} command may require a separate
1164 @code{gitk} package, available in the appropriate distribution's
1168 @node Applying remote patches
1169 @subsection Applying remote patches
1172 TODO: Explain how to determine if a patch was created with
1173 @code{git@tie{}format-patch}.
1175 Well-formed git patches created with @code{git@tie{}format-patch}
1176 should be committed with the following command:
1182 Patches created without @code{git@tie{}format-patch} can be
1183 applied in two steps. The first step is to apply the patch to the
1187 git apply @var{patch}
1191 The second step is to commit the changes and give credit to the
1192 author of the patch. This can be done with the following command:
1195 git commit -a --author="@var{John Smith} <@var{john@@example.com}>"
1199 @node Sending and receiving patches via email
1200 @subsection Sending and receiving patches via email
1203 The default @code{x-diff} MIME type associated with patch files
1204 (i.e., files whose name ends in @code{.patch}) means that the
1205 encoding of line endings may be changed from UNIX to DOS format
1206 when they are sent as attachments. Attempting to apply such an
1207 inadvertently altered patch will cause git to fail with a message
1208 about @q{whitespace errors}.
1210 The solution to such problems is surprisingly simple---just change
1211 the default file extension of patches generated by git to end in
1212 @code{.txt}, for example:
1215 git config format.suffix '.patch.txt'
1218 This should cause email programs to apply the correct base64
1219 encoding to attached patches.
1221 If you receive a patch with DOS instead of UNIX line-endings, it
1222 can be converted back using the @code{dos2unix} utility.
1224 Lots of useful information on email complications with patches is
1225 provided on the Wine wiki at
1226 @uref{http://wiki.winehq.org/GitWine}.
1230 @subsection Commit access
1233 Most contributors are not able to commit patches directly to the
1234 main repository---only members of the LilyPond development team
1235 have @emph{commit access}. If you are a contributor and are
1236 interested in joining the development team, contact the Project
1237 Manager through the mailing list
1238 (@email{lilypond-devel@@gnu.org}). Generally, only contributors
1239 who have already provided a number of patches which have been
1240 pushed to the main repository will be considered for membership.
1242 If you have been approved by the Project Manager, use the
1243 following procedure to obtain commit access:
1247 If you don't already have one, set up a Savannah user account at
1248 @uref{https://savannah.gnu.org/account/register.php}. If your web
1249 browser responds with an @qq{untrusted connection} message when
1250 you visit the link, follow the steps for including the CAcert root
1251 certificate in your browser, given at
1252 @uref{http://savannah.gnu.org/tls/tutorial/}.
1256 After registering, if you are not logged in automatically, login
1257 at @uref{https://savannah.gnu.org/account/login.php}---this should
1258 take you to your @qq{my} page
1259 (@uref{https://savannah.gnu.org/my/}).
1263 Click on the @qq{My Groups} link to access the @qq{My Group
1264 Membership} page. From there, find the @qq{Request for Inclusion}
1265 box and search for @qq{LilyPond}. Among the search results, check
1266 the box labeled @qq{GNU LilyPond Music Typesetter} and write a
1267 brief (required) message for the Project Manager (@qq{Hey it's
1268 me!} should be fine).
1270 Note that you will not have commit access until the Project
1271 Manager activates your membership. Once your membership is
1272 activated, LilyPond should appear under the heading @qq{Groups I'm
1273 Contributor of} on your @qq{My Group Membership} page.
1277 Generate an SSH @q{dsa} key pair. Enter the following at the
1284 When prompted for a location to save the key, press <ENTER> to
1285 accept the default location (@file{~/.ssh/id_dsa}).
1287 Next you are asked to enter an optional passphrase. On most
1288 systems, if you use a passphrase, you will likely be prompted for
1289 it every time you use @command{git@tie{}push} or
1290 @command{git@tie{}pull}. You may prefer this since it can protect
1291 you from your own mistakes (like pushing when you mean to pull),
1292 though you may find it tedious to keep re-entering it.
1294 You can change/enable/disable your passphrase at any time with:
1297 ssh-keygen -f ~/.ssh/id_dsa -p
1300 Note that the GNOME desktop has a feature which stores your
1301 passphrase for you for an entire GNOME session. If you use a
1302 passphrase to @qq{protect you from yourself}, you will want to
1303 disable this feature, since you'll only be prompted once. Run the
1304 following command, then logout of GNOME and log back in:
1307 gconftool-2 --set -t bool \
1308 /apps/gnome-keyring/daemon-components/ssh false
1311 After setting up your passphrase, your private key is saved as
1312 @file{~/.ssh/id_dsa} and your public key is saved as
1313 @file{~/.ssh/id_dsa.pub}.
1317 Register your public SSH @q{dsa} key with Savannah. From the
1318 @qq{My Account Configuration} page, click on @qq{Edit SSH Keys},
1319 then paste the contents of your @file{~/.ssh/id_dsa.pub} file into
1320 one of the @qq{Authorized keys} text fields, and click
1323 Savannah should respond with something like:
1326 Success: Key #1 seen Keys registered
1331 Configure Git to use the SSH protocol (instead of the GIT
1332 protocol). From your local Git repository, enter:
1335 git config remote.origin.url \
1336 ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1340 where @var{user} is your username on Savannah.
1344 After your membership has been activated and you’ve configured Git
1345 to use SSH, test the connection with:
1351 SSH should issue the following warning:
1354 The authenticity of host 'git.sv.gnu.org (140.186.70.72)' can't
1356 RSA key fingerprint is
1357 80:5a:b0:0c:ec:93:66:29:49:7e:04:2b:fd:ba:2c:d5.
1358 Are you sure you want to continue connecting (yes/no)?
1361 Make sure the RSA key fingerprint displayed matches the one above.
1362 If it doesn't, respond @qq{no} and check that you configured Git
1363 properly in the previous step. If it does match, respond
1364 @qq{yes}. SSH should then issue another warning:
1367 Warning: Permanently added 'git.sv.gnu.org,140.186.70.72' (RSA) to
1368 the list of known hosts.
1371 The list of known hosts is stored in the file
1372 @file{~/.ssh/known_hosts}.
1374 At this point, you are prompted for your passphrase if you have
1375 one, then Git will attempt a pull.
1377 If @command{git@tie{}pull@tie{}--verbose} fails, you should see
1378 error messages like these:
1381 Permission denied (publickey).
1382 fatal: The remote end hung up unexpectedly
1385 If you get the above error, you may have made a mistake when
1386 registering your SSH key at Savannah. If the key is properly
1387 registered, you probably just need to wait for the Savannah server
1388 to activate it. It usually takes a few minutes for the key to be
1389 active after registering it, but if it still doesn't work after an
1390 hour, ask for help on the mailing list.
1392 If @command{git@tie{}pull@tie{}--verbose} succeeds, the output
1393 will include a @q{From} line that shows @q{ssh} as the protocol:
1396 From ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond
1399 If the protocol shown is not @q{ssh}, check that you configured
1400 Git properly in the previous step.
1404 Test your commit access with a dry run:
1407 git push --dry-run --verbose
1410 Note that recent versions of Git (Git 1.6.3 or later) will issue a
1411 big warning if the above command is used. The simplest solution
1412 is to tell Git to push all matching branches by default:
1415 git config push.default matching
1419 Then @code{git@tie{}push} should work as before. For more
1420 details, consult the @code{git@tie{}push} man page.
1424 @subsubheading Technical details
1428 On Firefox, to view or remove the CAcert root certificate, go to:
1429 Edit > Preferences > Advanced > Encryption > View Certificates >
1430 Authorities > Certificate Name > Root CA > CA Cert Signing
1434 The @command{git@tie{}config} commands above should modify your
1435 local repository's @file{.git/config} file. These lines:
1439 url = git://git.sv.gnu.org/lilypond.git/
1443 should now be changed to:
1447 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1451 where @var{user} is your login name on Savannah.
1455 @command{git@tie{}config@tie{}push.default@tie{}matching} command
1456 should add these lines to @file{.git/config}:
1465 Encryption protocols, including ssh, generally do not permit packet
1466 fragmentation to avoid introducing a point of insecurity. This
1467 means that the maximum packet size must not exceed the smallest
1468 MTU (Maximum Transmission Unit) set in the routers along the path.
1469 This smallest MTU is determined by a procedure during call set-up
1470 which relies on the transmission over the path of ICMP packets.
1471 If any of the routers in the path block ICMP packets this mechanism
1472 fails, resulting in the possibility of packets being transmitted
1473 which exceed the MTU of one of the routers. If this happens the
1474 packet is discarded, causing the ssh session to hang, timeout or
1475 terminate with the error message
1478 ssh: connect to host <host ip addr> port 22: Bad file number
1479 fatal: The remote end hung up unexpectedly
1482 depending on precisely when in the proceedings the first large
1483 packet is transmitted. Most routers on the internet have MTU
1484 set to 1500, but routers installed in homes to connect via
1485 broadband may use a slightly smaller MTU for efficient transmission
1486 over ATM. If this problem is encountered a possible work-around is
1487 to set the MTU in the local router to 1500.
1489 @node Git on Windows
1490 @section Git on Windows
1492 @c Some of this may duplicate stuff in other sections
1493 @c But it is probably best for windows users to have it all together
1494 @c If necessary, clear this up later -td
1496 TODO: Decide what to do with this... Pare it down? Move
1497 paragraphs next to analogous Unix instructions? -mp
1499 @subsection Background to nomenclature
1501 Git is a system for tracking the changes made to source files by a
1502 distributed set of editors. It is designed to work without a
1503 master repository, but we have chosen to have a master respository
1504 for LilyPond files. Editors hold a local copy of the master
1505 repository together with any changes they have made locally.
1506 Local changes are held in a local @q{branch}, of which there may
1507 be several, but these instructions assume you are using just one.
1508 The files visible in the local repository always correspond to
1509 those on the currently @q{checked out} local branch.
1511 Files are edited on a local branch, and in that state the changes
1512 are said to be @q{unstaged}. When editing is complete, the
1513 changes are moved to being @q{staged for commit}, and finally the
1514 changes are @q{committed} to the local branch. Once committed,
1515 the changes (called a @q{commit}) are given a unique 40-digit
1516 hexadecimal reference number called the @q{Committish} or @q{SHA1
1517 ID} which identifies the commit to Git. Such committed changes
1518 can be sent to the master repository by @q{pushing} them (if you
1519 have write permission) or by sending them by email to someone who
1520 has, either as a complete file or as a @q{diff} or @q{patch}
1521 (which send just the differences from the master repository).
1523 @subsection Installing git
1526 @uref{http://code.google.com/p/msysgit/downloads/list} (note, not
1527 msysGit, which is for Git developers and not PortableGit, which is
1528 not a full git installation) and install it.
1530 Note that most users will not need to install SSH. That is not
1531 required until you have been granted direct push permissions to
1532 the master git repository.
1534 Start Git by clicking on the desktop icon. This will bring up a
1535 command line bash shell. This may be unfamiliar to Windows users.
1536 If so, follow these instructions carefully. Commands are entered
1537 at a $ prompt and are terminated by keying a newline.
1539 @subsection Initialising Git
1541 Decide where you wish to place your local Git repository, creating
1542 the folders in Windows as necessary. Here we call the folder to
1543 contain the repository @code{[path]/Git}, but if you intend using
1544 Git for other projects a directory name like @code{lilypond-git}
1545 might be better. You will need to have space for around
1548 Start the Git bash shell by clicking on the desk-top icon
1549 installed with Git and type
1555 to position the shell at your new Git repository.
1557 Note: if [path] contains folders with names containing spaces use
1569 to initialize your Git repository.
1571 Then type (all on one line; the shell will wrap automatically)
1574 git remote add -ft master origin git://git.sv.gnu.org/lilypond.git
1577 to download the lilypond master files.
1579 @warning{Be patient! Even on a broadband connection this can take
1580 10 minutes or more. Wait for lots of [new tag] messages and the $
1583 We now need to generate a local copy of the downloaded files in a
1584 new local branch. Your local branch needs to have a name. It is
1585 usual to call it @q{master} and we shall do that here.
1590 git checkout -b master origin/master
1593 This creates a second branch called @q{master}. You will see two
1594 warnings (ignore these), and a message advising you that your
1595 local branch @q{master} has been set up to track the remote
1596 branch. You now have two branches, a local branch called
1597 @q{master}, and a tracking branch called @q{origin/master}, which
1598 is a shortened form of @q{remotes/origin/master}.
1600 Return to Windows Explorer and look in your Git repository. You
1601 should see lots of folders. For example, the LilyPond
1602 documentation can be found in [path]/Git/Documentation/.
1604 The Git bash shell is terminated by typing @code{exit} or by
1605 clicking on the usual Windows close-window widget.
1609 Almost all subsequent work will use the Git Graphical User
1610 Interface, which avoids having to type command line commands. To
1611 start Git GUI first start the Git bash shell by clicking on the
1612 desktop icon, and type
1619 The Git GUI will open in a new window. It contains four panels
1620 and 7 pull-down menus. At this stage do not use any of the
1621 commands under Branch, Commit, Merge or Remote. These will be
1624 The top panel on the left contains the names of files which you
1625 are in the process of editing (Unstaged Changes), and the lower
1626 panel on the left contains the names of files you have finished
1627 editing and have staged ready for committing (Staged Changes). At
1628 present, these panels will be empty as you have not yet made any
1629 changes to any file. After a file has been edited and saved the
1630 top panel on the right will display the differences between the
1631 edited file selected in one of the panels on the left and the last
1632 version committed on the current branch.
1634 The panel at bottom right is used to enter a descriptive message
1635 about the change before committing it.
1637 The Git GUI is terminated by entering CNTL-Q while it is the
1638 active window or by clicking on the usual Windows close-window
1641 @subsection Personalising your local git repository
1643 Open the Git GUI, click on
1649 and enter your name and email address in the left-hand (Git
1650 Repository) panel. Leave everything else unchanged and save it.
1652 Note that Windows users must leave the default setting for line
1653 endings unchanged. All files in a git repository must have lines
1654 terminated by just a LF, as this is required for Merge to work,
1655 but Windows files are terminated by CRLF by default. The git
1656 default setting causes the line endings of files in a Windows git
1657 repository to be flipped automatically between LF and CRLF as
1658 required. This enables files to be edited by any Windows editor
1659 without causing problems in the git repository.
1661 @subsection Checking out a branch
1663 At this stage you have two branches in your local repository,
1664 both identical. To see them click on
1670 You should have one local branch called @q{master} and one
1671 tracking branch called @q{origin/master}. The latter is your
1672 local copy of the @q{remotes/origin/master} branch in the master
1673 LilyPond repository. The local @q{master} branch is where you
1674 will make your local changes.
1676 When a particular branch is selected, i.e., checked out, the files
1677 visible in your repository are changed to reflect the state of the
1678 files on that branch.
1680 @subsection Updating files from @q{remote/origin/master}
1682 Before starting the editing of a file, ensure your local
1683 repository contains the latest version of the files in the remote
1684 repository by first clicking
1687 Remote -> Fetch from -> origin
1693 This will place the latest version of every file, including all
1694 the changes made by others, into the @q{origin/master} branch of
1695 the tracking branches in your git repository. You can see these
1696 files by checking out this branch, but you must @emph{never} edit
1697 any files while this branch is checked out. Check out your local
1698 @q{master} branch again.
1700 You then need to merge these fetched files into your local
1701 @q{master} branch by clicking on
1704 Merge -> Local Merge
1708 and if necessary select the local @q{master} branch.
1710 Note that a merge cannot be completed if you have made any local
1711 changes which have not yet been committed.
1713 This merge will update all the files in the @q{master} branch to
1714 reflect the current state of the @q{origin/master} branch. If any
1715 of the changes conflict with changes you have made yourself
1716 recently you will be notified of the conflict (see below).
1718 @subsection Editing files
1720 First ensure your @q{master} branch is checked out, then simply
1721 edit the files in your local Git repository with your favourite
1722 editor and save them back there. If any file contains non-ASCII
1723 characters ensure you save it in UTF-8 format. Git will detect
1724 any changes whenever you restart Git GUI and the file names will
1725 then be listed in the Unstaged Changes panel. Or you can click
1726 the Rescan button to refresh the panel contents at any time. You
1727 may break off and resume editing any time.
1729 The changes you have made may be displayed in diff form in the top
1730 right-hand panel of Git GUI by clicking on the file name shown in
1731 one of the left panels.
1733 When your editing is complete, move the files from being Unstaged
1734 to Staged by clicking the document symbol to the left of each
1735 name. If you change your mind it can be moved back by clicking on
1736 the ticked box to the left of the name.
1738 Finally the changes you have made may be committed to your
1739 @q{master} branch by entering a brief message in the Commit
1740 Message box and clicking the Commit button.
1742 If you wish to amend your changes after a commit has been made,
1743 the original version and the changes you made in that commit may
1744 be recovered by selecting
1747 Commit -> Amend Last Commit
1751 or by checking the Amend Last Commit radio button at bottom right.
1752 This will return the changes to the Staged state, so further
1753 editing made be carried out within that commit. This must only be
1754 done @emph{before} the changes have been Pushed or sent to your
1755 mentor for Pushing - after that it is too late and corrections
1756 have to be made as a separate commit.
1759 @subsection Sending changes to @q{remotes/origin/master}
1761 If you do not have write access to @q{remotes/origin/master} you
1762 will need to send your changes by email to someone who does.
1764 First you need to create a diff or patch file containing your
1765 changes. To create this, the file must first be committed. Then
1766 terminate the Git GUI. In the git bash shell first cd to your Git
1773 if necessary, then produce the patch with
1776 git format-patch origin
1779 This will create a patch file for all the locally committed files
1780 which differ from @q{origin/master}. The patch file can be found
1781 in [path]/Git and will have a name formed from the commit message.
1783 @subsection Resolving merge conflicts
1785 As soon as you have committed a changed file your local
1786 @code{master} branch has diverged from @code{origin/master}, and
1787 will remain diverged until your changes have been committed in
1788 @code{remotes/origin/master} and Fetched back into your
1789 @code{origin/master} branch. Similarly, if a new commit has been
1790 made to @code{remotes/origin/master} by someone else and Fetched,
1791 your local @code{master} branch is divergent. You can detect a
1792 divergent branch by clicking on
1795 Repository -> Visualise all branch history
1798 This opens up a very useful new window called @q{gitk}. Use this
1799 to browse all the commits made by yourself and others.
1801 If the diagram at top left of the resulting window does not show
1802 your @code{master} tag on the same node as the
1803 @code{remotes/origin/master} tag your branch has diverged from
1804 @code{origin/master}. This is quite normal if files you have
1805 modified yourself have not yet been Pushed to
1806 @code{remotes/origin/master} and Fetched, or if files modified and
1807 committed by others have been Fetched since you last Merged
1808 @code{origin/master} into your local @code{master} branch.
1810 If a file being merged from @code{origin/master} differs from one
1811 you have modified in a way that cannot be resolved automatically
1812 by git, Merge will report a Conflict which you must resolve by
1813 editing the file to create the version you wish to keep.
1815 This could happen if the person updating
1816 @code{remotes/origin/master} for you has added some changes of his
1817 own before committing your changes to
1818 @code{remotes/origin/master}, or if someone else has changed the
1819 same file since you last fetched the file from
1820 @code{remotes/origin/master}.
1822 Open the file in your editor and look for sections which are
1825 [to be completed when I next have a merge conflict to be sure I
1826 give the right instructions -td]
1829 @subsection Other actions
1831 The instructions above describe the simplest way of using git on
1832 Windows. Other git facilities which may usefully supplement these
1836 @item Using multiple local branches (Create, Rename, Delete)
1837 @item Resetting branches
1838 @item Cherry-picking commits
1839 @item Pushing commits to @w{remote/origin/master}
1840 @item Using gitk to review history
1843 Once familiarity with using git on Windows has been gained the
1844 standard git manuals can be used to learn about these.
1847 @node Repository directory structure
1848 @section Repository directory structure
1851 @c TODO: integrate the roadmap better
1852 @verbatiminclude ROADMAP
1855 @node Other Git documentation
1856 @section Other Git documentation
1860 Official git man pages:
1861 @uref{http://www.kernel.org/pub/software/scm/git/docs/}
1864 More in-depth tutorials: @uref{http://git-scm.com/documentation}
1867 Book about git: @uref{http://progit.org/,Pro Git}