1 @c -*- coding: us-ascii; mode: texinfo; -*-
2 @node Starting with git
3 @chapter Starting with git
5 The goal of this chapter is to provide all the git commands that
6 contributors should know for basic lilypond development. However,
7 to complete or present in another form the introduction to Git
8 usage in this chapter, it may be a good idea to look at the other
9 Git documentation listed in @ref{Other git documentation}.
12 * Getting the source code::
13 * Updating the source code::
14 * Sharing your changes::
15 * Advanced git stuff::
17 * Other git documentation::
18 * Roadmap of directories::
22 @node Getting the source code
23 @section Getting the source code
27 * Git user configuration::
29 * Documentation translations source code::
31 * Other locations for git::
34 @node Git introduction
35 @subsection Git introduction
37 The source code is kept in a Git respository. This allows us to
38 track changes to files, and for multiple people to work on the
39 same set of files efficiently.
41 After downloading the source code, it is important to update the
42 repository by @ref{Updating the source code}.
44 @warning{These instructions assume that you are using the
45 command-line version of Git 1.5 or higher. Windows users should
46 skip to @ref{Git on Windows}.}
49 @node Git user configuration
50 @subsection Git user configuration
52 Some useful cofiguration can be performed automatically; cut and
53 paste the following section:
56 git config --global color.ui auto
59 To configure git to automatically use your name and email address
60 for commits and patches, edit the below lines by changing all the
64 git config --global user.name "MYNAME"
65 git config --global user.email MYEMAIL@@EXAMPLE.NET
69 @node Main source code
70 @subsection Main source code
72 To get the main source code and documentation,
74 @c WARNING: when updating the commands below, please
75 @c update the other flavors in the two next nodes
76 @c and in Introduction to Git concepts
78 mkdir lilypond; cd lilypond
80 git remote add -f -t master -m master origin git://git.sv.gnu.org/lilypond.git/
81 git checkout -b master origin/master
85 @node Documentation translations source code
86 @subsection Documentation translations source code
88 To translate the documentation,
91 mkdir lilypond-translation; cd lilypond-translation
93 git remote add -f -t lilypond/translation -m lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
94 git checkout -b lilypond/translation origin/lilypond/translation
99 @subsection Other branches
101 Most contributors will never need to touch the other branches. If
102 you wish to do so, you will need more familiarity with git; please
103 see @ref{Other git documentation}.
107 @item @code{dev/XYZ}:
108 These branches are for individual developers. They store code
109 which is not yet stable enough to be added to the @code{master}
112 @item @code{stable/XYZ}:
113 The branches are kept for archival reasons.
117 Another item of interest might be the Grand Unified Builder, our
118 cross-platform building tool. Since it is used by projects as
119 well, it is not stored in our gub repository. For more info, see
120 @uref{http://lilypond.org/gub}. The git location is:
123 http://github.com/janneke/gub
127 @node Other locations for git
128 @subsection Other locations for git
130 If you have difficulty connecting to most of the repositories
131 listed in earlier sections, try:
134 http://git.sv.gnu.org/r/lilypond.git
135 git://git.sv.gnu.org/lilypond.git
136 ssh://git.sv.gnu.org/srv/git/lilypond.git
139 Using HTTP protocol is slowest, so it is not recommended unless both
140 SSH and Git protocols fail, which happens e.g. if you connect to
141 internet through a router that filters out Git and/or SSH connections.
145 @node Updating the source code
146 @section Updating the source code
149 * Importance of updating::
151 * Resolving conflicts::
155 @node Importance of updating
156 @subsection Importance of updating
158 In a large project like LilyPond, contributors sometimes edit the same
159 file at the same time. As long as everybody updates their version of
160 the file with the most recent changes (@emph{pulling}), there are
161 generally no problems with this multiple-person editing. However,
162 big problems can arise if you do not pull before attempting to
163 commit. If this occurs, see @ref{Resolving conflicts}.
167 @subsection Updating command
169 Whenever you are asked to pull, it means you should update your
170 local copy of the repository with the changes made by others on
171 the remote @code{git.sv.gnu.org} repository:
178 The @code{-r} option is short for @code{--rebase}. If you don't
179 edit translated documentation and don't want to type @code{-r}
180 every time, add @code{rebase = true} to the master branch in your
181 @file{.git/config}, like so:
186 merge = refs/heads/master
190 @warning{translators and documentation editors, if you have
191 changed committishes in the head of translated files using commits
192 you have not yet pushed to @code{git.sv.gnu.org}, please do not
193 rebase. If you want to avoid wondering whether you should rebase
194 each time you pull, please always use committishes from master
195 and/or lilypond/translation branch on @code{git.sv.gnu.org}, which
196 in particular implies that you must push your changes to
197 documentation except committishes updates (possibly after having
198 rebased), then update the committishes and push them.}
200 @c FIXME: when committishes automatic conditional update have been
201 @c tested and documented, append the following to the warning above:
202 @c Note that using update-committishes make target generally touches
206 @node Resolving conflicts
207 @subsection Resolving conflicts
209 Occasionally an update may result in conflicts -- this happens
210 when you and somebody else have modified the same part of the same
211 file and git cannot figure out how to merge the two versions
212 together. When this happens, you must manually merge the two
215 If you need some documentation to understand and resolve conflicts,
216 see paragraphs @emph{How conflicts are presented} and @emph{How to
217 resolve conflicts} in @command{git merge} man page.
219 If all else fails, you can follow the instructions in
220 @ref{Reverting all local changes}. Be aware that this eliminates
221 any changes you have made!
224 @node Sharing your changes
225 @section Sharing your changes
228 * Producing a patch::
229 * Committing directly::
233 @node Producing a patch
234 @subsection Producing a patch
236 Once you have finished editing your files, checked that your changes
237 meet the @ref{Code style}, and/or @ref{Documentation policy}, properly
238 set up your name and email in @ref{Git user configuration}, and
239 checked that the entire thing compiles, you may:
243 git format-patch origin
246 The commit should include a brief message describing the change.
247 This consists of a one-line summary describing the change, and
248 if necessary a blank line followed by several lines giving the
252 Did household chores.
254 I hung up the wet laundry and then washed the car. I also
255 vacuumed the floors, rinsed the dirty dishes, fed the cat, and
256 recalibrated the temporal flux machine.
259 If the change is to the documentation only then the one-line
260 summary should be prefixed with @qq{Docs: }.
262 If you added a file to the source code, you must add it to git
266 git add @var{FILENAME}
270 (and possibly modify the @file{GNUmakefile})
272 These commands will produce one or more files named @file{0001-xyz},
273 @file{0002-abc}, etc. in the top directory of the git tree. Send an
274 email to @email{lilypond-devel@@gnu.org} with these files attached, and
275 a developer will review and apply the patches to the main repository.
276 If your patch is some translation work, you may send it to
277 @email{translations@@lilynet.net} instead.
279 To check if you have correctly added any new files, use:
286 If this command lists any @emph{Changed but not updated} files,
287 you should do a @command{git commit}. If it lists any
288 @emph{Untracked files}, then you should do a @command{git add}.
291 @node Committing directly
292 @subsection Committing directly
294 Most contributors do not have permission to commit directly. If you do,
295 make sure you have set up your name and email in @ref{Git user
296 configuration}, then edit @file{.git/config}: change the line
299 url = git://git.sv.gnu.org/lilypond.git/
306 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
310 where @var{user} is your login name on Savannah.
312 If you have not already done so, you should generate and upload a
313 SSH key: open @uref{https://savannah.gnu.org/my/} in your browser,
314 go to @q{Account Configuration}, then to something like
315 @q{Edit SSH Keys}, and follow the instructions on that page.
323 Note that recent versions of Git (Git 1.6.3 or later) will issue a
324 big warning if the above command is used. The simplest solution
325 is to add a new section to @file{.git/config} that looks like
334 Then @code{git push origin} will work as before. For more
335 details, consult the @code{git push} man page.
338 @node Advanced git stuff
339 @section Advanced git stuff
341 @warning{This section is not necessary for normal contributors;
342 these commands are presented for information for people interested
343 in learning more about git.}
346 It is possible to work with several branches on the same local Git
347 repository; this is especially useful for translators who may have to
348 deal with both @code{lilypond/translation} and a stable branch,
349 e.g. @code{stable/2.12}.
351 Some Git commands are introduced first, then a workflow with several
352 Git branches of LilyPond source code is presented.
355 * Introduction to Git concepts::
356 * Git commands for managing several branches::
357 * Working on LilyPond sources with several branches::
359 * Applying git patches::
360 * Reverting all local changes::
364 @node Introduction to Git concepts
365 @subsection Introduction to Git concepts
367 A bit of Git vocabulary will be explained below. The following is
368 just introduction material; for better understanding of Git concepts,
369 you are invited to read further documentation, especially Git
370 Community Book at @uref{http://book.git-scm.com/}.
372 The @code{git pull origin} command above is just a shortcut for this
376 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
380 where @code{@var{branch}} is typically @code{master}, @code{web} or
381 @code{lilypond/translation}; if you do not know or remember, see
382 @ref{Getting the source code} to remember which commands you issued or
383 which source code you wanted to get.
385 A @emph{commit} is a set of changes made to the sources; it also
386 includes the committish of the parent commit, the name and e-mail of
387 the @emph{author} (the person who wrote the changes), the name and
388 e-mail of the @emph{committer} (the person who brings these changes
389 into the Git repository), and a commit message.
391 A @emph{committish} is the SHA1 checksum of a commit, a number made of
392 40 hexadecimal digits, which acts as the internal unique identifier
393 for this commit. To refer to a particular revision, don't use vague
394 references like the (approximative) date, simply copy and paste the
397 A @emph{branch} is nothing more than a pointer to a particular commit,
398 which is called the @emph{head} of the branch; when referring to a
399 branch, one often acutally thinks about its head and the ancestor
402 Now we will explain the two last commands you used to get the source
403 code from Git -- see @ref{Getting the source code}.
406 git remote add -f -t @var{branch} -m @var{branch} origin git://git.sv.gnu.org/lilypond.git/
407 git checkout -b @var{branch} origin/@var{branch}
410 The @command{git remote} has created a branch called
411 @code{origin/@var{branch}} in your local Git repository. As this
412 branch is a copy of the remote branch web from git.sv.gnu.org LilyPond
413 repository, it is called a @emph{remote branch}, and is meant to track
414 the changes on the branch from git.sv.gnu.org: it will be updated
415 every time you run @command{git pull origin} or @command{git fetch
418 The @command{git checkout} command has created a branch named
419 @code{@var{branch}}. At the beginning, this branch is identical to
420 @code{origin/@var{branch}}, but it will differ as soon as you make
421 changes, e.g. adding newly translated pages or editing some
422 documentation or code source file. Whenever you pull, you merge the
423 changes from @code{origin/@var{branch}} and @code{@var{branch}} since
424 the last pulling. If you do not have push (i.e. @qq{write}) access on
425 git.sv.gnu.org, your @code{@var{branch}} will always differ from
426 @code{origin/@var{branch}}. In this case, remember that other people
427 working like you with the remote branch @code{@var{branch}} of
428 git://git.sv.gnu.org/lilypond.git/ (called @code{origin/@var{branch}}
429 on your local repository) know nothing about your own
430 @code{@var{branch}}: this means that whenever you use a committish or
431 make a patch, others expect you to take the latest commit of
432 @code{origin/@var{branch}} as a reference.
434 Finally, please remember to read the man page of every Git command you
435 will find in this manual in case you want to discover alternate
436 methods or just understand how it works.
439 @node Git commands for managing several branches
440 @subsection Git commands for managing several branches
442 @subsubheading Listing branches and remotes
444 You can get the exact path or URL of all remotes with
451 To list Git branches on your local repositories, run
454 git branch # list local branches only
455 git branch -r # list remote branches
456 git branch -a # list all branches
460 @subsubheading Checking out branches
462 To know the currently checked out branch, i.e. the branch whose source
463 files are present in your working tree, read the first line of the
471 The currently checked out branch is also marked with an asterisk in
472 the output of @command{git branch}.
474 You can check out another branch @code{@var{other_branch}}, i.e. check
475 out @code{@var{other_branch}} to the working tree, by running
478 git checkout @var{other_branch}
481 Note that it is possible to check out another branch while having
482 uncommitted changes, but it is not recommended unless you know what
483 you are doing; it is recommended to run @command{git status} to check
484 this kind of issue before checking out another branch.
487 @subsubheading Merging branches
489 To merge branch @code{@var{foo}} into branch @code{@var{bar}}, i.e. to
490 @qq{add} all changes made in branch @code{@var{foo}} to branch
491 @code{@var{bar}}, run
494 git checkout @var{bar}
498 If any conflict happens, see @ref{Resolving conflicts}.
500 There are common usage cases for merging: as a translator, you will
501 often want to merge @code{master} into @code{lilypond/translation}; on
502 the other hand, the Translations meister wants to merge
503 @code{lilypond/translation} into @code{master} whenever he has checked
504 that @code{lilypond/translation} builds successfully.
507 @node Working on LilyPond sources with several branches
508 @subsection Working on LilyPond sources with several branches
510 @subsubheading Fetching new branches from git.sv.gnu.org
512 To fetch and check out a new branch named @code{@var{branch}} on
513 git.sv.gnu.org, run from top of the Git repository
516 git config --add remote.origin.fetch +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
517 git checkout --track -b @var{branch} origin/@var{branch}
520 After this, you can pull @code{@var{branch}} from git.sv.gnu.org with
526 Note that this command generally fetches all branches you added with
527 @command{git remote add} (when you initialized the repository) or
528 @command{git config --add}, i.e. it updates all remote branches from
529 remote @code{origin}, then it merges the remote branch tracked by
530 current branch into current branch. For example, if your current
531 branch is @code{master} --- which is the case if you got the sources
532 with the commands described in @ref{Main source code} and did not
533 issue any @command{git checkout} command --- @code{origin/master} will
534 be merged into @code{master}.
537 @subsubheading Local clones, or having several working trees
539 If you play with several Git branches, e.g. @code{master},
540 @code{lilypond/translation}, @code{stable/2.12}), you may want to have
541 one source and build tree for each branch; this is possible with
542 subdirectories of your local Git repository, used as local cloned
543 subrepositories. To create a local clone for the branch named
544 @code{@var{branch}}, run
547 git checkout @var{branch}
548 git clone -l -s -n . @var{subdir}
553 Note that @code{@var{subdir}} must be a directory name which does not
554 already exist. In @code{@var{subdir}}, you can use all Git commands
555 to browse revisions history, commit and uncommit changes; to update
556 the cloned subrepository with changes made on the main repository, cd
557 into @code{@var{subdir}} and run @command{git pull}; to send changes
558 made on the subrepository back to the main repository, run
559 @command{git push} from @code{@var{subdir}}. Note that only one
560 branch (the currently checked out branch) is created in the
561 subrepository by default; it is possible to have several branches in a
562 subrepository and do usual operations (checkout, merge, create,
563 delete...) on these branches, but this possibility is not detailed
566 When you push @code{@var{branch}} from @code{@var{subdir}} to the main
567 repository, and @code{@var{branch}} is checked out in the main
568 repository, you must save uncommitted changes (see @command{git
569 stash}) and do @command{git reset --hard} in the main repository in
570 order to apply pushed changes in the working tree of the main
577 The commands above don't only bring you the latest version of the
578 sources, but also the full history of revisions (revisons, also
579 called commits, are changes made to the sources), stored in the
580 .git directory. You can browse this history with
583 git log # only shows the logs (author, committish and commit message)
584 git log -p # also shows diffs
585 gitk # shows history graphically
588 @warning{The @code{gitk} command may require a separate @code{gitk} package,
589 available in the appropriate distribution's repositories.}
592 @node Applying git patches
593 @subsection Applying git patches
595 Well-formed git patches created with @code{git format-patch}
596 should be committed with the following command:
602 Patches created without @code{git format-patch} can be applied in
603 two steps. The first step is to apply the patch to the working
607 git apply @var{patch}
611 The second step is to commit the changes and give credit to the
612 author of the patch. This can be done with the following command:
615 git commit -a --author="First Last <user@@example.net>"
619 @node Reverting all local changes
620 @subsection Reverting all local changes
622 Sometimes git will become hopelessly confused, and you just want
623 to get back to a known, stable state. This command destroys any
624 local changes you have made, but at least you get back to the
625 current online version:
628 git reset --hard origin/master
633 @section Git on Windows
635 @c Some of this may duplicate stuff in other sections
636 @c But it is probably best for windows users to have it all together
637 @c If necessary, clear this up later -td
639 @subsection Background to nomenclature
641 Git is a system for tracking the changes made to source files by
642 a distributed set of editors. It is designed to work without a
643 master repository, but we have chosen to have a master respository
644 for LilyPond files. Editors hold a local copy of the master
645 repository together with any changes they have made locally. Local
646 changes are held in a local @q{branch}, of which there may be
647 several, but these instructions assume you are using just one. The
648 files visible in the local repository always correspond to those
649 on the currently @q{checked out} local branch.
651 Files are edited on a local branch, and in that state the
652 changes are said to be @q{unstaged}. When editing is complete, the
653 changes are moved to being @q{staged for commit}, and finally the
654 changes are @q{committed} to the local branch. Once committed, the
655 changes (called a @q{commit}) are given a unique 40-digit hexadecimal
656 reference number called the @q{Committish} or @q{SHA1 ID} which
657 identifies the commit to Git. Such committed changes can be sent to
658 the master repository by @q{pushing} them (if you have write
659 permission) or by sending them by email to someone who has, either
660 as a complete file or as a @q{diff} or @q{patch} (which send just
661 the differences from the master repository).
663 @subsection Installing git
666 @uref{http://code.google.com/p/msysgit/downloads/list}
667 (note, not msysGit, which is for Git developers and not PortableGit,
668 which is not a full git installation) and
671 Note that most users will not need to install SSH. That is not
672 required until you have been granted direct push permissions to
673 the master git repository.
675 Start Git by clicking on the desktop icon.
676 This will bring up a command line bash shell. This may be
677 unfamiliar to Windows users. If so, follow these
678 instructions carefully. Commands are entered at a $ prompt
679 and are terminated by keying a newline.
681 @subsection Initialising Git
683 Decide where you wish to place your local Git repository,
684 creating the folders in Windows as necessary. Here we
685 call the folder to contain the repository @code{[path]/Git}, but
686 if you intend using Git for other projects a directory name like
687 @code{lilypond-git} might be better. You will need to have space
688 for around 100Mbytes.
690 Start the Git bash shell by clicking on the desk-top icon installed
697 to position the shell at your new Git repository.
699 Note: if [path] contains folders with names containing
712 to initialize your Git repository.
714 Then type (all on one line; the shell will wrap automatically)
717 git remote add -f -t master origin git://git.sv.gnu.org/lilypond.git
720 to download the lilypond master files.
722 @warning{Be patient! Even on a broadband connection this can take
723 10 minutes or more. Wait for lots of [new tag] messages
726 We now need to generate a local copy of the downloaded files
727 in a new local branch. Your local branch needs to have a
728 name. It is usual to call it @q{master} and we shall do that
734 git checkout -b master origin/master
737 This creates a second branch called @q{master}. You will see
738 two warnings (ignore these), and a message advising you that
739 your local branch @q{master} has been set up to track the remote
740 branch. You now have two branches, a local branch called
741 @q{master}, and a tracking branch called @q{origin/master},
742 which is a shortened form of @q{remotes/origin/master}.
744 Return to Windows Explorer and look in your Git repository. You
745 should see lots of folders. For example, the LilyPond documentation
746 can be found in [path]/Git/Documentation/.
748 The Git bash shell is terminated by typing @code{exit} or by
749 clicking on the usual Windows close-window widget.
753 Almost all subsequent work will use the Git Graphical User
754 Interface, which avoids having to type command line
755 commands. To start Git GUI first start the Git bash shell by
756 clicking on the desktop icon, and type
763 The Git GUI will open in a new window. It contains four panels
764 and 7 pull-down menus. At this stage do not use any of the
765 commands under Branch, Commit, Merge or Remote. These will
768 The top panel on the left contains the names of files which
769 you are in the process of editing (Unstaged Changes), and the
770 lower panel on the left contains the names of
771 files you have finished editing and have staged ready for
772 committing (Staged Changes). At present, these panels will
773 be empty as you have not yet made any changes to any file.
774 After a file has been edited and saved the top panel on the right
775 will display the differences between the edited file selected
776 in one of the panels on the left and the last version committed
777 on the current branch.
779 The panel at bottom right is used to enter a descriptive
780 message about the change before committing it.
782 The Git GUI is terminated by entering CNTL-Q while it is the
783 active window or by clicking on the usual Windows close-window
786 @subsection Personalising your local git repository
788 Open the Git GUI, click on
794 and enter your name and email address in the
795 left-hand (Git Repository) panel. Leave everything
796 else unchanged and save it.
798 Note that Windows users must leave the default setting for line
799 endings unchanged. All files in a git repository must have lines
800 terminated by just a LF, as this is required for Merge to work, but
801 Windows files are terminated by CRLF by default. The git default
802 setting causes the line endings of files in a Windows git repository
803 to be flipped automatically between LF and CRLF as required. This
804 enables files to be edited by any Windows editor without causing
805 problems in the git repository.
807 @subsection Checking out a branch
809 At this stage you have two branches in your local repository,
810 both identical. To see them click on
816 You should have one local branch called @q{master} and one
817 tracking branch called @q{origin/master}. The latter is your
818 local copy of the @q{remotes/origin/master} branch in the master
819 LilyPond repository. The local @q{master} branch is where you
820 will make your local changes.
822 When a particular branch is selected, i.e., checked out, the
823 files visible in your repository are changed to reflect the
824 state of the files on that branch.
826 @subsection Updating files from @q{remote/origin/master}
828 Before starting the editing of a file, ensure your local repository
829 contains the latest version of the files in the remote repository
833 Remote -> Fetch from -> origin
839 This will place the latest version of every file, including all the
840 changes made by others, into the @q{origin/master} branch of the
841 tracking branches in your git repository. You can see these files
842 by checking out this branch, but you must @emph{never} edit any
843 files while this branch is checked out. Check out your local
844 @q{master} branch again.
846 You then need to merge these fetched files into your local @q{master}
847 branch by clicking on
854 and if necessary select the local @q{master} branch.
856 Note that a merge cannot be completed if you have made any local
857 changes which have not yet been committed.
859 This merge will update all the files in the @q{master} branch to
860 reflect the current state of the @q{origin/master} branch. If any
861 of the changes conflict with changes you have made yourself recently
862 you will be notified of the conflict (see below).
864 @subsection Editing files
866 First ensure your @q{master} branch is checked out, then
867 simply edit the files in your local Git repository with your
868 favourite editor and save them back there. If any file contains
869 non-ASCII characters ensure you save it in UTF-8 format. Git will
870 detect any changes whenever you restart Git GUI and the file names
871 will then be listed in the Unstaged Changes panel.
872 Or you can click the Rescan button to refresh the panel
873 contents at any time. You may break off and resume editing any
876 The changes you have made may be displayed in diff form in the top
877 right-hand panel of Git GUI by clicking on the file name shown in
878 one of the left panels.
880 When your editing is complete, move the files from being
881 Unstaged to Staged by clicking the document symbol to
882 the left of each name. If you change your mind it can
883 be moved back by clicking on the ticked box to the
886 Finally the changes you have made may be committed to
887 your @q{master} branch by entering a brief message in
888 the Commit Message box and clicking the Commit button.
890 If you wish to amend your changes after a commit has been
891 made, the original version and the changes you made in that
892 commit may be recovered by selecting
895 Commit -> Amend Last Commit
899 or by checking the Amend Last Commit radio button at bottom right.
900 This will return the changes to the Staged state, so further
901 editing made be carried out within that commit. This must only be
902 done @emph{before} the changes have been Pushed or sent to your
903 mentor for Pushing - after that it is too late and corrections
904 have to be made as a separate commit.
907 @subsection Sending changes to @q{remotes/origin/master}
909 If you do not have write access to @q{remotes/origin/master} you
910 will need to send your changes by email to someone who does.
912 First you need to create a diff or patch file containing
913 your changes. To create this, the file must first be
914 committed. Then terminate the Git GUI. In the
915 git bash shell first cd to your Git repository with
921 if necessary, then produce the patch with
924 git format-patch origin
927 This will create a patch file for all the locally committed files
928 which differ from @q{origin/master}. The patch file can be found
929 in [path]/Git and will have a name formed from the commit
932 @subsection Resolving merge conflicts
934 As soon as you have committed a changed file your local @q{master}
935 branch has diverged from @q{origin/master}, and will
936 remain diverged until your changes have been committed
937 in @q{remotes/origin/master} and Fetched back into your
938 @q{origin/master} branch. Similarly, if a new commit has been made
939 to @q{remotes/origin/master} by someone else and Fetched, your
940 local @q{master} branch is divergent. You can detect a divergent
941 branch by clicking on
944 Repository -> Visualise all branch history
947 This opens up a very useful new window called @q{gitk}.
948 Use this to browse all the commits made by yourself and others.
950 If the diagram at top left of the resulting window
951 does not show your @q{master} tag on the same node as
952 the @q{remotes/origin/master} tag your branch has diverged from
953 @q{origin/master}. This is quite normal if files you have modified
954 yourself have not yet been Pushed to @q{remotes/origin/master} and
955 Fetched, or if files modified and committed by others have been
956 Fetched since you last Merged @q{origin/master} into your local
959 If a file being merged from @q{origin/master} differs from
960 one you have modified in a way that cannot be resolved
961 automatically by git, Merge will report a Conflict
962 which you must resolve by editing the file to create the
963 version you wish to keep.
965 This could happen if the person updating @q{remotes/origin/master}
966 for you has added some changes of his own before
967 committing your changes to @q{remotes/origin/master}, or if someone
968 else has changed the same file since you last
969 fetched the file from @q{remotes/origin/master}.
971 Open the file in your editor and look for sections which
972 are delimited with ...
974 [to be completed when I next have a merge conflict to be
975 sure I give the right instructions -td]
978 @subsection Other actions
980 The instructions above describe the simplest way of using
981 git on Windows. Other git facilities which may usefully
982 supplement these include
986 @item Using multiple local branches (Create, Rename, Delete)
987 @item Resetting branches
988 @item Cherry-picking commits
989 @item Pushing commits to @w{remote/origin/master}
990 @item Using gitk to review history
994 Once familiarity with using git on Windows has been gained the
995 standard git manuals can be used to learn about these.
998 @node Other git documentation
999 @section Other git documentation
1004 Official git man pages: @uref{http://www.kernel.org/pub/software/scm/git/docs/}
1007 More in-depth tutorials: @uref{http://git-scm.com/documentation}
1010 Book about git: @uref{http://progit.org/,Pro Git}
1015 @node Roadmap of directories
1016 @section Roadmap of directories
1018 @c TODO: integrate the roadmap better
1019 @verbatiminclude ROADMAP