1 @c -*- coding: utf-8; mode: texinfo; -*-
4 @node Working with source code
5 @chapter Working with source code
7 @warning{New contributors should read @ref{Quick start}, and in
8 particular @ref{Using lily-git}, instead of this chapter.}
10 Advanced contributors will find this material quite useful,
11 particularly if they are working on major new features.
15 * Basic Git procedures::
16 * Advanced Git procedures::
18 * Repository directory structure::
19 * Other Git documentation::
23 @node Starting with Git
24 @section Starting with Git
26 Using the Git program directly (as opposed to using the
27 @command{lily-git.tcl} GUI) allows you to have much greater control
28 over the contributing process. You should consider using Git if
29 you want to work on complex projects, or if you want to work on
30 multiple projects concurrently.
35 * Downloading remote branches::
40 @subsection Setting up
43 TODO: Remove this note if incorporating Windows instructions
44 throughout this section:
46 @warning{These instructions assume that you are using the
47 command-line version of Git 1.5 or higher. Windows users should
48 skip to @ref{Git on Windows}.}
52 * Initializing a repository::
58 @unnumberedsubsubsec Installing Git
61 If you are using a Unix-based machine, the easiest way to download
62 and install Git is through a package manager such as @command{rpm}
63 or @command{apt-get}---the installation is generally automatic.
64 The only required package is (usually) called @command{git-core},
65 although some of the auxiliary @command{git@var{*}} packages are
66 also useful (such as @command{gitk}).
68 Alternatively, you can visit the Git website
69 (@uref{http://git-scm.com/}) for downloadable binaries and
72 TODO: add Windows installation instructions (or @@ref@{Git on
76 @node Initializing a repository
77 @unnumberedsubsubsec Initializing a repository
80 Once Git is installed, you'll need to create a new directory where
81 your initial repository will be stored (the example below uses
82 @file{~/lilypond-git/}, where @code{~} represents your home
83 directory). Run @command{git@tie{}init} from within the new
84 directory to initialize an empty repository:
87 mkdir ~/lilypond-git/; cd ~/lilypond-git/
91 @subsubheading Technical details
93 This creates (within the @file{~/lilypond-git/} directory) a
94 subdirectory called @file{.git/}, which Git uses to keep track of
95 changes to the repository, among other things. Normally you don't
96 need to access it, but it's good to know it's there.
100 @unnumberedsubsubsec Configuring Git
102 @warning{Throughout the rest of this manual, all command-line
103 input should be entered from the top directory of the Git
104 repository being discussed (eg. @file{~/lilypond-git/}). This is
105 referred to as the @emph{top source directory}.}
107 Before downloading a copy of the main LilyPond repository, you
108 should configure some basic settings with the
109 @command{git@tie{}config} command. Git allows you to set both
110 global and repository-specific options.
112 To configure settings that affect all repositories, use the
113 @command{--global} command line option. For example, the first
114 two options that you should always set are your @var{name} and
115 @var{email}, since Git needs these to keep track of commit
119 git config --global user.name "@var{John Smith}"
120 git config --global user.email @var{john@@example.com}
123 To configure Git to use colored output where possible, use:
126 git config --global color.ui auto
129 The text editor that opens when using @command{git@tie{}commit}
130 can also be changed. If none of your editor-related environment
131 variables are set ($GIT_EDITOR, $VISUAL, or $EDITOR), the default
132 editor is usually @command{vi} or @command{vim}. If you're not
133 familiar with either of these, you should probably change the
134 default to an editor that you know how to use. For example, to
135 change the default editor to @command{nano}, enter:
138 git config --global core.editor @var{nano}
141 TODO: Add instructions for changing the editor on Windows, which
142 is a little different, I think. -mp
144 @subsubheading Technical details
146 Git stores the information entered with
147 @command{git@tie{}config@tie{}--global} in the file
148 @file{.gitconfig}, located in your home directory. This file can
149 also be modified directly, without using
150 @command{git@tie{}config}. The @file{.gitconfig} file generated
151 by the above commands would look like this:
156 email = john@@example.com
163 Using the @command{git@tie{}config} command @emph{without} the
164 @command{--global} option configures repository-specific settings,
165 which are stored in the file @file{.git/config}. This file is
166 created when a repository is initialized (using
167 @command{git@tie{}init}), and by default contains these lines:
171 repositoryformatversion = 0
174 logallrefupdates = true
177 However, since different repository-specific options are
178 recommended for different development tasks, it is best to avoid
179 setting any now. Specific recommendations will be mentioned later
183 @node Downloading remote branches
184 @subsection Downloading remote branches
188 * Organization of remote branches::
189 * LilyPond repository sources::
190 * Downloading individual branches::
191 * Downloading all remote branches::
196 @node Organization of remote branches
197 @unnumberedsubsubsec Organization of remote branches
200 The main LilyPond repository is organized into @emph{branches} to
201 facilitate development. These are often called @emph{remote}
202 branches to distinguish them from @emph{local} branches you might
203 create yourself (see @ref{Using local branches}).
205 The @code{master} branch contains all the source files used to
206 build LilyPond, which includes the program itself (both stable and
207 development releases), the documentation (and its translations),
208 and the website. Generally, the @code{master} branch is expected
209 to compile successfully.
211 The @code{lilypond/translation} branch is a side branch that
212 allows translators to work without needing to worry about
213 compilation problems. Periodically, the Translation Meister
214 (after verifying that it doesn't break compilation), will
215 @emph{merge} this branch back into @code{master} to incorporate
216 recent translations. Similarly, the @code{master} branch is
217 usually merged into the @code{lilypond/translation} branch after
218 significant changes to the English documentation. See
219 @ref{Translating the documentation} for details.
222 @node LilyPond repository sources
223 @unnumberedsubsubsec LilyPond repository sources
226 The recommended source for downloading a copy of the main
230 git://git.sv.gnu.org/lilypond.git
233 However, if your internet router filters out connections using the
234 GIT protocol, or if you experience difficulty connecting via GIT,
235 you can try these other sources:
238 ssh://git.sv.gnu.org/srv/git/lilypond.git
239 http://git.sv.gnu.org/r/lilypond.git
242 The SSH protocol can only be used if your system is properly set
243 up to use it. Also, the HTTP protocol is slowest, so it should
244 only be used as a last resort.
247 @node Downloading individual branches
248 @unnumberedsubsubsec Downloading individual branches
251 Once you have initialized an empty Git repository on your system
252 (see @ref{Initializing a repository}), you can download a remote
253 branch into it. Make sure you know which branch you want to start
256 To download the @code{master} branch, enter the following:
259 git remote add -ft master -m master \
260 origin git://git.sv.gnu.org/lilypond.git/
263 To download the @code{lilypond/translation} branch, enter:
266 git remote add -ft lilypond/translation -m \
267 lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
270 The @command{git@tie{}remote@tie{}add} process could take up to
271 ten minutes, depending on the speed of your connection. The
272 output will be something like this:
276 remote: Counting objects: 235967, done.
277 remote: Compressing objects: 100% (42721/42721), done.
278 remote: Total 235967 (delta 195098), reused 233311 (delta 192772)
279 Receiving objects: 100% (235967/235967), 68.37 MiB | 479 KiB/s, done.
280 Resolving deltas: 100% (195098/195098), done.
281 From git://git.sv.gnu.org/lilypond
282 * [new branch] master -> origin/master
283 From git://git.sv.gnu.org/lilypond
284 * [new tag] flower/1.0.1 -> flower/1.0.1
285 * [new tag] flower/1.0.10 -> flower/1.0.10
287 * [new tag] release/2.9.6 -> release/2.9.6
288 * [new tag] release/2.9.7 -> release/2.9.7
291 When @command{git@tie{}remote@tie{}add} is finished, the remote
292 branch should be downloaded into your repository---though not yet
293 in a form that you can use. In order to browse the source code
294 files, you need to @emph{create} and @emph{checkout} your own
295 local branch. In this case, however, it is easier to have Git
296 create the branch automatically by using the @command{checkout}
297 command on a non-existent branch. Enter the following:
300 git checkout -b @var{branch} origin/@var{branch}
304 where @code{@var{branch}} is the name of your tracking branch,
305 either @code{master} or @code{lilypond/translation}.
307 Git will issue some warnings; this is normal:
310 warning: You appear to be on a branch yet to be born.
311 warning: Forcing checkout of origin/master.
312 Branch master set up to track remote branch master from origin.
316 By now the source files should be accessible---you should be able
317 to edit any files in the @file{lilypond-git/} directory using a
318 text editor of your choice. But don't start just yet! Before
319 editing any source files, learn how to keep your changes organized
320 and prevent problems later---read @ref{Basic Git procedures}.
322 @subsubheading Technical Details
324 The @command{git@tie{}remote@tie{}add} command should add some
325 lines to your local repository's @file{.git/config} file:
329 url = git://git.sv.gnu.org/lilypond.git/
330 fetch = +refs/heads/master:refs/remotes/origin/master
334 @node Downloading all remote branches
335 @unnumberedsubsubsec Downloading all remote branches
338 To download all remote branches at once, you can @command{clone}
339 the entire repository:
342 git clone git://git.sv.gnu.org/lilypond.git
347 @unnumberedsubsubsec Other branches
349 Most contributors will never need to touch the other branches. If
350 you wish to do so, you will need more familiarity with Git; please
351 see @ref{Other Git documentation}.
354 @item @code{dev/XYZ}:
355 These branches are for individual developers. They store code
356 which is not yet stable enough to be added to the @code{master}
359 @item @code{stable/XYZ}:
360 The branches are kept for archival reasons.
364 Another item of interest might be the Grand Unified Builder, our
365 cross-platform building tool. Since it is used by projects as
366 well, it is not stored in our gub repository. For more info, see
367 @uref{http://lilypond.org/gub}. The git location is
368 @uref{http://github.com/janneke/gub}.
371 @node Basic Git procedures
372 @section Basic Git procedures
376 * The Git contributor's cycle::
377 * Pulling and rebasing::
378 * Using local branches::
379 * Commits and patches::
383 @node The Git contributor's cycle
384 @subsection The Git contributor's cycle
387 Here is a simplified view of the contribution process on Git:
391 Update your local repository by @emph{pulling} the most recent
392 updates from the remote repository.
395 Edit source files within your local repository's @emph{working
399 @emph{Commit} the changes you've made to a local @emph{branch}.
402 Generate a @emph{patch} to share your changes with the developers.
406 @node Pulling and rebasing
407 @subsection Pulling and rebasing
410 When developers push new patches to the @code{git.sv.gnu.org}
411 repository, your local repository is @strong{not} automatically
412 updated. It is important to keep your repository up-to-date by
413 periodically @emph{pulling} the most recent @emph{commits} from
414 the remote branch. Developers expect patches to be as current as
415 possible, since outdated patches require extra work before they
418 Occasionally you may need to rework some of your own modifications
419 to match changes made to the remote branch (see @ref{Resolving
420 conflicts}), and it's considerably easier to rework things
421 incrementally. If you don't update your repository along the way,
422 you may have to spend a lot of time resolving branch conflicts and
423 reconfiguring much of the work you've already done.
425 Fortunately, Git is able to resolve certain types of branch
426 conflicts automatically with a process called @emph{rebasing}.
427 When rebasing, Git tries to modify your old commits so they appear
428 as new commits (based on the latest updates). For a more involved
429 explanation, see the @command{git-rebase} man page.
431 To pull without rebasing (recommended for translators), use the
435 git pull # recommended for translators
438 If you're tracking the remote @code{master} branch, you should add
439 the @code{-r} option (short for @code{--rebase}) to keep commits
440 on your local branch current:
443 git pull -r # use with caution when translating
446 If you don't edit translated documentation and don't want to type
447 @code{-r} every time, configure the master branch to rebase by
448 default with this command:
451 git config branch.master.rebase true
454 If pull fails because of a message like
457 error: Your local changes to 'Documentation/learning/tutorial.itely'
458 would be overwritten by merge. Aborting.
465 Documentation/learning/tutorial.itely: needs update
466 refusing to pull with rebase: your working tree is not up-to-date
470 it means that you have modified some files in you working tree
471 without committing changes (see @ref{Commits and patches}); you
472 can use the @command{git@tie{}stash} command to work around this:
475 git stash # save uncommitted changes
476 git pull -r # pull using rebase (translators omit "-r")
477 git stash pop # reapply previously saved changes
480 Note that @command{git@tie{}stash@tie{}pop} will try to apply a
481 patch, and this may create a conflict. If this happens, see
482 @ref{Resolving conflicts}.
484 TODO: I think the next paragraph is confusing. Perhaps prepare
485 the reader for new terms `committish' and `head'? -mp
487 @warning{translators and documentation editors, if you have
488 changed committishes in the head of translated files using commits
489 you have not yet pushed to @code{git.sv.gnu.org}, please do not
490 rebase. If you want to avoid wondering whether you should rebase
491 each time you pull, please always use committishes from master
492 and/or lilypond/translation branch on @code{git.sv.gnu.org}, which
493 in particular implies that you must push your changes to
494 documentation except committishes updates (possibly after having
495 rebased), then update the committishes and push them.}
497 TODO: when committishes automatic conditional update have been
498 tested and documented, append the following to the warning above:
499 Note that using update-committishes make target generally touches
502 @subsubheading Technical details
504 The @command{git@tie{}config} command mentioned above adds the
505 line @code{rebase = true} to the master branch in your local
506 repository's @file{.git/config} file:
511 merge = refs/heads/master
516 @node Using local branches
517 @subsection Using local branches
521 * Creating and removing branches::
522 * Listing branches and remotes::
523 * Checking out branches::
528 @node Creating and removing branches
529 @unnumberedsubsubsec Creating and removing branches
532 Local branches are useful when you're working on several different
533 projects concurrently. To create a new branch, enter:
536 git branch @var{name}
539 To delete a branch, enter:
542 git branch -d @var{name}
545 Git will ask you for confirmation if it sees that data would be
546 lost by deleting the branch. Use @code{-D} instead of @code{-d}
547 to bypass this. Note that you cannot delete a branch if it is
548 currently checked out.
551 @node Listing branches and remotes
552 @unnumberedsubsubsec Listing branches and remotes
554 You can get the exact path or URL of all remote branches by
561 To list Git branches on your local repositories, run
564 git branch # list local branches only
565 git branch -r # list remote branches
566 git branch -a # list all branches
570 @node Checking out branches
571 @unnumberedsubsubsec Checking out branches
573 To know the currently checked out branch, i.e. the branch whose
574 source files are present in your working tree, read the first line
582 The currently checked out branch is also marked with an asterisk
583 in the output of @command{git branch}.
585 You can check out another branch @code{@var{other_branch}}, i.e.
586 check out @code{@var{other_branch}} to the working tree, by
590 git checkout @var{other_branch}
593 Note that it is possible to check out another branch while having
594 uncommitted changes, but it is not recommended unless you know
595 what you are doing; it is recommended to run @command{git status}
596 to check this kind of issue before checking out another branch.
598 @node Merging branches
599 @unnumberedsubsubsec Merging branches
601 To merge branch @code{@var{foo}} into branch @code{@var{bar}},
602 i.e. to @qq{add} all changes made in branch @code{@var{foo}} to
603 branch @code{@var{bar}}, run
606 git checkout @var{bar}
610 If any conflict happens, see @ref{Resolving conflicts}.
612 There are common usage cases for merging: as a translator, you
613 will often want to merge @code{master} into
614 @code{lilypond/translation}; on the other hand, the Translations
615 meister wants to merge @code{lilypond/translation} into
616 @code{master} whenever he has checked that
617 @code{lilypond/translation} builds successfully.
620 @node Commits and patches
621 @subsection Commits and patches
625 * Understanding commits::
629 * Uploading a patch for review::
633 @node Understanding commits
634 @unnumberedsubsubsec Understanding commits
636 Technically, a @emph{commit} is a single point in the history of a
637 branch, but most developers use the term to mean a @emph{commit
638 object}, which stores information about a particular revision. A
639 single commit can record changes to multiple source files, and
640 typically represents one logical set of related changes (such as a
641 bug-fix). You can list the ten most recent commits in your
642 current branch with this command:
645 git log -10 --oneline
648 If you're using an older version of Git and get an @q{unrecognized
649 argument} error, use this instead:
652 git log -10 --pretty=oneline --abbrev-commit
655 More interactive lists of the commits on the remote @code{master}
656 branch are available at
657 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=shortlog} and
658 @uref{http://git.sv.gnu.org/cgit/lilypond.git/log/}.
662 @unnumberedsubsubsec Making commits
665 Once you have modified some source files in your working
666 directory, you can make a commit with the following procedure:
670 Make sure you've configured Git properly (see @ref{Configuring
671 Git}). Check that your changes meet the requirements described in
672 @ref{Code style} and/or @ref{Documentation policy}. For advanced
673 edits, you may also want to verify that the changes don't break
674 the compilation process.
677 Run the following command:
684 to make sure you're on the right branch, and to see which files
685 have been modified, added or removed, etc. You may need to tell
686 Git about any files you've added by running one of these:
689 git add @var{file} # add untracked @var{file} individually
690 git add . # add all untracked files in current directory
694 After @command{git@tie{}add}, run @command{git@tie{}status} again
695 to make sure you got everything. You may also need to modify
699 Preview the changes about to be committed (to make sure everything
707 The @code{HEAD} argument refers to the most recent commit on the
708 currently checked-out branch.
711 Generate the commit with:
718 The @code{-a} is short for @code{--all} which includes modified
719 and deleted files, but only those newly created files that have
720 previously been added.
725 @node Commit messages
726 @unnumberedsubsubsec Commit messages
729 When you run the @command{git@tie{}commit@tie{}-a} command, Git
730 automatically opens the default text editor so you can enter a
731 @emph{commit message}. If you find yourself in a foreign editing
732 environment, you're probably in @command{vi} or @command{vim}. If
733 you want to switch to an editor you're more familiar with, quit by
734 typing @code{:q!} and pressing @code{<Enter>}. See
735 @ref{Configuring Git} for instructions on changing the default
738 In any case, Git will open a text file for your commit message
739 that looks like this:
743 # Please enter the commit message for your changes. Lines starting
744 # with '#' will be ignored, and an empty message aborts the commit.
746 # Changes to be committed:
747 # (use "git reset HEAD <file>..." to unstage)
749 # modified: working.itexi
753 Your commit message should begin with a one-line summary
754 describing the change (no more than 50 characters long), and if
755 necessary a blank line followed by several lines giving the
758 @c $ git log -1 --pretty=medium 4d6f1e5
760 Doc: add Baerenreiter and Henle solo cello suites
762 Added comparison of solo cello suite engravings to new essay with
763 high-res images, fixed cropping on Finale example.
766 Commit messages often start with a short prefix describing the
767 general location of the changes. If a commit affects the
768 documentation in English (or in several languages simultaneously)
769 the commit message should be prefixed with @qq{Doc:@tie{}}. If
770 the commit affects only one of the translations, the commit
771 message should be prefixed with @qq{Doc-@var{**}:@tie{}}, where
772 @var{**} is the two-letter language code. Commits that affect the
773 website should use @qq{Web:@tie{}} for English, and
774 @qq{Web-@var{**}:@tie{}} for the other languages. Also, changes
775 to a single file are often prefixed with the name of the file
776 involved. Visit the links listed in @ref{Understanding commits}
781 @unnumberedsubsubsec Making patches
783 If you want to share your changes with other contributors and
784 developers, you need to generate @emph{patches} from your commits.
785 We prefer it if you follow the instructions in
786 @ref{Uploading a patch for review}. However, we present an
787 alternate method here.
789 You should always run @command{git@tie{}pull@tie{}-r} (translators
790 should leave off the @code{-r}) before doing this to ensure that
791 your patches are as current as possible.
793 Once you have made one or more commits in your local repository,
794 and pulled the most recent commits from the remote branch, you can
795 generate patches from your local commits with the command:
798 git format-patch origin
801 The @code{origin} argument refers to the remote tracking branch at
802 @code{git.sv.gnu.org}. This command generates a separate patch
803 for each commit that's in the current branch but not in the remote
804 branch. Patches are placed in the current working directory and
805 will have names that look something like this:
808 0001-Doc-Fix-typos.patch
809 0002-Web-Remove-dead-links.patch
813 Send an email (must be less than 64 KB) to
814 @email{lilypond-devel@@gnu.org} briefly explaining your work, with
815 the patch files attached. Translators should send patches to
816 @email{translations@@lilynet.net}. After your patches are
817 reviewed, the developers may push one or more of them to the main
818 repository or discuss them with you.
821 @node Uploading a patch for review
822 @unnumberedsubsubsec Uploading a patch for review
824 Any non-trivial change should be uploaded to our @qq{Rietveld}
828 @uref{http://codereview.appspot.com/}
831 @subsubheading Initial setup
836 You must have a gmail account.
839 Install @command{git-cl} by entering:
842 git clone git://neugierig.org/git-cl.git
846 Add the @file{git-cl/} directory to your PATH, or create a
847 symbolic link to the @command{git-cl} and @command{upload.py}
848 scripts in one of your PATH directories (such as
853 Move into the top source directory and then configure
854 @command{git cl}. If you do not understand any question, just
855 answer with a newline (CR).
858 cd $HOME/lilypond-git/
862 The @qq{CC list} question should be answered with:
865 lilypond-devel@@gnu.org
870 @subsubheading Uploading patch set
872 @warning{Unless you are familiar with branches, only work on one
873 set of changes at once.}
875 There are two methods, depending on your git setup.
879 @strong{Master branch}: (easy option, and used in @command{lily-git.tcl})
881 If you added your patch to @code{master}, then:
885 git cl upload origin/master
888 If you have git push ability, make sure that you @emph{remove}
889 your patch (with @command{git rebase} or @command{git reset})
890 before pushing other stuff.
893 @strong{Separate branch}: (complicated option)
895 Ensure your changes are committed in a separate branch, which
896 should differ from the reference branch to be used by just the
897 changes to be uploaded. If the reference branch is to be
898 origin/master, ensure this is up-to-date. If necessary, use git
899 rebase to rebase the branch containing the changes to the head of
900 origin/master. Finally, check out branch with the changes and
904 git cl upload <reference SHA1 ID>
908 where <reference SHA1 ID> is the SHA1 ID of the commit to be used
909 as a reference source for the patch. Generally, this will be the
910 SHA1 ID of origin/master, and in that case the command:
913 git cl upload origin/master
921 After prompting for your Google email address and password, the
922 patch set will be posted to Rietveld, and you will be given a URL
925 @subsubheading Announcing your patch set
927 You should then announce the patch by logging into the code review
928 issue webpage and using @qq{Publish + Mail Comments} to add a
929 (mostly bogus) comment to your issue. The text of your comment
930 will be sent to our developer mailing list.
932 @subsubheading Revisions
934 As revisions are made in response to comments, successive patch sets
935 for the same issue can be uploaded by reissuing the git-cl command
936 with the modified branch checked out.
938 Sometimes in response to comments on revisions, the best way to
939 work may require creation of a new branch in git. In order to
940 associate the new branch with an existing Rietveld issue,
941 the following command can be used:
944 git cl issue issue-number
948 where @code{issue-number} is the number of the existing Rietveld
951 @subsubheading Resetting git cl
953 If @command{git cl} becomes confused, you can @qq{reset} it by
961 @node Advanced Git procedures
962 @section Advanced Git procedures
965 @warning{This section is not necessary for normal contributors;
966 these commands are presented for information for people interested
967 in learning more about git.}
969 It is possible to work with several branches on the same local Git
970 repository; this is especially useful for translators who may have
971 to deal with both @code{lilypond/translation} and a stable branch,
972 e.g. @code{stable/2.12}.
974 Some Git commands are introduced first, then a workflow with
975 several Git branches of LilyPond source code is presented.
979 * Advanced Git concepts::
980 * Resolving conflicts::
981 * Reverting all local changes::
982 * Working with remote branches::
984 * Applying remote patches::
985 * Sending and receiving patches via email::
990 @node Advanced Git concepts
991 @subsection Advanced Git concepts
994 A bit of Git vocabulary will be explained below. The following is
995 only introductory; for a better understanding of Git concepts, you
996 may wish to read @ref{Other Git documentation}.
998 The @code{git@tie{}pull@tie{}origin} command above is just a
999 shortcut for this command:
1002 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
1006 where @code{@var{branch}} is typically @code{master} or
1007 @code{lilypond/translation}; if you do not know or remember, see
1008 @ref{Downloading remote branches} to remember which commands you
1009 issued or which source code you wanted to get.
1011 A @emph{commit} is a set of changes made to the sources; it also
1012 includes the committish of the parent commit, the name and e-mail
1013 of the @emph{author} (the person who wrote the changes), the name
1014 and e-mail of the @emph{committer} (the person who brings these
1015 changes into the Git repository), and a commit message.
1017 A @emph{committish} is the SHA1 checksum of a commit, a number
1018 made of 40 hexadecimal digits, which acts as the internal unique
1019 identifier for this commit. To refer to a particular revision,
1020 don't use vague references like the (approximative) date, simply
1021 copy and paste the committish.
1023 A @emph{branch} is nothing more than a pointer to a particular
1024 commit, which is called the @emph{head} of the branch; when
1025 referring to a branch, one often actually thinks about its head
1026 and the ancestor commits of the head.
1028 Now we will explain the two last commands you used to get the
1029 source code from Git---see @ref{Downloading individual branches}.
1032 git remote add -ft @var{branch} -m @var{branch} \
1033 origin git://git.sv.gnu.org/lilypond.git/
1035 git checkout -b @var{branch} origin/@var{branch}
1038 The @command{git@tie{}remote} has created a branch called
1039 @code{origin/@var{branch}} in your local Git repository. As this
1040 branch is a copy of the remote branch web from git.sv.gnu.org
1041 LilyPond repository, it is called a @emph{remote branch}, and is
1042 meant to track the changes on the branch from git.sv.gnu.org: it
1043 will be updated every time you run
1044 @command{git@tie{}pull@tie{}origin} or
1045 @command{git@tie{}fetch@tie{}origin}.
1047 The @command{git@tie{}checkout} command has created a branch named
1048 @code{@var{branch}}. At the beginning, this branch is identical
1049 to @code{origin/@var{branch}}, but it will differ as soon as you
1050 make changes, e.g. adding newly translated pages or editing some
1051 documentation or code source file. Whenever you pull, you merge
1052 the changes from @code{origin/@var{branch}} and
1053 @code{@var{branch}} since the last pulling. If you do not have
1054 push (i.e. @qq{write}) access on git.sv.gnu.org, your
1055 @code{@var{branch}} will always differ from
1056 @code{origin/@var{branch}}. In this case, remember that other
1057 people working like you with the remote branch @code{@var{branch}}
1058 of git://git.sv.gnu.org/lilypond.git/ (called
1059 @code{origin/@var{branch}} on your local repository) know nothing
1060 about your own @code{@var{branch}}: this means that whenever you
1061 use a committish or make a patch, others expect you to take the
1062 latest commit of @code{origin/@var{branch}} as a reference.
1064 Finally, please remember to read the man page of every Git command
1065 you will find in this manual in case you want to discover
1066 alternate methods or just understand how it works.
1069 @node Resolving conflicts
1070 @subsection Resolving conflicts
1073 Occasionally an update may result in conflicts -- this happens
1074 when you and somebody else have modified the same part of the same
1075 file and git cannot figure out how to merge the two versions
1076 together. When this happens, you must manually merge the two
1079 If you need some documentation to understand and resolve
1080 conflicts, see paragraphs @emph{How conflicts are presented} and
1081 @emph{How to resolve conflicts} in @command{git merge} man page.
1083 If all else fails, you can follow the instructions in
1084 @ref{Reverting all local changes}. Be aware that this eliminates
1085 any changes you have made!
1088 @node Reverting all local changes
1089 @subsection Reverting all local changes
1091 Sometimes git will become hopelessly confused, and you just want
1092 to get back to a known, stable state. This command destroys any
1093 local changes you have made, but at least you get back to the
1094 current online version:
1097 git reset --hard origin/master
1101 @node Working with remote branches
1102 @subsection Working with remote branches
1105 @subsubheading Fetching new branches from git.sv.gnu.org
1107 To fetch and check out a new branch named @code{@var{branch}} on
1108 git.sv.gnu.org, run from top of the Git repository
1111 git config --add remote.origin.fetch \
1112 +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
1114 git checkout --track -b @var{branch} origin/@var{branch}
1117 After this, you can pull @code{@var{branch}} from git.sv.gnu.org
1124 Note that this command generally fetches all branches you added
1125 with @command{git@tie{}remote@tie{}add} (when you initialized the
1126 repository) or @command{git@tie{}config@tie{}--add}, i.e. it
1127 updates all remote branches from remote @code{origin}, then it
1128 merges the remote branch tracked by the current branch into the
1129 current branch. For example, if your current branch is
1130 @code{master}, @code{origin/master} will be merged into
1134 @subsubheading Local clones, or having several working trees
1136 If you play with several Git branches, e.g. @code{master},
1137 @code{lilypond/translation}, @code{stable/2.12}), you may want to
1138 have one source and build tree for each branch; this is possible
1139 with subdirectories of your local Git repository, used as local
1140 cloned subrepositories. To create a local clone for the branch
1141 named @code{@var{branch}}, run
1144 git checkout @var{branch}
1145 git clone -lsn . @var{subdir}
1150 Note that @code{@var{subdir}} must be a directory name which does
1151 not already exist. In @code{@var{subdir}}, you can use all Git
1152 commands to browse revisions history, commit and uncommit changes;
1153 to update the cloned subrepository with changes made on the main
1154 repository, cd into @code{@var{subdir}} and run
1155 @command{git@tie{}pull}; to send changes made on the subrepository
1156 back to the main repository, run @command{git@tie{}push} from
1157 @code{@var{subdir}}. Note that only one branch (the currently
1158 checked out branch) is created in the subrepository by default; it
1159 is possible to have several branches in a subrepository and do
1160 usual operations (checkout, merge, create, delete...) on these
1161 branches, but this possibility is not detailed here.
1163 When you push @code{@var{branch}} from @code{@var{subdir}} to the
1164 main repository, and @code{@var{branch}} is checked out in the
1165 main repository, you must save uncommitted changes (see
1166 @command{git@tie{}stash}) and do
1167 @command{git@tie{}reset@tie{}--hard} in the main repository in
1168 order to apply pushed changes in the working tree of the main
1176 The commands above don't only bring you the latest version of the
1177 sources, but also the full history of revisions (revisions, also
1178 called commits, are changes made to the sources), stored in the
1179 @file{.git} directory. You can browse this history with
1182 git log # only shows the logs (author, committish and commit message)
1183 git log -p # also shows diffs
1184 gitk # shows history graphically
1187 @warning{The @code{gitk} command may require a separate
1188 @code{gitk} package, available in the appropriate distribution's
1192 @node Applying remote patches
1193 @subsection Applying remote patches
1196 TODO: Explain how to determine if a patch was created with
1197 @code{git@tie{}format-patch}.
1199 Well-formed git patches created with @code{git@tie{}format-patch}
1200 should be committed with the following command:
1206 Patches created without @code{git@tie{}format-patch} can be
1207 applied in two steps. The first step is to apply the patch to the
1211 git apply @var{patch}
1215 The second step is to commit the changes and give credit to the
1216 author of the patch. This can be done with the following command:
1219 git commit -a --author="@var{John Smith} <@var{john@@example.com}>"
1223 @node Sending and receiving patches via email
1224 @subsection Sending and receiving patches via email
1227 The default @code{x-diff} MIME type associated with patch files
1228 (i.e., files whose name ends in @code{.patch}) means that the
1229 encoding of line endings may be changed from UNIX to DOS format
1230 when they are sent as attachments. Attempting to apply such an
1231 inadvertently altered patch will cause git to fail with a message
1232 about @q{whitespace errors}.
1234 The solution to such problems is surprisingly simple---just change
1235 the default file extension of patches generated by git to end in
1236 @code{.txt}, for example:
1239 git config format.suffix '.patch.txt'
1242 This should cause email programs to apply the correct base64
1243 encoding to attached patches.
1245 If you receive a patch with DOS instead of UNIX line-endings, it
1246 can be converted back using the @code{dos2unix} utility.
1248 Lots of useful information on email complications with patches is
1249 provided on the Wine wiki at
1250 @uref{http://wiki.winehq.org/GitWine}.
1254 @subsection Commit access
1257 Most contributors are not able to commit patches directly to the
1258 main repository---only members of the LilyPond development team
1259 have @emph{commit access}. If you are a contributor and are
1260 interested in joining the development team, contact the Project
1261 Manager through the mailing list
1262 (@email{lilypond-devel@@gnu.org}). Generally, only contributors
1263 who have already provided a number of patches which have been
1264 pushed to the main repository will be considered for membership.
1266 If you have been approved by the Project Manager, use the
1267 following procedure to obtain commit access:
1271 If you don't already have one, set up a Savannah user account at
1272 @uref{https://savannah.gnu.org/account/register.php}. If your web
1273 browser responds with an @qq{untrusted connection} message when
1274 you visit the link, follow the steps for including the CAcert root
1275 certificate in your browser, given at
1276 @uref{http://savannah.gnu.org/tls/tutorial/}.
1280 After registering, if you are not logged in automatically, login
1281 at @uref{https://savannah.gnu.org/account/login.php}---this should
1282 take you to your @qq{my} page
1283 (@uref{https://savannah.gnu.org/my/}).
1287 Click on the @qq{My Groups} link to access the @qq{My Group
1288 Membership} page. From there, find the @qq{Request for Inclusion}
1289 box and search for @qq{LilyPond}. Among the search results, check
1290 the box labeled @qq{GNU LilyPond Music Typesetter} and write a
1291 brief (required) message for the Project Manager (@qq{Hey it's
1292 me!} should be fine).
1294 Note that you will not have commit access until the Project
1295 Manager activates your membership. Once your membership is
1296 activated, LilyPond should appear under the heading @qq{Groups I'm
1297 Contributor of} on your @qq{My Group Membership} page.
1301 Generate an SSH @q{dsa} key pair. Enter the following at the
1308 When prompted for a location to save the key, press <ENTER> to
1309 accept the default location (@file{~/.ssh/id_dsa}).
1311 Next you are asked to enter an optional passphrase. On most
1312 systems, if you use a passphrase, you will likely be prompted for
1313 it every time you use @command{git@tie{}push} or
1314 @command{git@tie{}pull}. You may prefer this since it can protect
1315 you from your own mistakes (like pushing when you mean to pull),
1316 though you may find it tedious to keep re-entering it.
1318 You can change/enable/disable your passphrase at any time with:
1321 ssh-keygen -f ~/.ssh/id_dsa -p
1324 Note that the GNOME desktop has a feature which stores your
1325 passphrase for you for an entire GNOME session. If you use a
1326 passphrase to @qq{protect you from yourself}, you will want to
1327 disable this feature, since you'll only be prompted once. Run the
1328 following command, then logout of GNOME and log back in:
1331 gconftool-2 --set -t bool \
1332 /apps/gnome-keyring/daemon-components/ssh false
1335 After setting up your passphrase, your private key is saved as
1336 @file{~/.ssh/id_dsa} and your public key is saved as
1337 @file{~/.ssh/id_dsa.pub}.
1341 Register your public SSH @q{dsa} key with Savannah. From the
1342 @qq{My Account Configuration} page, click on @qq{Edit SSH Keys},
1343 then paste the contents of your @file{~/.ssh/id_dsa.pub} file into
1344 one of the @qq{Authorized keys} text fields, and click
1347 Savannah should respond with something like:
1350 Success: Key #1 seen Keys registered
1355 Configure Git to use the SSH protocol (instead of the GIT
1356 protocol). From your local Git repository, enter:
1359 git config remote.origin.url \
1360 ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1364 where @var{user} is your username on Savannah.
1368 After your membership has been activated and you've configured Git
1369 to use SSH, test the connection with:
1375 SSH should issue the following warning:
1378 The authenticity of host 'git.sv.gnu.org (140.186.70.72)' can't
1380 RSA key fingerprint is
1381 80:5a:b0:0c:ec:93:66:29:49:7e:04:2b:fd:ba:2c:d5.
1382 Are you sure you want to continue connecting (yes/no)?
1385 Make sure the RSA key fingerprint displayed matches the one above.
1386 If it doesn't, respond @qq{no} and check that you configured Git
1387 properly in the previous step. If it does match, respond
1388 @qq{yes}. SSH should then issue another warning:
1391 Warning: Permanently added 'git.sv.gnu.org,140.186.70.72' (RSA) to
1392 the list of known hosts.
1395 The list of known hosts is stored in the file
1396 @file{~/.ssh/known_hosts}.
1398 At this point, you are prompted for your passphrase if you have
1399 one, then Git will attempt a pull.
1401 If @command{git@tie{}pull@tie{}--verbose} fails, you should see
1402 error messages like these:
1405 Permission denied (publickey).
1406 fatal: The remote end hung up unexpectedly
1409 If you get the above error, you may have made a mistake when
1410 registering your SSH key at Savannah. If the key is properly
1411 registered, you probably just need to wait for the Savannah server
1412 to activate it. It usually takes a few minutes for the key to be
1413 active after registering it, but if it still doesn't work after an
1414 hour, ask for help on the mailing list.
1416 If @command{git@tie{}pull@tie{}--verbose} succeeds, the output
1417 will include a @q{From} line that shows @q{ssh} as the protocol:
1420 From ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond
1423 If the protocol shown is not @q{ssh}, check that you configured
1424 Git properly in the previous step.
1428 Test your commit access with a dry run:
1431 git push --dry-run --verbose
1434 Note that recent versions of Git (Git 1.6.3 or later) will issue a
1435 big warning if the above command is used. The simplest solution
1436 is to tell Git to push all matching branches by default:
1439 git config push.default matching
1443 Then @code{git@tie{}push} should work as before. For more
1444 details, consult the @code{git@tie{}push} man page.
1448 @subsubheading Technical details
1452 On Firefox, to view or remove the CAcert root certificate, go to:
1453 Edit > Preferences > Advanced > Encryption > View Certificates >
1454 Authorities > Certificate Name > Root CA > CA Cert Signing
1458 The @command{git@tie{}config} commands above should modify your
1459 local repository's @file{.git/config} file. These lines:
1463 url = git://git.sv.gnu.org/lilypond.git/
1467 should now be changed to:
1471 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1475 where @var{user} is your login name on Savannah.
1479 @command{git@tie{}config@tie{}push.default@tie{}matching} command
1480 should add these lines to @file{.git/config}:
1489 Encryption protocols, including ssh, generally do not permit packet
1490 fragmentation to avoid introducing a point of insecurity. This
1491 means that the maximum packet size must not exceed the smallest
1492 MTU (Maximum Transmission Unit) set in the routers along the path.
1493 This smallest MTU is determined by a procedure during call set-up
1494 which relies on the transmission over the path of ICMP packets.
1495 If any of the routers in the path block ICMP packets this mechanism
1496 fails, resulting in the possibility of packets being transmitted
1497 which exceed the MTU of one of the routers. If this happens the
1498 packet is discarded, causing the ssh session to hang, timeout or
1499 terminate with the error message
1502 ssh: connect to host <host ip addr> port 22: Bad file number
1503 fatal: The remote end hung up unexpectedly
1506 depending on precisely when in the proceedings the first large
1507 packet is transmitted. Most routers on the internet have MTU
1508 set to 1500, but routers installed in homes to connect via
1509 broadband may use a slightly smaller MTU for efficient transmission
1510 over ATM. If this problem is encountered a possible work-around is
1511 to set the MTU in the local router to 1500.
1513 @node Git on Windows
1514 @section Git on Windows
1516 @c Some of this may duplicate stuff in other sections
1517 @c But it is probably best for windows users to have it all together
1518 @c If necessary, clear this up later -td
1520 TODO: Decide what to do with this... Pare it down? Move
1521 paragraphs next to analogous Unix instructions? -mp
1523 @subsection Background to nomenclature
1525 Git is a system for tracking the changes made to source files by a
1526 distributed set of editors. It is designed to work without a
1527 master repository, but we have chosen to have a master repository
1528 for LilyPond files. Editors hold a local copy of the master
1529 repository together with any changes they have made locally.
1530 Local changes are held in a local @q{branch}, of which there may
1531 be several, but these instructions assume you are using just one.
1532 The files visible in the local repository always correspond to
1533 those on the currently @q{checked out} local branch.
1535 Files are edited on a local branch, and in that state the changes
1536 are said to be @q{unstaged}. When editing is complete, the
1537 changes are moved to being @q{staged for commit}, and finally the
1538 changes are @q{committed} to the local branch. Once committed,
1539 the changes (called a @q{commit}) are given a unique 40-digit
1540 hexadecimal reference number called the @q{Committish} or @q{SHA1
1541 ID} which identifies the commit to Git. Such committed changes
1542 can be sent to the master repository by @q{pushing} them (if you
1543 have write permission) or by sending them by email to someone who
1544 has, either as a complete file or as a @q{diff} or @q{patch}
1545 (which send just the differences from the master repository).
1547 @subsection Installing git
1550 @uref{http://code.google.com/p/msysgit/downloads/list} (note, not
1551 msysGit, which is for Git developers and not PortableGit, which is
1552 not a full git installation) and install it.
1554 Note that most users will not need to install SSH. That is not
1555 required until you have been granted direct push permissions to
1556 the master git repository.
1558 Start Git by clicking on the desktop icon. This will bring up a
1559 command line bash shell. This may be unfamiliar to Windows users.
1560 If so, follow these instructions carefully. Commands are entered
1561 at a $ prompt and are terminated by keying a newline.
1563 @subsection Initialising Git
1565 Decide where you wish to place your local Git repository, creating
1566 the folders in Windows as necessary. Here we call the folder to
1567 contain the repository @code{[path]/Git}, but if you intend using
1568 Git for other projects a directory name like @code{lilypond-git}
1569 might be better. You will need to have space for around
1572 Start the Git bash shell by clicking on the desk-top icon
1573 installed with Git and type
1579 to position the shell at your new Git repository.
1581 Note: if [path] contains folders with names containing spaces use
1593 to initialize your Git repository.
1595 Then type (all on one line; the shell will wrap automatically)
1598 git remote add -ft master origin git://git.sv.gnu.org/lilypond.git
1601 to download the lilypond master files.
1603 @warning{Be patient! Even on a broadband connection this can take
1604 10 minutes or more. Wait for lots of [new tag] messages and the $
1607 We now need to generate a local copy of the downloaded files in a
1608 new local branch. Your local branch needs to have a name. It is
1609 usual to call it @q{master} and we shall do that here.
1614 git checkout -b master origin/master
1617 This creates a second branch called @q{master}. You will see two
1618 warnings (ignore these), and a message advising you that your
1619 local branch @q{master} has been set up to track the remote
1620 branch. You now have two branches, a local branch called
1621 @q{master}, and a tracking branch called @q{origin/master}, which
1622 is a shortened form of @q{remotes/origin/master}.
1624 Return to Windows Explorer and look in your Git repository. You
1625 should see lots of folders. For example, the LilyPond
1626 documentation can be found in [path]/Git/Documentation/.
1628 The Git bash shell is terminated by typing @code{exit} or by
1629 clicking on the usual Windows close-window widget.
1633 Almost all subsequent work will use the Git Graphical User
1634 Interface, which avoids having to type command line commands. To
1635 start Git GUI first start the Git bash shell by clicking on the
1636 desktop icon, and type
1643 The Git GUI will open in a new window. It contains four panels
1644 and 7 pull-down menus. At this stage do not use any of the
1645 commands under Branch, Commit, Merge or Remote. These will be
1648 The top panel on the left contains the names of files which you
1649 are in the process of editing (Unstaged Changes), and the lower
1650 panel on the left contains the names of files you have finished
1651 editing and have staged ready for committing (Staged Changes). At
1652 present, these panels will be empty as you have not yet made any
1653 changes to any file. After a file has been edited and saved the
1654 top panel on the right will display the differences between the
1655 edited file selected in one of the panels on the left and the last
1656 version committed on the current branch.
1658 The panel at bottom right is used to enter a descriptive message
1659 about the change before committing it.
1661 The Git GUI is terminated by entering CNTL-Q while it is the
1662 active window or by clicking on the usual Windows close-window
1665 @subsection Personalising your local git repository
1667 Open the Git GUI, click on
1673 and enter your name and email address in the left-hand (Git
1674 Repository) panel. Leave everything else unchanged and save it.
1676 Note that Windows users must leave the default setting for line
1677 endings unchanged. All files in a git repository must have lines
1678 terminated by just a LF, as this is required for Merge to work,
1679 but Windows files are terminated by CRLF by default. The git
1680 default setting causes the line endings of files in a Windows git
1681 repository to be flipped automatically between LF and CRLF as
1682 required. This enables files to be edited by any Windows editor
1683 without causing problems in the git repository.
1685 @subsection Checking out a branch
1687 At this stage you have two branches in your local repository,
1688 both identical. To see them click on
1694 You should have one local branch called @q{master} and one
1695 tracking branch called @q{origin/master}. The latter is your
1696 local copy of the @q{remotes/origin/master} branch in the master
1697 LilyPond repository. The local @q{master} branch is where you
1698 will make your local changes.
1700 When a particular branch is selected, i.e., checked out, the files
1701 visible in your repository are changed to reflect the state of the
1702 files on that branch.
1704 @subsection Updating files from @q{remote/origin/master}
1706 Before starting the editing of a file, ensure your local
1707 repository contains the latest version of the files in the remote
1708 repository by first clicking
1711 Remote -> Fetch from -> origin
1717 This will place the latest version of every file, including all
1718 the changes made by others, into the @q{origin/master} branch of
1719 the tracking branches in your git repository. You can see these
1720 files by checking out this branch, but you must @emph{never} edit
1721 any files while this branch is checked out. Check out your local
1722 @q{master} branch again.
1724 You then need to merge these fetched files into your local
1725 @q{master} branch by clicking on
1728 Merge -> Local Merge
1732 and if necessary select the local @q{master} branch.
1734 Note that a merge cannot be completed if you have made any local
1735 changes which have not yet been committed.
1737 This merge will update all the files in the @q{master} branch to
1738 reflect the current state of the @q{origin/master} branch. If any
1739 of the changes conflict with changes you have made yourself
1740 recently you will be notified of the conflict (see below).
1742 @subsection Editing files
1744 First ensure your @q{master} branch is checked out, then simply
1745 edit the files in your local Git repository with your favourite
1746 editor and save them back there. If any file contains non-ASCII
1747 characters ensure you save it in UTF-8 format. Git will detect
1748 any changes whenever you restart Git GUI and the file names will
1749 then be listed in the Unstaged Changes panel. Or you can click
1750 the Rescan button to refresh the panel contents at any time. You
1751 may break off and resume editing any time.
1753 The changes you have made may be displayed in diff form in the top
1754 right-hand panel of Git GUI by clicking on the file name shown in
1755 one of the left panels.
1757 When your editing is complete, move the files from being Unstaged
1758 to Staged by clicking the document symbol to the left of each
1759 name. If you change your mind it can be moved back by clicking on
1760 the ticked box to the left of the name.
1762 Finally the changes you have made may be committed to your
1763 @q{master} branch by entering a brief message in the Commit
1764 Message box and clicking the Commit button.
1766 If you wish to amend your changes after a commit has been made,
1767 the original version and the changes you made in that commit may
1768 be recovered by selecting
1771 Commit -> Amend Last Commit
1775 or by checking the Amend Last Commit radio button at bottom right.
1776 This will return the changes to the Staged state, so further
1777 editing made be carried out within that commit. This must only be
1778 done @emph{before} the changes have been Pushed or sent to your
1779 mentor for Pushing - after that it is too late and corrections
1780 have to be made as a separate commit.
1783 @subsection Sending changes to @q{remotes/origin/master}
1785 If you do not have write access to @q{remotes/origin/master} you
1786 will need to send your changes by email to someone who does.
1788 First you need to create a diff or patch file containing your
1789 changes. To create this, the file must first be committed. Then
1790 terminate the Git GUI. In the git bash shell first cd to your Git
1797 if necessary, then produce the patch with
1800 git format-patch origin
1803 This will create a patch file for all the locally committed files
1804 which differ from @q{origin/master}. The patch file can be found
1805 in [path]/Git and will have a name formed from the commit message.
1807 @subsection Resolving merge conflicts
1809 As soon as you have committed a changed file your local
1810 @code{master} branch has diverged from @code{origin/master}, and
1811 will remain diverged until your changes have been committed in
1812 @code{remotes/origin/master} and Fetched back into your
1813 @code{origin/master} branch. Similarly, if a new commit has been
1814 made to @code{remotes/origin/master} by someone else and Fetched,
1815 your local @code{master} branch is divergent. You can detect a
1816 divergent branch by clicking on
1819 Repository -> Visualise all branch history
1822 This opens up a very useful new window called @q{gitk}. Use this
1823 to browse all the commits made by yourself and others.
1825 If the diagram at top left of the resulting window does not show
1826 your @code{master} tag on the same node as the
1827 @code{remotes/origin/master} tag your branch has diverged from
1828 @code{origin/master}. This is quite normal if files you have
1829 modified yourself have not yet been Pushed to
1830 @code{remotes/origin/master} and Fetched, or if files modified and
1831 committed by others have been Fetched since you last Merged
1832 @code{origin/master} into your local @code{master} branch.
1834 If a file being merged from @code{origin/master} differs from one
1835 you have modified in a way that cannot be resolved automatically
1836 by git, Merge will report a Conflict which you must resolve by
1837 editing the file to create the version you wish to keep.
1839 This could happen if the person updating
1840 @code{remotes/origin/master} for you has added some changes of his
1841 own before committing your changes to
1842 @code{remotes/origin/master}, or if someone else has changed the
1843 same file since you last fetched the file from
1844 @code{remotes/origin/master}.
1846 Open the file in your editor and look for sections which are
1849 [to be completed when I next have a merge conflict to be sure I
1850 give the right instructions -td]
1853 @subsection Other actions
1855 The instructions above describe the simplest way of using git on
1856 Windows. Other git facilities which may usefully supplement these
1860 @item Using multiple local branches (Create, Rename, Delete)
1861 @item Resetting branches
1862 @item Cherry-picking commits
1863 @item Pushing commits to @w{remote/origin/master}
1864 @item Using gitk to review history
1867 Once familiarity with using git on Windows has been gained the
1868 standard git manuals can be used to learn about these.
1871 @node Repository directory structure
1872 @section Repository directory structure
1875 @c TODO: integrate the roadmap better
1876 @verbatiminclude ROADMAP
1879 @node Other Git documentation
1880 @section Other Git documentation
1884 Official git man pages:
1885 @uref{http://www.kernel.org/pub/software/scm/git/docs/}
1888 More in-depth tutorials: @uref{http://git-scm.com/documentation}
1891 Book about git: @uref{http://progit.org/,Pro Git}