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.
62 @subsubheading New local commit
64 A single commit typically represents one logical set of related
65 changes (such as a bug-fix), and may incorporate changes to
66 multiple files at the same time.
68 When you're finished making the changes for your first commit,
69 click the @qq{New local commit} button. This will open the
70 @qq{Git Commit Message} window. The message header is required,
71 and the message body is optional. See @ref{Commits and patches}
72 for more information regarding commits and commit messages.
74 After entering a commit message, click @qq{OK} to finalize the
78 @subsubheading Amend previous commit
80 You can go back and make changes to the most recent commit with
81 the @qq{Amend previous commit} button. This is useful if a
82 mistake is found after you've clicked the @qq{New local commit}
83 button. To amend the most recent commit, edit the source files as
84 needed and click the button. The earlier version of the commit is
85 not saved, but is replaced by the new one.
87 Note that this does not update patch files; if you have a patch
88 file from an earlier version of the commit, you will need to make
89 another patch set when using this feature. The old patch file is
90 not saved, but is replaced by the new one.
93 @subsubheading Make patch set
95 Before making a patch set from any commits, you should click the
96 @qq{Update source} button to make sure the commits are based on
97 the most recent remote snapshot.
99 When you click the @qq{Make patch set} button, @command{lily-git}
100 will produce patch files for any new commits, saving them to the
101 current directory. The command output will display the name of
102 the new patch files near the end of the output:
105 0001-CG-add-lily-git-instructions.patch
109 Send patch files to your mentor if you have one. Otherwise, write
110 an email (must be less than 64 KB) to
111 @email{lilypond-devel@@gnu.org} briefly explaining your work, with
112 the patch files attached. Translators should send patches to
113 @email{translations@@lilynet.net}.
116 @subsubheading The @qq{Abort changes -- Reset to origin} button
118 @warning{Only use this if your local commit history gets
119 hopelessly confused!}
121 The button labeled @qq{Abort changes -- Reset to origin} will copy
122 all changed files to a subdirectory of @file{lilypond-git/} named
123 @file{aborted_edits/}, and will reset the repository to the
124 current state of the remote repository (at @code{git.sv.gnu.org}).
127 @node Starting with Git
128 @section Starting with Git
131 Using the Git program directly (as opposed to using the
132 @command{lily-git} GUI) allows you to have much greater control
133 over the contributing process. You should consider using Git if
134 you want to work on complex projects, or if you want to work on
135 multiple projects concurrently.
140 * Downloading remote branches::
145 @subsection Setting up
148 TODO: Remove this note if incorporating Windows instructions
149 throughout this section:
151 @warning{These instructions assume that you are using the
152 command-line version of Git 1.5 or higher. Windows users should
153 skip to @ref{Git on Windows}.}
157 * Initializing a repository::
163 @unnumberedsubsubsec Installing Git
166 If you are using a Unix-based machine, the easiest way to download
167 and install Git is through a package manager such as @command{rpm}
168 or @command{apt-get}---the installation is generally automatic.
169 The only required package is (usually) called @command{git-core},
170 although some of the auxiliary @command{git@var{*}} packages are
171 also useful (such as @command{gitk}).
173 Alternatively, you can visit the Git website
174 (@uref{http://git-scm.com/}) for downloadable binaries and
177 TODO: add Windows installation instructions (or @@ref@{Git on
181 @node Initializing a repository
182 @unnumberedsubsubsec Initializing a repository
185 Once Git is installed, you'll need to create a new directory where
186 your initial repository will be stored (the example below uses
187 @file{~/lilypond-git/}, where @code{~} represents your home
188 directory). Run @command{git@tie{}init} from within the new
189 directory to initialize an empty repository:
192 mkdir ~/lilypond-git/; cd ~/lilypond-git/
196 @subsubheading Technical details
198 This creates (within the @file{~/lilypond-git/} directory) a
199 subdirectory called @file{.git/}, which Git uses to keep track of
200 changes to the repository, among other things. Normally you don't
201 need to access it, but it's good to know it's there.
204 @node Configuring Git
205 @unnumberedsubsubsec Configuring Git
207 @warning{Throughout the rest of this manual, all command-line
208 input should be entered from the top directory of the Git
209 repository being discussed (eg. @file{~/lilypond-git/}). This is
210 referred to as a @emph{top source directory}.}
212 Before downloading a copy of the main LilyPond repository, you
213 should configure some basic settings with the
214 @command{git@tie{}config} command. Git allows you to set both
215 global and repository-specific options.
217 To configure settings that affect all repositories, use the
218 @command{--global} command line option. For example, the first
219 two options that you should always set are your @var{name} and
220 @var{email}, since Git needs these to keep track of commit
224 git config --global user.name "@var{John Smith}"
225 git config --global user.email @var{john@@example.com}
228 To configure Git to use colored output where possible, use:
231 git config --global color.ui auto
234 The text editor that opens when using @command{git@tie{}commit}
235 can also be changed. If none of your editor-related environment
236 variables are set ($GIT_EDITOR, $VISUAL, or $EDITOR), the default
237 editor is usually @command{vi} or @command{vim}. If you're not
238 familiar with either of these, you should probably change the
239 default to an editor that you know how to use. For example, to
240 change the default editor to @command{nano}, enter:
243 git config --global core.editor @var{nano}
246 TODO: Add instructions for changing the editor on Windows, which
247 is a little different, I think. -mp
249 @subsubheading Technical details
251 Git stores the information entered with
252 @command{git@tie{}config@tie{}--global} in the file
253 @file{.gitconfig}, located in your home directory. This file can
254 also be modified directly, without using
255 @command{git@tie{}config}. The @file{.gitconfig} file generated
256 by the above commands would look like this:
261 email = john@@example.com
268 Using the @command{git@tie{}config} command @emph{without} the
269 @command{--global} option configures repository-specific settings,
270 which are stored in the file @file{.git/config}. This file is
271 created when a repository is initialized (using
272 @command{git@tie{}init}), and by default contains these lines:
276 repositoryformatversion = 0
279 logallrefupdates = true
282 However, since different repository-specific options are
283 recommended for different development tasks, it is best to avoid
284 setting any now. Specific recommendations will be mentioned later
288 @node Downloading remote branches
289 @subsection Downloading remote branches
293 * Organization of remote branches::
294 * LilyPond repository sources::
295 * Downloading individual branches::
296 * Downloading all remote branches::
301 @node Organization of remote branches
302 @unnumberedsubsubsec Organization of remote branches
305 The main LilyPond repository is organized into @emph{branches} to
306 facilitate development. These are often called @emph{remote}
307 branches to distinguish them from @emph{local} branches you might
308 create yourself (see @ref{Using local branches}).
310 The @code{master} branch contains all the source files used to
311 build LilyPond, which includes the program itself (both stable and
312 development releases), the documentation (and its translations),
313 and the website. Generally, the @code{master} branch is expected
314 to compile successfully.
316 The @code{lilypond/translation} branch is a side branch that
317 allows translators to work without needing to worry about
318 compilation problems. Periodically, the Translation Meister
319 (after verifying that it doesn't break compilation), will
320 @emph{merge} this branch back into @code{master} to incorporate
321 recent translations. Similarly, the @code{master} branch is
322 usually merged into the @code{lilypond/translation} branch after
323 significant changes to the English documentation. See
324 @ref{Translating the documentation} for details.
327 @node LilyPond repository sources
328 @unnumberedsubsubsec LilyPond repository sources
331 The recommended source for downloading a copy of the main
335 git://git.sv.gnu.org/lilypond.git
338 However, if your internet router filters out connections using the
339 GIT protocol, or if you experience difficulty connecting via GIT,
340 you can try these other sources:
343 ssh://git.sv.gnu.org/srv/git/lilypond.git
344 http://git.sv.gnu.org/r/lilypond.git
347 The SSH protocol can only be used if your system is properly set
348 up to use it. Also, the HTTP protocol is slowest, so it should
349 only be used as a last resort.
352 @node Downloading individual branches
353 @unnumberedsubsubsec Downloading individual branches
356 Once you have initialized an empty Git repository on your system
357 (see @ref{Initializing a repository}), you can download a remote
358 branch into it. Make sure you know which branch you want to start
361 To download the @code{master} branch, enter the following:
364 git remote add -ft master -m master \
365 origin git://git.sv.gnu.org/lilypond.git/
368 To download the @code{lilypond/translation} branch, enter:
371 git remote add -ft lilypond/translation -m \
372 lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
375 The @command{git@tie{}remote@tie{}add} process could take up to
376 ten minutes, depending on the speed of your connection. The
377 output will be something like this:
381 remote: Counting objects: 235967, done.
382 remote: Compressing objects: 100% (42721/42721), done.
383 remote: Total 235967 (delta 195098), reused 233311 (delta 192772)
384 Receiving objects: 100% (235967/235967), 68.37 MiB | 479 KiB/s, done.
385 Resolving deltas: 100% (195098/195098), done.
386 From git://git.sv.gnu.org/lilypond
387 * [new branch] master -> origin/master
388 From git://git.sv.gnu.org/lilypond
389 * [new tag] flower/1.0.1 -> flower/1.0.1
390 * [new tag] flower/1.0.10 -> flower/1.0.10
392 * [new tag] release/2.9.6 -> release/2.9.6
393 * [new tag] release/2.9.7 -> release/2.9.7
396 When @command{git@tie{}remote@tie{}add} is finished, the remote
397 branch should be downloaded into your repository---though not yet
398 in a form that you can use. In order to browse the source code
399 files, you need to @emph{create} and @emph{checkout} your own
400 local branch. In this case, however, it is easier to have Git
401 create the branch automatically by using the @command{checkout}
402 command on a non-existent branch. Enter the following:
405 git checkout -b @var{branch} origin/@var{branch}
409 where @code{@var{branch}} is the name of your tracking branch,
410 either @code{master} or @code{lilypond/translation}.
412 Git will issue some warnings; this is normal:
415 warning: You appear to be on a branch yet to be born.
416 warning: Forcing checkout of origin/master.
417 Branch master set up to track remote branch master from origin.
421 By now the source files should be accessible---you should be able
422 to edit any files in the @file{lilypond-git/} directory using a
423 text editor of your choice. But don't start just yet! Before
424 editing any source files, learn how to keep your changes organized
425 and prevent problems later---read @ref{Basic Git procedures}.
427 @subsubheading Technical Details
429 The @command{git@tie{}remote@tie{}add} command should add some
430 lines to your local repository's @file{.git/config} file:
434 url = git://git.sv.gnu.org/lilypond.git/
435 fetch = +refs/heads/master:refs/remotes/origin/master
439 @node Downloading all remote branches
440 @unnumberedsubsubsec Downloading all remote branches
443 To download all remote branches at once, you can @command{clone}
444 the entire repository:
447 git clone git://git.sv.gnu.org/lilypond.git
452 @unnumberedsubsubsec Other branches
454 Most contributors will never need to touch the other branches. If
455 you wish to do so, you will need more familiarity with Git; please
456 see @ref{Other Git documentation}.
459 @item @code{dev/XYZ}:
460 These branches are for individual developers. They store code
461 which is not yet stable enough to be added to the @code{master}
464 @item @code{stable/XYZ}:
465 The branches are kept for archival reasons.
469 Another item of interest might be the Grand Unified Builder, our
470 cross-platform building tool. Since it is used by projects as
471 well, it is not stored in our gub repository. For more info, see
472 @uref{http://lilypond.org/gub}. The git location is
473 @uref{http://github.com/janneke/gub}.
476 @node Basic Git procedures
477 @section Basic Git procedures
481 * The Git contributor's cycle::
482 * Pulling and rebasing::
483 * Using local branches::
484 * Commits and patches::
488 @node The Git contributor's cycle
489 @subsection The Git contributor's cycle
492 Here is a simplified view of the contribution process on Git:
496 Update your local repository by @emph{pulling} the most recent
497 updates from the remote repository.
500 Edit source files within your local repository's @emph{working
504 @emph{Commit} the changes you've made to a local @emph{branch}.
507 Generate a @emph{patch} to share your changes with the developers.
511 @node Pulling and rebasing
512 @subsection Pulling and rebasing
515 When developers push new patches to the @code{git.sv.gnu.org}
516 repository, your local repository is @strong{not} automatically
517 updated. It is important to keep your repository up-to-date by
518 periodically @emph{pulling} the most recent @emph{commits} from
519 the remote branch. Developers expect patches to be as current as
520 possible, since outdated patches require extra work before they
523 Occasionally you may need to rework some of your own modifications
524 to match changes made to the remote branch (see @ref{Resolving
525 conflicts}), and it's considerably easier to rework things
526 incrementally. If you don't update your repository along the way,
527 you may have to spend a lot of time resolving branch conflicts and
528 reconfiguring much of the work you've already done.
530 Fortunately, Git is able to resolve certain types of branch
531 conflicts automatically with a process called @emph{rebasing}.
532 When rebasing, Git tries to modify your old commits so they appear
533 as new commits (based on the latest updates). For a more involved
534 explanation, see the @command{git-rebase} man page.
536 To pull without rebasing (recommended for translators), use the
540 git pull # recommended for translators
543 If you're tracking the remote @code{master} branch, you should add
544 the @code{-r} option (short for @code{--rebase}) to keep commits
545 on your local branch current:
548 git pull -r # use with caution when translating
551 If you don't edit translated documentation and don't want to type
552 @code{-r} every time, configure the master branch to rebase by
553 default with this command:
556 git config branch.master.rebase true
559 If pull fails because of a message like
562 error: Your local changes to 'Documentation/learning/tutorial.itely'
563 would be overwritten by merge. Aborting.
570 Documentation/learning/tutorial.itely: needs update
571 refusing to pull with rebase: your working tree is not up-to-date
575 it means that you have modified some files in you working tree
576 without committing changes (see @ref{Commits and patches}); you
577 can use the @command{git@tie{}stash} command to work around this:
580 git stash # save uncommitted changes
581 git pull -r # pull using rebase (translators omit "-r")
582 git stash pop # reapply previously saved changes
585 Note that @command{git@tie{}stash@tie{}pop} will try to apply a
586 patch, and this may create a conflict. If this happens, see
587 @ref{Resolving conflicts}.
589 TODO: I think the next paragraph is confusing. Perhaps prepare
590 the reader for new terms `committish' and `head'? -mp
592 @warning{translators and documentation editors, if you have
593 changed committishes in the head of translated files using commits
594 you have not yet pushed to @code{git.sv.gnu.org}, please do not
595 rebase. If you want to avoid wondering whether you should rebase
596 each time you pull, please always use committishes from master
597 and/or lilypond/translation branch on @code{git.sv.gnu.org}, which
598 in particular implies that you must push your changes to
599 documentation except committishes updates (possibly after having
600 rebased), then update the committishes and push them.}
602 TODO: when committishes automatic conditional update have been
603 tested and documented, append the following to the warning above:
604 Note that using update-committishes make target generally touches
607 @subsubheading Technical details
609 The @command{git@tie{}config} command mentioned above adds the
610 line @code{rebase = true} to the master branch in your local
611 repository's @file{.git/config} file:
616 merge = refs/heads/master
621 @node Using local branches
622 @subsection Using local branches
626 * Creating and removing branches::
627 * Listing branches and remotes::
628 * Checking out branches::
633 @node Creating and removing branches
634 @unnumberedsubsubsec Creating and removing branches
637 Local branches are useful when you're working on several different
638 projects concurrently. To create a new branch, enter:
641 git branch @var{name}
644 To delete a branch, enter:
647 git branch -d @var{name}
650 Git will ask you for confirmation if it sees that data would be
651 lost by deleting the branch. Use @code{-D} instead of @code{-d}
652 to bypass this. Note that you cannot delete a branch if it is
653 currently checked out.
656 @node Listing branches and remotes
657 @unnumberedsubsubsec Listing branches and remotes
659 You can get the exact path or URL of all remote branches by
666 To list Git branches on your local repositories, run
669 git branch # list local branches only
670 git branch -r # list remote branches
671 git branch -a # list all branches
675 @node Checking out branches
676 @unnumberedsubsubsec Checking out branches
678 To know the currently checked out branch, i.e. the branch whose
679 source files are present in your working tree, read the first line
687 The currently checked out branch is also marked with an asterisk
688 in the output of @command{git branch}.
690 You can check out another branch @code{@var{other_branch}}, i.e.
691 check out @code{@var{other_branch}} to the working tree, by
695 git checkout @var{other_branch}
698 Note that it is possible to check out another branch while having
699 uncommitted changes, but it is not recommended unless you know
700 what you are doing; it is recommended to run @command{git status}
701 to check this kind of issue before checking out another branch.
703 @node Merging branches
704 @unnumberedsubsubsec Merging branches
706 To merge branch @code{@var{foo}} into branch @code{@var{bar}},
707 i.e. to @qq{add} all changes made in branch @code{@var{foo}} to
708 branch @code{@var{bar}}, run
711 git checkout @var{bar}
715 If any conflict happens, see @ref{Resolving conflicts}.
717 There are common usage cases for merging: as a translator, you
718 will often want to merge @code{master} into
719 @code{lilypond/translation}; on the other hand, the Translations
720 meister wants to merge @code{lilypond/translation} into
721 @code{master} whenever he has checked that
722 @code{lilypond/translation} builds successfully.
725 @node Commits and patches
726 @subsection Commits and patches
730 * Understanding commits::
737 @node Understanding commits
738 @unnumberedsubsubsec Understanding commits
740 Technically, a @emph{commit} is a single point in the history of a
741 branch, but most developers use the term to mean a @emph{commit
742 object}, which stores information about a particular revision. A
743 single commit can record changes to multiple source files, and
744 typically represents one logical set of related changes (such as a
745 bug-fix). You can list the ten most recent commits in your
746 current branch with this command:
749 git log -10 --oneline
752 If you're using an older version of Git and get an @q{unrecognized
753 argument} error, use this instead:
756 git log -10 --pretty=oneline --abbrev-commit
759 More interactive lists of the commits on the remote @code{master}
760 branch are available at
761 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=shortlog} and
762 @uref{http://git.sv.gnu.org/cgit/lilypond.git/log/}.
766 @unnumberedsubsubsec Making commits
769 Once you have modified some source files in your working
770 directory, you can make a commit with the following procedure:
774 Make sure you've configured Git properly (see @ref{Configuring
775 Git}). Check that your changes meet the requirements described in
776 @ref{Code style} and/or @ref{Documentation policy}. For advanced
777 edits, you may also want to verify that the changes don't break
778 the compilation process.
781 Run the following command:
788 to make sure you're on the right branch, and to see which files
789 have been modified, added or removed, etc. You may need to tell
790 Git about any files you've added by running one of these:
793 git add @var{file} # add untracked @var{file} individually
794 git add . # add all untracked files in current directory
798 After @command{git@tie{}add}, run @command{git@tie{}status} again
799 to make sure you got everything. You may also need to modify
803 Preview the changes about to be committed (to make sure everything
811 The @code{HEAD} argument refers to the most recent commit on the
812 currently checked-out branch.
815 Generate the commit with:
822 The @code{-a} is short for @code{--all} which includes modified
823 and deleted files, but only those newly created files that have
824 previously been added.
829 @node Commit messages
830 @unnumberedsubsubsec Commit messages
833 When you run the @command{git@tie{}commit@tie{}-a} command, Git
834 automatically opens the default text editor so you can enter a
835 @emph{commit message}. If you find yourself in a foreign editing
836 environment, you're probably in @command{vi} or @command{vim}. If
837 you want to switch to an editor you're more familiar with, quit by
838 typing @code{:q!} and pressing @code{<Enter>}. See
839 @ref{Configuring Git} for instructions on changing the default
842 In any case, Git will open a text file for your commit message
843 that looks like this:
847 # Please enter the commit message for your changes. Lines starting
848 # with '#' will be ignored, and an empty message aborts the commit.
850 # Changes to be committed:
851 # (use "git reset HEAD <file>..." to unstage)
853 # modified: working.itexi
857 Your commit message should begin with a one-line summary
858 describing the change (no more than 50 characters long), and if
859 necessary a blank line followed by several lines giving the
862 @c $ git log -1 --pretty=medium 4d6f1e5
864 Doc: add Baerenreiter and Henle solo cello suites
866 Added comparison of solo cello suite engravings to new essay with
867 high-res images, fixed cropping on Finale example.
870 Commit messages often start with a short prefix describing the
871 general location of the changes. If a commit affects the
872 documentation in English (or in several languages simultaneously)
873 the commit message should be prefixed with @qq{Doc:@tie{}}. If
874 the commit affects only one of the translations, the commit
875 message should be prefixed with @qq{Doc-@var{**}:@tie{}}, where
876 @var{**} is the two-letter language code. Commits that affect the
877 website should use @qq{Web:@tie{}} for English, and
878 @qq{Web-@var{**}:@tie{}} for the other languages. Also, changes
879 to a single file are often prefixed with the name of the file
880 involved. Visit the links listed in @ref{Understanding commits}
885 @unnumberedsubsubsec Making patches
888 If you want to share your changes with other contributors and
889 developers, you need to generate @emph{patches} from your commits.
890 You should always run @command{git@tie{}pull@tie{}-r} (translators
891 should leave off the @code{-r}) before doing this to ensure that
892 your patches are as current as possible.
894 Once you have made one or more commits in your local repository,
895 and pulled the most recent commits from the remote branch, you can
896 generate patches from your local commits with the command:
899 git format-patch origin
902 The @code{origin} argument refers to the remote tracking branch at
903 @code{git.sv.gnu.org}. This command generates a separate patch
904 for each commit that's in the current branch but not in the remote
905 branch. Patches are placed in the current working directory and
906 will have names that look something like this:
909 0001-Doc-Fix-typos.patch
910 0002-Web-Remove-dead-links.patch
914 Send an email (must be less than 64 KB) to
915 @email{lilypond-devel@@gnu.org} briefly explaining your work, with
916 the patch files attached. Translators should send patches to
917 @email{translations@@lilynet.net}. After your patches are
918 reviewed, the developers may push one or more of them to the main
919 repository or discuss them with you.
923 If your patch includes a significant amount of code, you may want
924 to see @ref{Adding or modifying features}, especially @emph{Post
928 @node Advanced Git procedures
929 @section Advanced Git procedures
932 @warning{This section is not necessary for normal contributors;
933 these commands are presented for information for people interested
934 in learning more about git.}
936 It is possible to work with several branches on the same local Git
937 repository; this is especially useful for translators who may have
938 to deal with both @code{lilypond/translation} and a stable branch,
939 e.g. @code{stable/2.12}.
941 Some Git commands are introduced first, then a workflow with
942 several Git branches of LilyPond source code is presented.
946 * Advanced Git concepts::
947 * Resolving conflicts::
948 * Reverting all local changes::
949 * Working with remote branches::
951 * Applying remote patches::
952 * Sending and receiving patches via email::
957 @node Advanced Git concepts
958 @subsection Advanced Git concepts
961 A bit of Git vocabulary will be explained below. The following is
962 only introductory; for a better understanding of Git concepts, you
963 may wish to read @ref{Other Git documentation}.
965 The @code{git@tie{}pull@tie{}origin} command above is just a
966 shortcut for this command:
969 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
973 where @code{@var{branch}} is typically @code{master} or
974 @code{lilypond/translation}; if you do not know or remember, see
975 @ref{Downloading remote branches} to remember which commands you
976 issued or which source code you wanted to get.
978 A @emph{commit} is a set of changes made to the sources; it also
979 includes the committish of the parent commit, the name and e-mail
980 of the @emph{author} (the person who wrote the changes), the name
981 and e-mail of the @emph{committer} (the person who brings these
982 changes into the Git repository), and a commit message.
984 A @emph{committish} is the SHA1 checksum of a commit, a number
985 made of 40 hexadecimal digits, which acts as the internal unique
986 identifier for this commit. To refer to a particular revision,
987 don't use vague references like the (approximative) date, simply
988 copy and paste the committish.
990 A @emph{branch} is nothing more than a pointer to a particular
991 commit, which is called the @emph{head} of the branch; when
992 referring to a branch, one often acutally thinks about its head
993 and the ancestor commits of the head.
995 Now we will explain the two last commands you used to get the
996 source code from Git---see @ref{Downloading individual branches}.
999 git remote add -ft @var{branch} -m @var{branch} \
1000 origin git://git.sv.gnu.org/lilypond.git/
1002 git checkout -b @var{branch} origin/@var{branch}
1005 The @command{git@tie{}remote} has created a branch called
1006 @code{origin/@var{branch}} in your local Git repository. As this
1007 branch is a copy of the remote branch web from git.sv.gnu.org
1008 LilyPond repository, it is called a @emph{remote branch}, and is
1009 meant to track the changes on the branch from git.sv.gnu.org: it
1010 will be updated every time you run
1011 @command{git@tie{}pull@tie{}origin} or
1012 @command{git@tie{}fetch@tie{}origin}.
1014 The @command{git@tie{}checkout} command has created a branch named
1015 @code{@var{branch}}. At the beginning, this branch is identical
1016 to @code{origin/@var{branch}}, but it will differ as soon as you
1017 make changes, e.g. adding newly translated pages or editing some
1018 documentation or code source file. Whenever you pull, you merge
1019 the changes from @code{origin/@var{branch}} and
1020 @code{@var{branch}} since the last pulling. If you do not have
1021 push (i.e. @qq{write}) access on git.sv.gnu.org, your
1022 @code{@var{branch}} will always differ from
1023 @code{origin/@var{branch}}. In this case, remember that other
1024 people working like you with the remote branch @code{@var{branch}}
1025 of git://git.sv.gnu.org/lilypond.git/ (called
1026 @code{origin/@var{branch}} on your local repository) know nothing
1027 about your own @code{@var{branch}}: this means that whenever you
1028 use a committish or make a patch, others expect you to take the
1029 latest commit of @code{origin/@var{branch}} as a reference.
1031 Finally, please remember to read the man page of every Git command
1032 you will find in this manual in case you want to discover
1033 alternate methods or just understand how it works.
1036 @node Resolving conflicts
1037 @subsection Resolving conflicts
1040 Occasionally an update may result in conflicts -- this happens
1041 when you and somebody else have modified the same part of the same
1042 file and git cannot figure out how to merge the two versions
1043 together. When this happens, you must manually merge the two
1046 If you need some documentation to understand and resolve
1047 conflicts, see paragraphs @emph{How conflicts are presented} and
1048 @emph{How to resolve conflicts} in @command{git merge} man page.
1050 If all else fails, you can follow the instructions in
1051 @ref{Reverting all local changes}. Be aware that this eliminates
1052 any changes you have made!
1055 @node Reverting all local changes
1056 @subsection Reverting all local changes
1058 Sometimes git will become hopelessly confused, and you just want
1059 to get back to a known, stable state. This command destroys any
1060 local changes you have made, but at least you get back to the
1061 current online version:
1064 git reset --hard origin/master
1068 @node Working with remote branches
1069 @subsection Working with remote branches
1072 @subsubheading Fetching new branches from git.sv.gnu.org
1074 To fetch and check out a new branch named @code{@var{branch}} on
1075 git.sv.gnu.org, run from top of the Git repository
1078 git config --add remote.origin.fetch \
1079 +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
1081 git checkout --track -b @var{branch} origin/@var{branch}
1084 After this, you can pull @code{@var{branch}} from git.sv.gnu.org
1091 Note that this command generally fetches all branches you added
1092 with @command{git@tie{}remote@tie{}add} (when you initialized the
1093 repository) or @command{git@tie{}config@tie{}--add}, i.e. it
1094 updates all remote branches from remote @code{origin}, then it
1095 merges the remote branch tracked by the current branch into the
1096 current branch. For example, if your current branch is
1097 @code{master}, @code{origin/master} will be merged into
1101 @subsubheading Local clones, or having several working trees
1103 If you play with several Git branches, e.g. @code{master},
1104 @code{lilypond/translation}, @code{stable/2.12}), you may want to
1105 have one source and build tree for each branch; this is possible
1106 with subdirectories of your local Git repository, used as local
1107 cloned subrepositories. To create a local clone for the branch
1108 named @code{@var{branch}}, run
1111 git checkout @var{branch}
1112 git clone -lsn . @var{subdir}
1117 Note that @code{@var{subdir}} must be a directory name which does
1118 not already exist. In @code{@var{subdir}}, you can use all Git
1119 commands to browse revisions history, commit and uncommit changes;
1120 to update the cloned subrepository with changes made on the main
1121 repository, cd into @code{@var{subdir}} and run
1122 @command{git@tie{}pull}; to send changes made on the subrepository
1123 back to the main repository, run @command{git@tie{}push} from
1124 @code{@var{subdir}}. Note that only one branch (the currently
1125 checked out branch) is created in the subrepository by default; it
1126 is possible to have several branches in a subrepository and do
1127 usual operations (checkout, merge, create, delete...) on these
1128 branches, but this possibility is not detailed here.
1130 When you push @code{@var{branch}} from @code{@var{subdir}} to the
1131 main repository, and @code{@var{branch}} is checked out in the
1132 main repository, you must save uncommitted changes (see
1133 @command{git@tie{}stash}) and do
1134 @command{git@tie{}reset@tie{}--hard} in the main repository in
1135 order to apply pushed changes in the working tree of the main
1143 The commands above don't only bring you the latest version of the
1144 sources, but also the full history of revisions (revisons, also
1145 called commits, are changes made to the sources), stored in the
1146 @file{.git} directory. You can browse this history with
1149 git log # only shows the logs (author, committish and commit message)
1150 git log -p # also shows diffs
1151 gitk # shows history graphically
1154 @warning{The @code{gitk} command may require a separate
1155 @code{gitk} package, available in the appropriate distribution's
1159 @node Applying remote patches
1160 @subsection Applying remote patches
1163 TODO: Explain how to determine if a patch was created with
1164 @code{git@tie{}format-patch}.
1166 Well-formed git patches created with @code{git@tie{}format-patch}
1167 should be committed with the following command:
1173 Patches created without @code{git@tie{}format-patch} can be
1174 applied in two steps. The first step is to apply the patch to the
1178 git apply @var{patch}
1182 The second step is to commit the changes and give credit to the
1183 author of the patch. This can be done with the following command:
1186 git commit -a --author="@var{John Smith} <@var{john@@example.com}>"
1190 @node Sending and receiving patches via email
1191 @subsection Sending and receiving patches via email
1194 The default @code{x-diff} MIME type associated with patch files
1195 (i.e., files whose name ends in @code{.patch}) means that the
1196 encoding of line endings may be changed from UNIX to DOS format
1197 when they are sent as attachments. Attempting to apply such an
1198 inadvertently altered patch will cause git to fail with a message
1199 about @q{whitespace errors}.
1201 The solution to such problems is surprisingly simple---just change
1202 the default file extension of patches generated by git to end in
1203 @code{.txt}, for example:
1206 git config format.suffix '.patch.txt'
1209 This should cause email programs to apply the correct base64
1210 encoding to attached patches.
1212 If you receive a patch with DOS instead of UNIX line-endings, it
1213 can be converted back using the @code{dos2unix} utility.
1215 Lots of useful information on email complications with patches is
1216 provided on the Wine wiki at
1217 @uref{http://wiki.winehq.org/GitWine}.
1221 @subsection Commit access
1224 Most contributors are not able to commit patches directly to the
1225 main repository---only members of the LilyPond development team
1226 have @emph{commit access}. If you are a contributor and are
1227 interested in joining the development team, contact the Project
1228 Manager through the mailing list
1229 (@email{lilypond-devel@@gnu.org}). Generally, only contributors
1230 who have already provided a number of patches which have been
1231 pushed to the main repository will be considered for membership.
1233 If you have been approved by the Project Manager, use the
1234 following procedure to obtain commit access:
1238 If you don't already have one, set up a Savannah user account at
1239 @uref{https://savannah.gnu.org/account/register.php}. If your web
1240 browser responds with an @qq{untrusted connection} message when
1241 you visit the link, follow the steps for including the CAcert root
1242 certificate in your browser, given at
1243 @uref{http://savannah.gnu.org/tls/tutorial/}.
1247 After registering, if you are not logged in automatically, login
1248 at @uref{https://savannah.gnu.org/account/login.php}---this should
1249 take you to your @qq{my} page
1250 (@uref{https://savannah.gnu.org/my/}).
1254 Click on the @qq{My Groups} link to access the @qq{My Group
1255 Membership} page. From there, find the @qq{Request for Inclusion}
1256 box and search for @qq{LilyPond}. Among the search results, check
1257 the box labeled @qq{GNU LilyPond Music Typesetter} and write a
1258 brief (required) message for the Project Manager (@qq{Hey it's
1259 me!} should be fine).
1261 Note that you will not have commit access until the Project
1262 Manager activates your membership. Once your membership is
1263 activated, LilyPond should appear under the heading @qq{Groups I'm
1264 Contributor of} on your @qq{My Group Membership} page.
1268 Generate an SSH @q{dsa} key pair. Enter the following at the
1275 When prompted for a location to save the key, press <ENTER> to
1276 accept the default location (@file{~/.ssh/id_dsa}).
1278 Next you are asked to enter an optional passphrase. On most
1279 systems, if you use a passphrase, you will likely be prompted for
1280 it every time you use @command{git@tie{}push} or
1281 @command{git@tie{}pull}. You may prefer this since it can protect
1282 you from your own mistakes (like pushing when you mean to pull),
1283 though you may find it tedious to keep re-entering it.
1285 You can change/enable/disable your passphrase at any time with:
1288 ssh-keygen -f ~/.ssh/id_dsa -p
1291 Note that the GNOME desktop has a feature which stores your
1292 passphrase for you for an entire GNOME session. If you use a
1293 passphrase to @qq{protect you from yourself}, you will want to
1294 disable this feature, since you'll only be prompted once. Run the
1295 following command, then logout of GNOME and log back in:
1298 gconftool-2 --set -t bool \
1299 /apps/gnome-keyring/daemon-components/ssh false
1302 After setting up your passphrase, your private key is saved as
1303 @file{~/.ssh/id_dsa} and your public key is saved as
1304 @file{~/.ssh/id_dsa.pub}.
1308 Register your public SSH @q{dsa} key with Savannah. From the
1309 @qq{My Account Configuration} page, click on @qq{Edit SSH Keys},
1310 then paste the contents of your @file{~/.ssh/id_dsa.pub} file into
1311 one of the @qq{Authorized keys} text fields, and click
1314 Savannah should respond with something like:
1317 Success: Key #1 seen Keys registered
1322 Configure Git to use the SSH protocol (instead of the GIT
1323 protocol). From your local Git repository, enter:
1326 git config remote.origin.url \
1327 ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1331 where @var{user} is your username on Savannah.
1335 After your membership has been activated and you’ve configured Git
1336 to use SSH, test the connection with:
1342 SSH should issue the following warning:
1345 The authenticity of host 'git.sv.gnu.org (140.186.70.72)' can't
1347 RSA key fingerprint is
1348 80:5a:b0:0c:ec:93:66:29:49:7e:04:2b:fd:ba:2c:d5.
1349 Are you sure you want to continue connecting (yes/no)?
1352 Make sure the RSA key fingerprint displayed matches the one above.
1353 If it doesn't, respond @qq{no} and check that you configured Git
1354 properly in the previous step. If it does match, respond
1355 @qq{yes}. SSH should then issue another warning:
1358 Warning: Permanently added 'git.sv.gnu.org,140.186.70.72' (RSA) to
1359 the list of known hosts.
1362 The list of known hosts is stored in the file
1363 @file{~/.ssh/known_hosts}.
1365 At this point, you are prompted for your passphrase if you have
1366 one, then Git will attempt a pull.
1368 If @command{git@tie{}pull@tie{}--verbose} fails, you should see
1369 error messages like these:
1372 Permission denied (publickey).
1373 fatal: The remote end hung up unexpectedly
1376 If you get the above error, you may have made a mistake when
1377 registering your SSH key at Savannah. If the key is properly
1378 registered, you probably just need to wait for the Savannah server
1379 to activate it. It usually takes a few minutes for the key to be
1380 active after registering it, but if it still doesn't work after an
1381 hour, ask for help on the mailing list.
1383 If @command{git@tie{}pull@tie{}--verbose} succeeds, the output
1384 will include a @q{From} line that shows @q{ssh} as the protocol:
1387 From ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond
1390 If the protocol shown is not @q{ssh}, check that you configured
1391 Git properly in the previous step.
1395 Test your commit access with a dry run:
1398 git push --dry-run --verbose
1401 Note that recent versions of Git (Git 1.6.3 or later) will issue a
1402 big warning if the above command is used. The simplest solution
1403 is to tell Git to push all matching branches by default:
1406 git config push.default matching
1410 Then @code{git@tie{}push} should work as before. For more
1411 details, consult the @code{git@tie{}push} man page.
1415 @subsubheading Technical details
1419 On Firefox, to view or remove the CAcert root certificate, go to:
1420 Edit > Preferences > Advanced > Encryption > View Certificates >
1421 Authorities > Certificate Name > Root CA > CA Cert Signing
1425 The @command{git@tie{}config} commands above should modify your
1426 local repository's @file{.git/config} file. These lines:
1430 url = git://git.sv.gnu.org/lilypond.git/
1434 should now be changed to:
1438 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1442 where @var{user} is your login name on Savannah.
1446 @command{git@tie{}config@tie{}push.default@tie{}matching} command
1447 should add these lines to @file{.git/config}:
1455 @node Git on Windows
1456 @section Git on Windows
1458 @c Some of this may duplicate stuff in other sections
1459 @c But it is probably best for windows users to have it all together
1460 @c If necessary, clear this up later -td
1462 TODO: Decide what to do with this... Pare it down? Move
1463 paragraphs next to analogous Unix instructions? -mp
1465 @subsection Background to nomenclature
1467 Git is a system for tracking the changes made to source files by a
1468 distributed set of editors. It is designed to work without a
1469 master repository, but we have chosen to have a master respository
1470 for LilyPond files. Editors hold a local copy of the master
1471 repository together with any changes they have made locally.
1472 Local changes are held in a local @q{branch}, of which there may
1473 be several, but these instructions assume you are using just one.
1474 The files visible in the local repository always correspond to
1475 those on the currently @q{checked out} local branch.
1477 Files are edited on a local branch, and in that state the changes
1478 are said to be @q{unstaged}. When editing is complete, the
1479 changes are moved to being @q{staged for commit}, and finally the
1480 changes are @q{committed} to the local branch. Once committed,
1481 the changes (called a @q{commit}) are given a unique 40-digit
1482 hexadecimal reference number called the @q{Committish} or @q{SHA1
1483 ID} which identifies the commit to Git. Such committed changes
1484 can be sent to the master repository by @q{pushing} them (if you
1485 have write permission) or by sending them by email to someone who
1486 has, either as a complete file or as a @q{diff} or @q{patch}
1487 (which send just the differences from the master repository).
1489 @subsection Installing git
1492 @uref{http://code.google.com/p/msysgit/downloads/list} (note, not
1493 msysGit, which is for Git developers and not PortableGit, which is
1494 not a full git installation) and install it.
1496 Note that most users will not need to install SSH. That is not
1497 required until you have been granted direct push permissions to
1498 the master git repository.
1500 Start Git by clicking on the desktop icon. This will bring up a
1501 command line bash shell. This may be unfamiliar to Windows users.
1502 If so, follow these instructions carefully. Commands are entered
1503 at a $ prompt and are terminated by keying a newline.
1505 @subsection Initialising Git
1507 Decide where you wish to place your local Git repository, creating
1508 the folders in Windows as necessary. Here we call the folder to
1509 contain the repository @code{[path]/Git}, but if you intend using
1510 Git for other projects a directory name like @code{lilypond-git}
1511 might be better. You will need to have space for around
1514 Start the Git bash shell by clicking on the desk-top icon
1515 installed with Git and type
1521 to position the shell at your new Git repository.
1523 Note: if [path] contains folders with names containing spaces use
1535 to initialize your Git repository.
1537 Then type (all on one line; the shell will wrap automatically)
1540 git remote add -ft master origin git://git.sv.gnu.org/lilypond.git
1543 to download the lilypond master files.
1545 @warning{Be patient! Even on a broadband connection this can take
1546 10 minutes or more. Wait for lots of [new tag] messages and the $
1549 We now need to generate a local copy of the downloaded files in a
1550 new local branch. Your local branch needs to have a name. It is
1551 usual to call it @q{master} and we shall do that here.
1556 git checkout -b master origin/master
1559 This creates a second branch called @q{master}. You will see two
1560 warnings (ignore these), and a message advising you that your
1561 local branch @q{master} has been set up to track the remote
1562 branch. You now have two branches, a local branch called
1563 @q{master}, and a tracking branch called @q{origin/master}, which
1564 is a shortened form of @q{remotes/origin/master}.
1566 Return to Windows Explorer and look in your Git repository. You
1567 should see lots of folders. For example, the LilyPond
1568 documentation can be found in [path]/Git/Documentation/.
1570 The Git bash shell is terminated by typing @code{exit} or by
1571 clicking on the usual Windows close-window widget.
1575 Almost all subsequent work will use the Git Graphical User
1576 Interface, which avoids having to type command line commands. To
1577 start Git GUI first start the Git bash shell by clicking on the
1578 desktop icon, and type
1585 The Git GUI will open in a new window. It contains four panels
1586 and 7 pull-down menus. At this stage do not use any of the
1587 commands under Branch, Commit, Merge or Remote. These will be
1590 The top panel on the left contains the names of files which you
1591 are in the process of editing (Unstaged Changes), and the lower
1592 panel on the left contains the names of files you have finished
1593 editing and have staged ready for committing (Staged Changes). At
1594 present, these panels will be empty as you have not yet made any
1595 changes to any file. After a file has been edited and saved the
1596 top panel on the right will display the differences between the
1597 edited file selected in one of the panels on the left and the last
1598 version committed on the current branch.
1600 The panel at bottom right is used to enter a descriptive message
1601 about the change before committing it.
1603 The Git GUI is terminated by entering CNTL-Q while it is the
1604 active window or by clicking on the usual Windows close-window
1607 @subsection Personalising your local git repository
1609 Open the Git GUI, click on
1615 and enter your name and email address in the left-hand (Git
1616 Repository) panel. Leave everything else unchanged and save it.
1618 Note that Windows users must leave the default setting for line
1619 endings unchanged. All files in a git repository must have lines
1620 terminated by just a LF, as this is required for Merge to work,
1621 but Windows files are terminated by CRLF by default. The git
1622 default setting causes the line endings of files in a Windows git
1623 repository to be flipped automatically between LF and CRLF as
1624 required. This enables files to be edited by any Windows editor
1625 without causing problems in the git repository.
1627 @subsection Checking out a branch
1629 At this stage you have two branches in your local repository,
1630 both identical. To see them click on
1636 You should have one local branch called @q{master} and one
1637 tracking branch called @q{origin/master}. The latter is your
1638 local copy of the @q{remotes/origin/master} branch in the master
1639 LilyPond repository. The local @q{master} branch is where you
1640 will make your local changes.
1642 When a particular branch is selected, i.e., checked out, the files
1643 visible in your repository are changed to reflect the state of the
1644 files on that branch.
1646 @subsection Updating files from @q{remote/origin/master}
1648 Before starting the editing of a file, ensure your local
1649 repository contains the latest version of the files in the remote
1650 repository by first clicking
1653 Remote -> Fetch from -> origin
1659 This will place the latest version of every file, including all
1660 the changes made by others, into the @q{origin/master} branch of
1661 the tracking branches in your git repository. You can see these
1662 files by checking out this branch, but you must @emph{never} edit
1663 any files while this branch is checked out. Check out your local
1664 @q{master} branch again.
1666 You then need to merge these fetched files into your local
1667 @q{master} branch by clicking on
1670 Merge -> Local Merge
1674 and if necessary select the local @q{master} branch.
1676 Note that a merge cannot be completed if you have made any local
1677 changes which have not yet been committed.
1679 This merge will update all the files in the @q{master} branch to
1680 reflect the current state of the @q{origin/master} branch. If any
1681 of the changes conflict with changes you have made yourself
1682 recently you will be notified of the conflict (see below).
1684 @subsection Editing files
1686 First ensure your @q{master} branch is checked out, then simply
1687 edit the files in your local Git repository with your favourite
1688 editor and save them back there. If any file contains non-ASCII
1689 characters ensure you save it in UTF-8 format. Git will detect
1690 any changes whenever you restart Git GUI and the file names will
1691 then be listed in the Unstaged Changes panel. Or you can click
1692 the Rescan button to refresh the panel contents at any time. You
1693 may break off and resume editing any time.
1695 The changes you have made may be displayed in diff form in the top
1696 right-hand panel of Git GUI by clicking on the file name shown in
1697 one of the left panels.
1699 When your editing is complete, move the files from being Unstaged
1700 to Staged by clicking the document symbol to the left of each
1701 name. If you change your mind it can be moved back by clicking on
1702 the ticked box to the left of the name.
1704 Finally the changes you have made may be committed to your
1705 @q{master} branch by entering a brief message in the Commit
1706 Message box and clicking the Commit button.
1708 If you wish to amend your changes after a commit has been made,
1709 the original version and the changes you made in that commit may
1710 be recovered by selecting
1713 Commit -> Amend Last Commit
1717 or by checking the Amend Last Commit radio button at bottom right.
1718 This will return the changes to the Staged state, so further
1719 editing made be carried out within that commit. This must only be
1720 done @emph{before} the changes have been Pushed or sent to your
1721 mentor for Pushing - after that it is too late and corrections
1722 have to be made as a separate commit.
1725 @subsection Sending changes to @q{remotes/origin/master}
1727 If you do not have write access to @q{remotes/origin/master} you
1728 will need to send your changes by email to someone who does.
1730 First you need to create a diff or patch file containing your
1731 changes. To create this, the file must first be committed. Then
1732 terminate the Git GUI. In the git bash shell first cd to your Git
1739 if necessary, then produce the patch with
1742 git format-patch origin
1745 This will create a patch file for all the locally committed files
1746 which differ from @q{origin/master}. The patch file can be found
1747 in [path]/Git and will have a name formed from the commit message.
1749 @subsection Resolving merge conflicts
1751 As soon as you have committed a changed file your local
1752 @code{master} branch has diverged from @code{origin/master}, and
1753 will remain diverged until your changes have been committed in
1754 @code{remotes/origin/master} and Fetched back into your
1755 @code{origin/master} branch. Similarly, if a new commit has been
1756 made to @code{remotes/origin/master} by someone else and Fetched,
1757 your local @code{master} branch is divergent. You can detect a
1758 divergent branch by clicking on
1761 Repository -> Visualise all branch history
1764 This opens up a very useful new window called @q{gitk}. Use this
1765 to browse all the commits made by yourself and others.
1767 If the diagram at top left of the resulting window does not show
1768 your @code{master} tag on the same node as the
1769 @code{remotes/origin/master} tag your branch has diverged from
1770 @code{origin/master}. This is quite normal if files you have
1771 modified yourself have not yet been Pushed to
1772 @code{remotes/origin/master} and Fetched, or if files modified and
1773 committed by others have been Fetched since you last Merged
1774 @code{origin/master} into your local @code{master} branch.
1776 If a file being merged from @code{origin/master} differs from one
1777 you have modified in a way that cannot be resolved automatically
1778 by git, Merge will report a Conflict which you must resolve by
1779 editing the file to create the version you wish to keep.
1781 This could happen if the person updating
1782 @code{remotes/origin/master} for you has added some changes of his
1783 own before committing your changes to
1784 @code{remotes/origin/master}, or if someone else has changed the
1785 same file since you last fetched the file from
1786 @code{remotes/origin/master}.
1788 Open the file in your editor and look for sections which are
1791 [to be completed when I next have a merge conflict to be sure I
1792 give the right instructions -td]
1795 @subsection Other actions
1797 The instructions above describe the simplest way of using git on
1798 Windows. Other git facilities which may usefully supplement these
1802 @item Using multiple local branches (Create, Rename, Delete)
1803 @item Resetting branches
1804 @item Cherry-picking commits
1805 @item Pushing commits to @w{remote/origin/master}
1806 @item Using gitk to review history
1809 Once familiarity with using git on Windows has been gained the
1810 standard git manuals can be used to learn about these.
1813 @node Repository directory structure
1814 @section Repository directory structure
1817 @c TODO: integrate the roadmap better
1818 @verbatiminclude ROADMAP
1821 @node Other Git documentation
1822 @section Other Git documentation
1826 Official git man pages:
1827 @uref{http://www.kernel.org/pub/software/scm/git/docs/}
1830 More in-depth tutorials: @uref{http://git-scm.com/documentation}
1833 Book about git: @uref{http://progit.org/,Pro Git}