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{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.
14 * Manually installing lily-git.tcl::
16 * Basic Git procedures::
17 * Advanced Git procedures::
19 * Repository directory structure::
20 * Other Git documentation::
24 @node Manually installing lily-git.tcl
25 @section Manually installing lily-git.tcl
27 We have created an easy-to-use GUI to simplify git for new
28 contributors. If you are comfortable with the command-line, then
29 skip ahead to @ref{Starting with Git}.
31 @warning{These instructions are only for people who are @emph{not}
34 @c there's some duplication in this section with stuff covered in
35 @c Quick Start, but moving it into a macro inside included/ would
36 @c be getting a bit icky. -gp
40 If you haven't already, download and install Git.
44 @item Windows users: download the @code{.exe} file labeled
45 @qq{Full installer for official Git} from:
48 @uref{https://git-for-windows.github.io/}
51 @item Other operating systems: either install @command{git} with
52 your package manager, or download it from the @qq{Binaries}
56 @uref{http://git-scm.com/download}
63 Download the @command{lily-git.tcl} script from:
65 @c don't change the cgit link below to gitweb; gitweb uses
66 @c long filenames like "scripts_auxiliar_lily-git.tcl"
69 @uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
73 To run the program from the command line, navigate to the
74 directory containing @command{lily-git.tcl} and enter:
81 Click on the @qq{Get source} button.
83 This will create a directory called @file{lilypond-git/} within
84 your home directory, and will download the source code into that
85 directory (around 150@tie{}Mb). When the process is finished, the
86 @qq{Command output} window will display @qq{Done}, and the button
87 label will change to say @qq{Update source}.
90 Navigate to the @file{lilypond-git/} directory to view the source
95 @warning{Throughout the rest of this manual, most command-line
96 input should be entered from @file{$LILYPOND_GIT}. This is
97 referred to as the @emph{top source directory}.}
99 Further instructions are in @ref{How to use lily-git}.
102 @node Starting with Git
103 @section Starting with Git
105 Using the Git program directly (as opposed to using the
106 @command{lily-git.tcl} GUI) allows you to have much greater control
107 over the contributing process. You should consider using Git if
108 you want to work on complex projects, or if you want to work on
109 multiple projects concurrently.
114 * Git for the impatient::
115 * Other repositories::
116 * Downloading remote branches::
121 @subsection Setting up
123 @warning{These instructions assume that you are using the
124 command-line version of Git 1.5 or higher. Windows users should
125 skip to @ref{Git on Windows}.}
129 * Initializing a repository::
135 @unnumberedsubsubsec Installing Git
137 If you are using a Unix-based machine, the easiest way to download
138 and install Git is through a package manager such as @command{rpm}
139 or @command{apt-get} -- the installation is generally automatic.
140 The only required package is (usually) called @command{git-core},
141 although some of the auxiliary @command{git@var{*}} packages are
142 also useful (such as @command{gitk}).
144 Alternatively, you can visit the Git website
145 (@uref{http://git-scm.com/}) for downloadable binaries and
149 @node Initializing a repository
150 @unnumberedsubsubsec Initializing a repository
152 Once Git is installed, get a copy of the source code:
155 git clone git://git.sv.gnu.org/lilypond.git ~/lilypond-git
158 The above command will put the it in @file{~/lilypond-git}, where
159 @code{~} represents your home directory.
161 @subsubheading Technical details
163 This creates (within the @file{$LILYPOND_GIT} directory) a
164 subdirectory called @file{.git/}, which Git uses to keep track of
165 changes to the repository, among other things. Normally you don't
166 need to access it, but it's good to know it's there.
169 @node Configuring Git
170 @unnumberedsubsubsec Configuring Git
172 @warning{Throughout the rest of this manual, all command-line
173 input should be entered from the top directory of the Git
174 repository being discussed (eg. @file{$LILYPOND_GIT}). This is
175 referred to as the @emph{top source directory}.}
177 Before working with the copy of the main LilyPond repository, you
178 should configure some basic settings with the
179 @command{git@tie{}config} command. Git allows you to set both
180 global and repository-specific options.
182 To configure settings that affect all repositories, use the
183 @option{--global} command line option. For example, the first
184 two options that you should always set are your @var{name} and
185 @var{email}, since Git needs these to keep track of commit
189 git config --global user.name "@var{John Smith}"
190 git config --global user.email @var{john@@example.com}
193 To configure Git to use colored output where possible, use:
196 git config --global color.ui auto
199 The text editor that opens when using @command{git@tie{}commit}
200 can also be changed. If none of your editor-related environment
201 variables are set ($GIT_EDITOR, $VISUAL, or $EDITOR), the default
202 editor is usually @command{vi} or @command{vim}. If you're not
203 familiar with either of these, you should probably change the
204 default to an editor that you know how to use. For example, to
205 change the default editor to @command{nano}, enter:
208 git config --global core.editor @var{nano}
211 Finally, and in some ways most importantly, let's make sure that
212 we can easily see the state of our working copy, without the need
213 of typing @code{git status} repeatedly. If you're not using
214 LilyDev, add the following lines to your @file{~/.bashrc}:
217 export PS1="\u@\h \w\$(__git_ps1)$ "
218 export GIT_PS1_SHOWDIRTYSTATE=true
219 export GIT_PS1_SHOWUNTRACKEDFILES=true
220 export GIT_PS1_SHOWUPSTREAM=auto
223 The first line will show the branch we're on. The other lines
224 will use some symbols next to the branch name to indicate some
225 kind of state. @qq{*} means that there are unstaged changes,
226 @qq{+} indicates staged changes; if there are untracked files,
227 a @qq{%} will appear. Finally, we can also see if our HEAD is
228 behind (@qq{<}) or ahead (@qq{>}) of its upstream, and if they
229 have diverged (@qq{<>}) or they are synced (@qq{=}).
231 You may need to install the additional @code{bash-completion}
232 package, but it is definitely worth it. After installation
233 you must log out, and then log back in again to enable it.
236 @subsubheading Technical details
238 Git stores the information entered with
239 @command{git@tie{}config@tie{}--global} in the file
240 @file{.gitconfig}, located in your home directory. This file can
241 also be modified directly, without using
242 @command{git@tie{}config}. The @file{.gitconfig} file generated
243 by the above commands would look like this:
248 email = john@@example.com
255 Using the @command{git@tie{}config} command @emph{without} the
256 @option{--global} option configures repository-specific settings,
257 which are stored in the file @file{.git/config}. This file is
258 created when a repository is initialized (using
259 @command{git@tie{}init}), and by default contains these lines:
263 repositoryformatversion = 0
266 logallrefupdates = true
269 However, since different repository-specific options are
270 recommended for different development tasks, it is best to avoid
271 setting any now. Specific recommendations will be mentioned later
275 @node Git for the impatient
276 @subsection Git for the impatient
278 @advanced{The intent of this subsection is to get you working on lilypond as
279 soon as possible. If you want to learn about git, go read
280 @ref{Other Git documentation}.
282 Also, these instructions are designed to eliminate the most common
283 problems we have found in using git. If you already know git and
284 have a different way of working, great! Feel free to ignore the
285 advice in this subsection.}
288 Ok, so you've been using @command{lily-git.tcl} for a while, but
289 it's time to take the next step. Since our review process delays
290 patches by 60-120 hours, and you want to be able to work on other
291 stuff while your previous work is getting reviewed, you're going
292 to use @strong{branches}.
294 You can think of a branch as being a separate copy of the source
295 code. But don't worry about it.
297 @subsubheading Start work: make a new branch
299 Let's pretend you want to add a section to the Contributor's Guide
300 about using branches.
302 Start by updating the repository, then making a new branch. Call
303 the branch anything you want as long as the name starts with
304 @code{dev/}. Branch names that don't begin with @code{dev/} are
305 reserved for special things in lilypond.
309 git pull -r origin master
313 @subsubheading Switch to that branch
315 Nothing has happened to the files yet. Let's change into the new
316 branch. You can think of this as @qq{loading a file}, although in
317 this case it's really @qq{loading a directory and subdirectories
324 Your prompt now shows you that you're on the other branch:
327 gperciva@@LilyDev:~/lilypond-git (dev/cg)$
330 To be able to manage multiple lilypond issues at once, you'll need to switch
331 branches. You should have each lilypond issue on a separate branch.
332 Switching branches is easy:
336 git checkout origin/staging
337 git checkout origin/release/unstable
341 Branches that begin with @code{origin/} are part of the remote repository,
342 rather than your local repository, so when you check them out you get a
343 temporary local branch. You should never make changes directly on a
344 branch beginning with @code{origin/}. You get changes into the remote
345 repository by making them in local branches, and then pushing them to
346 @code{origin/staging} as described below.
348 @subsubheading Make your changes
350 Edit files, then commit them.
357 Remember how I said that switching to a branch was like
358 @qq{loading a directory}? Well, you've just @qq{saved a
359 directory}, so that you can @qq{load} it later.
361 @advanced{If you have used @command{cvs} or @command{svn}, you may
362 be very confused: those programs use @qq{commit} to mean
363 @qq{upload my changes to the shared source repository}.
364 Unfortunately, just to be different, @w{@command{git commit}}
365 means @qq{save my changes to the files}.}
367 When you create a new file, you need to add it to git, then commit it:
370 git add input/regression/avoid-crash-on-condition.ly
375 Edit more files. Commit them again. Edit yet more files, commit
376 them again. Go eat dinner. Switch to @code{master} so you can
377 play with the latest changes from other developers. Switch back
378 to your branch and edit some more. Commit those changes.
380 At this stage, don't worry about how many commits you have.
383 @subsubheading Save commits to external files
385 Branches are nerve-wracking until you get used to them. You can
386 save your hard work as individual @file{.patch} files. Be sure to
387 commit your changes first.
391 git format-patch master
394 I personally have between 4 and 20 of those files saved in a
395 special folder at any point in time. Git experts might laugh as
396 that behavior, but I feel a @emph{lot} better knowing that I've
400 @subsubheading Prepare your branch for review
402 After committing, you can update your branch with the latest master:
407 git pull -r origin master
413 Due to the speed of lilypond development, sometimes
414 @code{master} has changed so much that your branch can no
415 longer be applied to it. In that happens, you will have a merge
416 conflict. Stop for a moment to either cry or have a stiff drink,
417 then proceed to @ref{Merge conflicts}.
420 @subsubheading Upload your branch
422 Finally, you're finished your changes. Time to upload for review.
423 Make sure that you're on your branch, then upload:
431 @subsubheading Wait for reviews
433 While you're waiting for a countdown and reviews, go back to
434 master, make a @code{dev/doc-beams} branch, and start adding doc
435 suggestions from issue 12345 from the tracker. Or make a
436 @code{dev/page-breaks} and fix bug in page breaking. Or whatever.
437 Don't worry, your @code{dev/cg} is safe.
440 @subsubheading Combining commits (optional unless you have broken commits)
442 Does the history of your branch look good?
448 If you have a lot of commits on your branch, you might want to
449 combine some of them. Alternately, you may like your commits, but
450 want to edit the commit messages.
456 Follow instructions on the screen.
458 @warning{This step gives you the power to completely lose your
459 work. Make a backup of your commits by saving them to
460 @file{.patch} files before playing with this. If you do lose
461 your work, don't despair. You can get it back by using @code{git reflog}.
462 The use of @code{git reflog} is not covered here.}
464 @warning{If any of the commits on your branch represent partial work that will
465 not pass @var{make && make doc}, you @strong{must} squash these
466 commits into a working commit. Otherwise, your push will break staging
467 and will not be able to be merged to master. In general, you will
468 be safer to have one commit per push.}
471 @subsubheading Push to staging
473 When you've got the coveted @code{Patch-push} status, time to
478 git rebase origin/staging dev/cg~0
482 @warning{Do not skip the @command{gitk} step; a quick 5-second
483 check of the visual history can save a great deal of frustration
484 later on. You should see a set of your commits that are ahead of
485 @code{origin/staging}, with no label for the top commit -- only a
488 @warning{If @code{origin/staging} and @code{origin/master} are the
489 same commit, your branch (@code{dev/cg} in the example) will also
490 be at the top of the @code{gitk} tree. This is normal.}
492 If everything looks good, push it:
495 git push origin HEAD:staging
498 Then change back to your working branch:
504 @warning{It is a best practice to avoid rebasing any of your branches
505 to @code{origin/staging}. If @code{origin/staging} is broken, it
506 will be deleted and rebuilt. If you have rebased one of your branches
507 to @code{origin/staging}, the broken commits can end up in your branch.
508 The commands given above do the rebase on a temporary branch, and avoid
509 changing your working branch.}
512 @subsubheading Delete your branch (safe)
514 After a few hours, if there's nothing wrong with your branch, it
515 should be automatically moved to @code{origin/master}. Update,
516 then try removing your branch:
520 git pull -r origin master
524 The last command will fail if the contents of @code{dev/cg} are
525 not present in @code{origin/master}.
528 @subsubheading Delete your branch (UNSAFE)
530 @c don't give explicit commands here -- this is too dangerous to copy and paste
531 Sometimes everything goes wrong. If you want to remove a branch even though
532 it will cause your work to be lost (that is, if the contents of @code{dev/cg}
533 are @strong{not} present in master), follow the instructions in @qq{Delete
534 your branch (safe)}, but replace the @code{-d} on the final line with
538 @node Other repositories
539 @subsection Other repositories
541 We have a few other code repositories.
545 * Grand Unified Builder (GUB)::
547 * yet more repositories::
551 @unnumberedsubsubsec lilypond-extra
553 There is a separate repository for general administrative scripts,
554 as well as pictures and media files for the website. People
555 interested in working on the website should download this
556 repository, and set their @code{$LILYPOND_WEB_MEDIA_GIT}
557 environment variable to point to that repository.
560 @uref{https://github.com/gperciva/lilypond-extra}
563 To configure an environment variable in bash (the default for most
564 GNU/Linux distributions),
567 export LILYPOND_WEB_MEDIA_GIT=$HOME/dir/of/lilypond-extra/
570 Be aware that @code{lilypond-extra} is the definitive source for some binary
571 files - in particular PDF versions of papers concerning LilyPond. To add
572 further PDFs of this sort, all that is necessary is to add the PDF to
573 @code{lilypond-extra} and then add a reference to it in the documentation. The
574 file will then be copied to the website when @code{make website} is run.
576 However, pictures that are also used in the documentation build are mastered in
577 the main git repository. If any of these is changed, it should be updated in
578 git, and then the updates copied to @code{lilypond-extra}.
580 @node Grand Unified Builder (GUB)
581 @unnumberedsubsubsec Grand Unified Builder (GUB)
583 Another item of interest might be the Grand Unified Builder, our
584 cross-platform building tool. Since it is used by other projects as
585 well, it is not stored in our gub repository. For more info, see
586 @uref{http://lilypond.org/gub}.
588 There are two locations for this repository: the version being used to
589 build lilypond, which is at
592 @uref{http://github.com/gperciva/gub}
595 and the original version by Jan Nieuwenhuizen, kept at
598 @uref{http://github.com/janneke/gub}
603 @unnumberedsubsubsec LilyPad
605 Our binary releases on MacOS X and Windows contain a lightweight
608 To make any modifications the Windows editor, you will need to do the
613 Clone the git repository from @code{https://github.com/gperciva/lilypad}
616 Make changes to the source, and check it compiles. In a Windows environment
617 @code{MinGW} provides both a @code{Git} installation and a @code{gcc}
618 compiler. This can be obtained from @code{http://www.mingw.org/}
621 Update the version which is contained in the @file{rsrc.rc}. Check
625 Commit the changes with an informative commit message.
628 Push the changes to github. You will need to use syntax similiar to this:
631 git push https://UserName@@github.com/gperciva/lilypad.git
634 You will need to have push access to the git repository for this to be
638 Make a tarball of the source code to be used by GUB by pulling the updated
639 repository from GitHub. Ensure that the tarball has the correct Version
643 Copy the tarball to @code{http://lilypond.org/downloads/gub-sources/lilypad/}.
644 You will need to have SSH access to @code{lilypond.org}. If you do not, contact
645 the Release Manager via the lilypond-devel mailing list.
648 Update GUB to make it use the new tarball by editing
649 @file{gub/specs/lilypad.py} and changing the @code{source =} line to point to
653 Push this updated @file{lilypad.py} version to the GUB repository on GitHub.
656 Test the changes with a new GUB compile.
660 @node yet more repositories
661 @unnumberedsubsubsec yet more repositories
663 There are a few other repositories floating around, which will
664 hopefully be documented in the near future.
667 @node Downloading remote branches
668 @subsection Downloading remote branches
670 @warning{contains obsolete + misleading info}
673 * Organization of remote branches::
674 * LilyPond repository sources::
675 * Downloading individual branches::
676 * Downloading all remote branches::
681 @node Organization of remote branches
682 @unnumberedsubsubsec Organization of remote branches
685 The main LilyPond repository is organized into @emph{branches} to
686 facilitate development. These are often called @emph{remote}
687 branches to distinguish them from @emph{local} branches you might
688 create yourself (see @ref{Using local branches}).
690 The @code{master} branch contains all the source files used to
691 build LilyPond, which includes the program itself (both stable and
692 development releases), the documentation (and its translations),
693 and the website. Generally, the @code{master} branch is expected
694 to compile successfully.
696 The @code{translation} branch is a side branch that
697 allows translators to work without needing to worry about
698 compilation problems. Periodically, the Translation Meister
699 (after verifying that it doesn't break compilation), will
700 @emph{merge} this branch into @code{staging} to incorporate
701 recent translations. Similarly, the @code{master} branch is
702 usually merged into the @code{translation} branch after
703 significant changes to the English documentation. See
704 @ref{Translating the documentation} for details.
707 @node LilyPond repository sources
708 @unnumberedsubsubsec LilyPond repository sources
711 The recommended source for downloading a copy of the main
715 git://git.sv.gnu.org/lilypond.git
718 However, if your internet router filters out connections using the
719 GIT protocol, or if you experience difficulty connecting via GIT,
720 you can try these other sources:
723 ssh://git.sv.gnu.org/srv/git/lilypond.git
724 http://git.sv.gnu.org/r/lilypond.git
727 The SSH protocol can only be used if your system is properly set
728 up to use it. Also, the HTTP protocol is slowest, so it should
729 only be used as a last resort.
732 @node Downloading individual branches
733 @unnumberedsubsubsec Downloading individual branches
735 @warning{obsolete, should be deleted!}
738 Once you have initialized an empty Git repository on your system
739 (see @ref{Initializing a repository}), you can download a remote
740 branch into it. Make sure you know which branch you want to start
743 To download the @code{master} branch, enter the following:
746 git remote add -ft master -m master \
747 origin git://git.sv.gnu.org/lilypond.git/
750 To download the @code{translation} branch, enter:
753 git remote add -ft translation -m \
754 translation origin git://git.sv.gnu.org/lilypond.git/
757 The @command{git@tie{}remote@tie{}add} process could take up to
758 ten minutes, depending on the speed of your connection. The
759 output will be something like this:
763 remote: Counting objects: 235967, done.
764 remote: Compressing objects: 100% (42721/42721), done.
765 remote: Total 235967 (delta 195098), reused 233311 (delta 192772)
766 Receiving objects: 100% (235967/235967), 68.37 MiB | 479 KiB/s, done.
767 Resolving deltas: 100% (195098/195098), done.
768 From git://git.sv.gnu.org/lilypond
769 * [new branch] master -> origin/master
770 From git://git.sv.gnu.org/lilypond
771 * [new tag] flower/1.0.1 -> flower/1.0.1
772 * [new tag] flower/1.0.10 -> flower/1.0.10
774 * [new tag] release/2.9.6 -> release/2.9.6
775 * [new tag] release/2.9.7 -> release/2.9.7
778 When @command{git@tie{}remote@tie{}add} is finished, the remote
779 branch should be downloaded into your repository---though not yet
780 in a form that you can use. In order to browse the source code
781 files, you need to @emph{create} and @emph{checkout} your own
782 local branch. In this case, however, it is easier to have Git
783 create the branch automatically by using the @command{checkout}
784 command on a non-existent branch. Enter the following:
787 git checkout -b @var{branch} origin/@var{branch}
791 where @code{@var{branch}} is the name of your tracking branch,
792 either @code{master} or @code{translation}.
794 Git will issue some warnings; this is normal:
797 warning: You appear to be on a branch yet to be born.
798 warning: Forcing checkout of origin/master.
799 Branch master set up to track remote branch master from origin.
803 By now the source files should be accessible---you should be able
804 to edit any files in the @file{$LILYPOND_GIT} directory using a
805 text editor of your choice. But don't start just yet! Before
806 editing any source files, learn how to keep your changes organized
807 and prevent problems later---read @ref{Basic Git procedures}.
809 @subsubheading Technical Details
811 The @command{git@tie{}remote@tie{}add} command should add some
812 lines to your local repository's @file{.git/config} file:
816 url = git://git.sv.gnu.org/lilypond.git/
817 fetch = +refs/heads/master:refs/remotes/origin/master
821 @node Downloading all remote branches
822 @unnumberedsubsubsec Downloading all remote branches
825 To download all remote branches at once, you can @command{clone}
826 the entire repository:
829 git clone git://git.sv.gnu.org/lilypond.git
834 @unnumberedsubsubsec Other branches
836 Most contributors will never need to touch the other branches. If
837 you wish to do so, you will need more familiarity with Git; please
838 see @ref{Other Git documentation}.
841 @item @code{dev/XYZ}:
842 These branches are for individual developers. They store code
843 which is not yet stable enough to be added to the @code{master}
846 @item @code{stable/XYZ}:
847 The branches are kept for archival reasons.
849 @item @code{archive/XYZ}:
850 The branches are kept for archival reasons.
855 @node Basic Git procedures
856 @section Basic Git procedures
860 * The Git contributor's cycle::
861 * Pulling and rebasing::
862 * Using local branches::
865 * Uploading a patch for review::
866 * The patch review cycle::
870 @node The Git contributor's cycle
871 @subsection The Git contributor's cycle
874 Here is a simplified view of the contribution process on Git:
878 Update your local repository by @emph{pulling} the most recent
879 updates from the remote repository.
882 Edit source files within your local repository's @emph{working
886 @emph{Commit} the changes you've made to a local @emph{branch}.
889 Generate a @emph{patch} to share your changes with the developers.
893 @node Pulling and rebasing
894 @subsection Pulling and rebasing
897 When developers push new patches to the @code{git.sv.gnu.org}
898 repository, your local repository is @strong{not} automatically
899 updated. It is important to keep your repository up-to-date by
900 periodically @emph{pulling} the most recent @emph{commits} from
901 the remote branch. Developers expect patches to be as current as
902 possible, since outdated patches require extra work before they
905 Occasionally you may need to rework some of your own modifications
906 to match changes made to the remote branch (see @ref{Resolving
907 conflicts}), and it's considerably easier to rework things
908 incrementally. If you don't update your repository along the way,
909 you may have to spend a lot of time resolving branch conflicts and
910 reconfiguring much of the work you've already done.
912 Fortunately, Git is able to resolve certain types of branch
913 conflicts automatically with a process called @emph{rebasing}.
914 When rebasing, Git tries to modify your old commits so they appear
915 as new commits (based on the latest updates). For a more involved
916 explanation, see the @command{git-rebase} man page.
918 To pull without rebasing (recommended for translators), use the
922 git pull # recommended for translators
925 If you're tracking the remote @code{master} branch, you should add
926 the @option{-r} option (short for @option{--rebase}) to keep commits
927 on your local branch current:
930 git pull -r # use with caution when translating
933 If you don't edit translated documentation and don't want to type
934 @option{-r} every time, configure the master branch to rebase by
935 default with this command:
938 git config branch.master.rebase true
941 If pull fails because of a message like
944 error: Your local changes to 'Documentation/learning/tutorial.itely'
945 would be overwritten by merge. Aborting.
952 Documentation/learning/tutorial.itely: needs update
953 refusing to pull with rebase: your working tree is not up-to-date
957 it means that you have modified some files in you working tree
958 without committing changes (see @ref{Commits}); you
959 can use the @command{git@tie{}stash} command to work around this:
962 git stash # save uncommitted changes
963 git pull -r # pull using rebase (translators omit "-r")
964 git stash pop # reapply previously saved changes
967 Note that @command{git@tie{}stash@tie{}pop} will try to apply a
968 patch, and this may create a conflict. If this happens, see
969 @ref{Resolving conflicts}.
971 TODO: I think the next paragraph is confusing. Perhaps prepare
972 the reader for new terms `committish' and `head'? -mp
974 @warning{translators and documentation editors, if you have
975 changed committishes in the head of translated files using commits
976 you have not yet pushed to @code{git.sv.gnu.org}, please do not
977 rebase. If you want to avoid wondering whether you should rebase
978 each time you pull, please always use committishes from master
979 and/or translation branch on @code{git.sv.gnu.org}, which
980 in particular implies that you must push your changes to
981 documentation except committishes updates (possibly after having
982 rebased), then update the committishes and push them.}
984 TODO: when committishes automatic conditional update have been
985 tested and documented, append the following to the warning above:
986 Note that using update-committishes make target generally touches
989 @subsubheading Technical details
991 The @command{git@tie{}config} command mentioned above adds the
992 line @code{rebase = true} to the master branch in your local
993 repository's @file{.git/config} file:
998 merge = refs/heads/master
1003 @node Using local branches
1004 @subsection Using local branches
1008 * Creating and removing branches::
1009 * Listing branches and remotes::
1010 * Checking out branches::
1011 * Merging branches::
1015 @node Creating and removing branches
1016 @unnumberedsubsubsec Creating and removing branches
1019 Local branches are useful when you're working on several different
1020 projects concurrently. To create a new branch, enter:
1023 git branch @var{name}
1026 To delete a branch, enter:
1029 git branch -d @var{name}
1032 Git will ask you for confirmation if it sees that data would be
1033 lost by deleting the branch. Use @option{-D} instead of @option{-d}
1034 to bypass this. Note that you cannot delete a branch if it is
1035 currently checked out.
1038 @node Listing branches and remotes
1039 @unnumberedsubsubsec Listing branches and remotes
1041 You can get the exact path or URL of all remote branches by
1048 To list Git branches on your local repositories, run
1051 git branch # list local branches only
1052 git branch -r # list remote branches
1053 git branch -a # list all branches
1057 @node Checking out branches
1058 @unnumberedsubsubsec Checking out branches
1060 To know the currently checked out branch, i.e. the branch whose
1061 source files are present in your working tree, read the first line
1069 The currently checked out branch is also marked with an asterisk
1070 in the output of @command{git branch}.
1072 You can check out another branch @code{@var{other_branch}}, i.e.
1073 check out @code{@var{other_branch}} to the working tree, by
1077 git checkout @var{other_branch}
1080 Note that it is possible to check out another branch while having
1081 uncommitted changes, but it is not recommended unless you know
1082 what you are doing; it is recommended to run @command{git status}
1083 to check this kind of issue before checking out another branch.
1085 @node Merging branches
1086 @unnumberedsubsubsec Merging branches
1088 To merge branch @code{@var{foo}} into branch @code{@var{bar}},
1089 i.e. to @qq{add} all changes made in branch @code{@var{foo}} to
1090 branch @code{@var{bar}}, run
1093 git checkout @var{bar}
1097 If any conflict happens, see @ref{Resolving conflicts}.
1099 There are common usage cases for merging: as a translator, you will
1100 often want the Translations meister to merge @code{master} into
1101 @code{translation}; on the other hand, the Translations meister wants
1102 to merge @code{translation} into @code{staging} whenever he has
1103 checked that @code{translation} builds successfully.
1110 * Understanding commits::
1111 * How to make a commit::
1116 @node Understanding commits
1117 @unnumberedsubsubsec Understanding commits
1119 Technically, a @emph{commit} is a single point in the history of a
1120 branch, but most developers use the term to mean a @emph{commit
1121 object}, which stores information about a particular revision. A
1122 single commit can record changes to multiple source files, and
1123 typically represents one logical set of related changes (such as a
1124 bug-fix). You can list the ten most recent commits in your
1125 current branch with this command:
1128 git log -10 --oneline
1131 If you're using an older version of Git and get an @q{unrecognized
1132 argument} error, use this instead:
1135 git log -10 --pretty=oneline --abbrev-commit
1138 More interactive lists of the commits on the remote @code{master}
1139 branch are available at
1140 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=shortlog} and
1141 @uref{http://git.sv.gnu.org/cgit/lilypond.git/log/}.
1144 @node How to make a commit
1145 @unnumberedsubsubsec How to make a commit
1148 Once you have modified some source files in your working
1149 directory, you can make a commit with the following procedure:
1153 Make sure you've configured Git properly (see @ref{Configuring
1154 Git}). Check that your changes meet the requirements described in
1155 @ref{Code style} and/or @ref{Documentation policy}. For advanced
1156 edits, you may also want to verify that the changes don't break
1157 the compilation process.
1160 Run the following command:
1167 to make sure you're on the right branch, and to see which files
1168 have been modified, added or removed, etc. You may need to tell
1169 Git about any files you've added by running one of these:
1172 git add @var{file} # add untracked @var{file} individually
1173 git add . # add all untracked files in current directory
1177 After @command{git@tie{}add}, run @command{git@tie{}status} again
1178 to make sure you got everything. You may also need to modify
1182 Preview the changes about to be committed (to make sure everything
1190 The @code{HEAD} argument refers to the most recent commit on the
1191 currently checked-out branch.
1194 Generate the commit with:
1201 The @option{-a} is short for @option{--all} which includes modified
1202 and deleted files, but only those newly created files that have
1203 previously been added.
1208 @node Commit messages
1209 @unnumberedsubsubsec Commit messages
1212 When you run the @command{git@tie{}commit@tie{}-a} command, Git
1213 automatically opens the default text editor so you can enter a
1214 @emph{commit message}. If you find yourself in a foreign editing
1215 environment, you're probably in @command{vi} or @command{vim}. If
1216 you want to switch to an editor you're more familiar with, quit by
1217 typing @code{:q!} and pressing @code{<Enter>}. See
1218 @ref{Configuring Git} for instructions on changing the default
1221 In any case, Git will open a text file for your commit message
1222 that looks like this:
1226 # Please enter the commit message for your changes. Lines starting
1227 # with '#' will be ignored, and an empty message aborts the commit.
1229 # Changes to be committed:
1230 # (use "git reset HEAD <file>..." to unstage)
1232 # modified: working.itexi
1236 Your commit message should begin with a one-line summary
1237 describing the change (no more than 50 characters long), and if
1238 necessary a blank line followed by several lines giving the
1241 @c $ git log -1 --pretty=medium 4d6f1e5
1243 Doc: add Baerenreiter and Henle solo cello suites
1245 Added comparison of solo cello suite engravings to new essay with
1246 high-res images, fixed cropping on Finale example.
1249 Commit messages often start with a short prefix describing the
1250 general location of the changes.
1254 Doc: and Doc-@var{**}: If a commit affects the
1255 documentation in English (or in several languages simultaneously)
1256 the commit message should be prefixed with @qq{Doc:@tie{}}. If the
1257 commit affects only one of the translations, the commit
1258 message should be prefixed with @qq{Doc-@var{**}:@tie{}}, where
1259 @var{**} is the two-letter language code.
1262 Web: and Web-@var{**}: Commits that affect the
1263 website should use @qq{Web:@tie{}} for English, and
1264 @qq{Web-@var{**}:@tie{}} for other languages.
1267 CSS: Commits that change CSS files should use @qq{Web:@tie{}CSS:@tie{}}
1268 or @qq{Doc:@tie{}CSS:@tie{}} depending on whether they affect the
1269 website or the documentation/manuals.
1272 Changes to a single file are often prefixed with the name of the file
1276 Visit the links listed in @ref{Understanding commits} for examples.
1284 * How to make a patch::
1285 * Emailing patches::
1288 @node How to make a patch
1289 @unnumberedsubsubsec How to make a patch
1291 If you want to share your changes with other contributors and
1292 developers, you need to generate @emph{patches} from your commits.
1293 We prefer it if you follow the instructions in
1294 @ref{Uploading a patch for review}. However, we present an
1295 alternate method here.
1297 You should always run @command{git@tie{}pull@tie{}-r} (translators
1298 should leave off the @option{-r}) before doing this to ensure that
1299 your patches are as current as possible.
1301 Once you have made one or more commits in your local repository,
1302 and pulled the most recent commits from the remote branch, you can
1303 generate patches from your local commits with the command:
1306 git format-patch origin
1309 The @code{origin} argument refers to the remote tracking branch at
1310 @code{git.sv.gnu.org}. This command generates a separate patch
1311 for each commit that's in the current branch but not in the remote
1312 branch. Patches are placed in the current working directory and
1313 will have names that look something like this:
1316 0001-Doc-Fix-typos.patch
1317 0002-Web-Remove-dead-links.patch
1321 Send an email (must be less than 64 KB) to
1322 @email{lilypond-devel@@gnu.org} briefly explaining your work, with
1323 the patch files attached. Translators should send patches to
1324 @email{translations@@lilynet.net}. After your patches are
1325 reviewed, the developers may push one or more of them to the main
1326 repository or discuss them with you.
1329 @node Emailing patches
1330 @unnumberedsubsubsec Emailing patches
1332 The default @code{x-diff} MIME type associated with patch files
1333 (i.e., files whose name ends in @code{.patch}) means that the
1334 encoding of line endings may be changed from UNIX to DOS format
1335 when they are sent as attachments. Attempting to apply such an
1336 inadvertently altered patch will cause git to fail with a message
1337 about @q{whitespace errors}.
1339 The solution to such problems is surprisingly simple---just change
1340 the default file extension of patches generated by git to end in
1341 @code{.txt}, for example:
1344 git config format.suffix '.patch.txt'
1347 This should cause email programs to apply the correct base64
1348 encoding to attached patches.
1350 If you receive a patch with DOS instead of UNIX line-endings, it
1351 can be converted back using the @code{dos2unix} utility.
1353 Lots of useful information on email complications with patches is
1354 provided on the Wine wiki at
1355 @uref{http://wiki.winehq.org/GitWine}.
1358 @node Uploading a patch for review
1359 @subsection Uploading a patch for review
1361 Any non-trivial change should be uploaded to our @qq{Rietveld}
1362 code review website:
1365 @uref{http://codereview.appspot.com/}
1368 You can upload a patch for review by using our custom @code{git-cl}
1369 @q{helper-script}. This section assumes you have already installed,
1370 updated, and configured @code{git-cl}. See @ref{git-cl}.
1372 @warning{Unless you are familiar with branches, only work on one
1373 set of changes at once.}
1375 There are two methods, depending on your git setup.
1379 @strong{Master branch}: (easy option)
1381 If you added your patch to @code{master}, then:
1385 git-cl upload origin/master
1388 @c Mention staging here?
1389 If you have git push ability, make sure that you @emph{remove}
1390 your patch (with @command{git rebase} or @command{git reset})
1391 before pushing other stuff.
1393 @c don't make this one an @example; we don't want to make it easy
1394 @c for people to use this accidently
1395 Notifications of patches are automatically added to our issue
1396 tracker to reduce the chance of patches getting lost. To suppress
1397 this (not recommended), add the @code{-n / --no-code-issue}
1401 @strong{Separate branch}: (complicated option)
1403 Ensure your changes are committed in a separate branch, which should
1404 differ from the reference branch to be used (usually
1405 @code{origin/master}) by just the changes to be uploaded. Checkout the
1406 branch with the changes:
1409 git checkout some-branch-with-changes
1412 If the reference branch is to be @code{origin/master}, ensure that the
1413 branch containing the changes is up-to-date with it. Use
1414 @command{git rebase} or @command{git pull -r} to rebase the branch to
1415 the head of @code{origin/master}. For example:
1418 git pull -r origin master
1421 Finally, start the upload by entering:
1424 git-cl upload <reference SHA1 ID>
1428 where <reference SHA1 ID> is the SHA1 ID of the commit to be used
1429 as a reference source for the patch. Generally, this will be the
1430 SHA1 ID of origin/master, and in that case you can just use the command:
1433 git-cl upload origin/master
1438 First you will see a terminal editor where you can edit the
1439 message that will accompany your patch. @command{git-cl} will
1440 respect the @env{EDITOR} environment variable if defined,
1441 otherwise it will use @command{vi} as the default editor.
1443 After prompting for your Google email address and password, the
1444 patch set will be posted to Rietveld, and you will be given a URL
1447 @warning{Some installations of git-cl fail when uploading a patch
1448 with certain filename extensions. If this happens, it can
1449 generally be fixed by editing the list of exceptions at top of
1452 @subsubheading Announcing your patch set
1454 You should then announce the patch by logging into the code review
1455 issue webpage and using @qq{Publish + Mail Comments} to add a
1456 (mostly bogus) comment to your issue. The text of your comment
1457 will be sent to our developer mailing list.
1459 @warning{There is no automatic notification of a new patch; you
1460 must add a comment yourself.}
1462 @subsubheading Revisions
1464 As revisions are made in response to comments, successive patch sets
1465 for the same issue can be uploaded by reissuing the git-cl command
1466 with the modified branch checked out.
1468 Sometimes in response to comments on revisions, the best way to
1469 work may require creation of a new branch in git. In order to
1470 associate the new branch with an existing Rietveld issue,
1471 the following command can be used:
1474 git-cl issue issue-number
1478 where @code{issue-number} is the number of the existing Rietveld
1481 @subsubheading Resetting git-cl
1483 If @command{git-cl} becomes confused, you can @qq{reset} it by
1491 @node The patch review cycle
1492 @subsection The patch review cycle
1494 Your patch will be available for reviews for the next few hours or
1495 days. Three times a week, patches with no known problems are
1496 gathered into a @qq{patch countdown} and their status changed to
1497 @code{patch-countdown}. The countdown is a 48-hour waiting period
1498 in which any final reviews or complaints should be made.
1500 During the countdown, your patch may be set to
1501 @code{patch-needs_work}, indicating that you should fix something
1502 (or at least discuss why the patch needs no modification). If no
1503 problems are found, the patch will be set to @code{patch-push}.
1505 Once a patch has @code{patch-push}, it should be sent to your
1506 mentor for uploading. If you have git push ability, look at
1507 @ref{Pushing to staging}.
1512 Patches get added to the tracker and to Rietveld by the @qq{git-cl} tool, with
1513 a status of @qq{patch-new}.
1516 The automated tester, Patchy, verifies that the patch can be applied
1517 to current master. By default, it checks that the patch allows @code{make}
1518 and @code{make test} to complete successfully. It can also be configured to
1519 check that @code{make doc} is successful. If it passes, Patchy changes the
1520 status to @qq{patch-review} and emails the developer list. If the patch
1521 fails, Patchy sets it to @qq{patch-needs_work} and notifies the developer list.
1524 The Patch Meister reviews the tracker periodically, to list patches
1525 which have been on review for at least 24 hours. The list is found at
1528 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch%20patch=review&sort=modified+patch&colspec=ID%20Type%20Status%20Priority%20Owner%20Patch%20Summary%20Modified}
1532 For each patch, the Handler reviews any discussion on the tracker
1533 and on Rietveld, to determine whether the patch can go forward. If
1534 there is any indication that a developer thinks the patch is not
1535 ready, the Handler marks it @qq{patch-needs_work} and makes a comment
1536 regarding the reason, referring to the Rietveld item if needed.
1539 Patches with explicit approval, or at least no negative comment, can
1540 be updated to @qq{patch-countdown}. When saving the tracker item,
1541 clear the @qq{send email} box to prevent sending notification for
1545 The Patch Meister sends an email to the developer list, with a fixed
1546 subject line, to enable filtering by email clients:
1549 PATCH: Countdown to 20130113
1552 The text of the email sets the deadline for this countdown batch. At
1553 present, batches are done on Tuesday, Thursday and Sunday evenings.
1555 To create the countdown announcement, use the
1556 @code{make-countdown-announcement.sh} script, which takes the
1557 deadline date, and optionally your name. Follow the instructions
1562 scripts/auxiliar/make-countdown-announcement.sh "Jan 1, 2001" James
1565 The script produces an announcement that is easily readable in all
1566 email clients. Also, whenever a new contributor submits a patch,
1567 you will be prompted to add the new username and author name to
1568 the script itself, and then commit those changes to the main git
1573 On the scheduled countdown day, the Patch Meister reviews the
1574 previous list of patches on countdown, with the same procedure and
1575 criteria as before. Patches with no controversy can be set to
1576 @qq{patch-push} with a courtesy message added to the comment block.
1579 Roughly at six month intervals, the Patch Meister can list the
1580 patches which have been set to @qq{patch-needs-work} and send the
1581 results to the developer list for review. In most cases, these
1582 patches should be marked @qq{patch-abandoned} but this should come
1583 from the developer if possible.
1586 As in most organisations of unpaid volunteers, fixed procedures are
1587 useful in as much as they get the job done. In our community, there
1588 is room for senior developers to bypass normal patch handling flows,
1589 particularly now that the testing of patches is largely automated.
1590 Similarly, the minimum age of 24 hours can reasonably be waived if
1591 the patch is minor and from an experienced developer.
1597 There is a single Patch Meister, and a number of Patch Helpers
1598 (rename this?). The list of known patches awaiting review is:
1601 @uref{http://code.google.com/p/lilypond/issues/list?can=2&q=label:patch&sort=patch}
1605 @subheading Helpers: adding patches
1607 The primary duty is to add patches to the google tracker; we have
1608 a bad track record of losing patches in email. Patches generally
1609 come to the @code{lilypond-devel} mailing list, but are sometimes
1610 sent to @code{bug-lilypond}, @code{lilypond-users}, or
1611 @code{frogs} mailing list instead.
1615 Unless a patch is clearly in response to an existing issue, add a
1616 new issue with the @code{Patch-new} label and a link to the patch
1617 (either on the mailing list archives or the codereview url).
1619 Issue numbers are cheap; losing developers because they got fed up
1620 with us losing their hard work is expensive.
1623 @c if we enter patches immediately, I don't think this is relevant.
1626 Before adding a patch-reminder issue, do a quick check to see if
1627 it was pushed without sending any email. This can be checked for
1628 searching for relevant terms (from the patch subject or commit
1629 message) on the webgit page:
1632 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git}
1637 If the patch is clearly in response to an existing issue, then
1638 update that issue with the @code{Patch-new} label and a link to
1639 the patch (either on the mailing list archives or the codereview
1643 After adding the issue, please send a response email to the same
1644 group(s) that the initial patch was sent to.
1646 If the initial email was sent to multiple mailing lists (such as
1647 both @code{bugs} and @code{devel}), then reply to all those
1648 mailing lists as well. The email should contain a link to the
1649 issue you just added.
1653 @subheading Helpers: @code{Patch-review} label
1655 The secondary duty is to do make sure that every issue in the
1656 tracker with a @code{Patch-review} label has passed these
1661 Applies automatically to git master.
1663 It's ok to have offsets, but not conflicts.
1666 Regtest comparison looks ok; no unexpected changes.
1669 Descriptive subject line.
1671 Avoid subjects like @qq{fixes 123}; instead write @qq{Doc: discuss
1672 stacking-dir for BassFigureAlignment (fix 123)}.
1675 Compiles docs from scratch. Only check this if you have reason to
1676 suspect it might not work.
1681 Check code indentation and style. This should be easier post-GOP
1682 when we have a better-defined code style.
1687 @subheading Patch Meister
1689 The Patch Meister will:
1694 send @qq{countdown} emails to
1695 @code{lilypond-devel} when patches appear to be ready.
1698 send general requests to review patches, or even nasty requests to
1702 downgrade patches from @code{Patch-review} to
1703 @code{Patch-needs_work} as appropriate.
1706 downgrade patches from @code{Patch-needs_work} to
1707 @code{Patch-abandoned} if no actions have been taken in four
1715 @node Advanced Git procedures
1716 @section Advanced Git procedures
1719 @warning{This section is not necessary for normal contributors;
1720 these commands are presented for information for people interested
1721 in learning more about git.}
1723 It is possible to work with several branches on the same local Git
1724 repository; this is especially useful for translators who may have
1725 to deal with both @code{translation} and a stable branch,
1726 e.g. @code{stable/2.12}.
1728 Some Git commands are introduced first, then a workflow with
1729 several Git branches of LilyPond source code is presented.
1734 * Advanced Git concepts::
1735 * Resolving conflicts::
1736 * Reverting all local changes::
1737 * Working with remote branches::
1739 * Applying remote patches::
1740 * Cleaning up multiple patches::
1742 * Pushing to staging::
1746 @node Merge conflicts
1747 @subsection Merge conflicts
1749 To be filled in later, and/or moved to a different section. I
1750 just wanted to make sure that I had a stub ready somewhere.
1753 @node Advanced Git concepts
1754 @subsection Advanced Git concepts
1757 A bit of Git vocabulary will be explained below. The following is
1758 only introductory; for a better understanding of Git concepts, you
1759 may wish to read @ref{Other Git documentation}.
1761 The @code{git@tie{}pull@tie{}origin} command above is just a
1762 shortcut for this command:
1765 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
1769 where @code{@var{branch}} is typically @code{master} or
1770 @code{translation}; if you do not know or remember, see
1771 @ref{Downloading remote branches} to remember which commands you
1772 issued or which source code you wanted to get.
1774 A @emph{commit} is a set of changes made to the sources; it also
1775 includes the committish of the parent commit, the name and e-mail
1776 of the @emph{author} (the person who wrote the changes), the name
1777 and e-mail of the @emph{committer} (the person who brings these
1778 changes into the Git repository), and a commit message.
1780 A @emph{committish} is the SHA1 checksum of a commit, a number
1781 made of 40 hexadecimal digits, which acts as the internal unique
1782 identifier for this commit. To refer to a particular revision,
1783 don't use vague references like the (approximative) date, simply
1784 copy and paste the committish.
1786 A @emph{branch} is nothing more than a pointer to a particular
1787 commit, which is called the @emph{head} of the branch; when
1788 referring to a branch, one often actually thinks about its head
1789 and the ancestor commits of the head.
1791 Now we will explain the two last commands you used to get the
1792 source code from Git---see @ref{Downloading individual branches}.
1795 git remote add -ft @var{branch} -m @var{branch} \
1796 origin git://git.sv.gnu.org/lilypond.git/
1798 git checkout -b @var{branch} origin/@var{branch}
1801 The @command{git@tie{}remote} has created a branch called
1802 @code{origin/@var{branch}} in your local Git repository. As this
1803 branch is a copy of the remote branch web from git.sv.gnu.org
1804 LilyPond repository, it is called a @emph{remote branch}, and is
1805 meant to track the changes on the branch from git.sv.gnu.org: it
1806 will be updated every time you run
1807 @command{git@tie{}pull@tie{}origin} or
1808 @command{git@tie{}fetch@tie{}origin}.
1810 The @command{git@tie{}checkout} command has created a branch named
1811 @code{@var{branch}}. At the beginning, this branch is identical
1812 to @code{origin/@var{branch}}, but it will differ as soon as you
1813 make changes, e.g. adding newly translated pages or editing some
1814 documentation or code source file. Whenever you pull, you merge
1815 the changes from @code{origin/@var{branch}} and
1816 @code{@var{branch}} since the last pulling. If you do not have
1817 push (i.e. @qq{write}) access on git.sv.gnu.org, your
1818 @code{@var{branch}} will always differ from
1819 @code{origin/@var{branch}}. In this case, remember that other
1820 people working like you with the remote branch @code{@var{branch}}
1821 of git://git.sv.gnu.org/lilypond.git/ (called
1822 @code{origin/@var{branch}} on your local repository) know nothing
1823 about your own @code{@var{branch}}: this means that whenever you
1824 use a committish or make a patch, others expect you to take the
1825 latest commit of @code{origin/@var{branch}} as a reference.
1827 Finally, please remember to read the man page of every Git command
1828 you will find in this manual in case you want to discover
1829 alternate methods or just understand how it works.
1832 @node Resolving conflicts
1833 @subsection Resolving conflicts
1836 Occasionally an update may result in conflicts -- this happens
1837 when you and somebody else have modified the same part of the same
1838 file and git cannot figure out how to merge the two versions
1839 together. When this happens, you must manually merge the two
1842 If you need some documentation to understand and resolve
1843 conflicts, see paragraphs @emph{How conflicts are presented} and
1844 @emph{How to resolve conflicts} in @command{git merge} man page.
1846 If all else fails, you can follow the instructions in
1847 @ref{Reverting all local changes}. Be aware that this eliminates
1848 any changes you have made!
1851 @node Reverting all local changes
1852 @subsection Reverting all local changes
1854 Sometimes git will become hopelessly confused, and you just want
1855 to get back to a known, stable state. This command destroys any
1856 local changes you have made in the currently checked-out branch,
1857 but at least you get back to the current online version:
1860 git reset --hard origin/master
1864 @node Working with remote branches
1865 @subsection Working with remote branches
1868 @subsubheading Fetching new branches from git.sv.gnu.org
1870 To fetch and check out a new branch named @code{@var{branch}} on
1871 git.sv.gnu.org, run from top of the Git repository
1874 git config --add remote.origin.fetch \
1875 +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
1877 git checkout --track -b @var{branch} origin/@var{branch}
1880 After this, you can pull @code{@var{branch}} from git.sv.gnu.org
1887 Note that this command generally fetches all branches you added
1888 with @command{git@tie{}remote@tie{}add} (when you initialized the
1889 repository) or @command{git@tie{}config@tie{}--add}, i.e. it
1890 updates all remote branches from remote @code{origin}, then it
1891 merges the remote branch tracked by the current branch into the
1892 current branch. For example, if your current branch is
1893 @code{master}, @code{origin/master} will be merged into
1897 @subsubheading Local clones, or having several working trees
1899 If you play with several Git branches, e.g. @code{master},
1900 @code{translation}, @code{stable/2.12}), you may want to
1901 have one source and build tree for each branch; this is possible
1902 with subdirectories of your local Git repository, used as local
1903 cloned subrepositories. To create a local clone for the branch
1904 named @code{@var{branch}}, run
1907 git checkout @var{branch}
1908 git clone -lsn . @var{subdir}
1913 Note that @code{@var{subdir}} must be a directory name which does
1914 not already exist. In @code{@var{subdir}}, you can use all Git
1915 commands to browse revisions history, commit and uncommit changes;
1916 to update the cloned subrepository with changes made on the main
1917 repository, cd into @code{@var{subdir}} and run
1918 @command{git@tie{}pull}; to send changes made on the subrepository
1919 back to the main repository, run @command{git@tie{}push} from
1920 @code{@var{subdir}}. Note that only one branch (the currently
1921 checked out branch) is created in the subrepository by default; it
1922 is possible to have several branches in a subrepository and do
1923 usual operations (checkout, merge, create, delete...) on these
1924 branches, but this possibility is not detailed here.
1926 When you push @code{@var{branch}} from @code{@var{subdir}} to the
1927 main repository, and @code{@var{branch}} is checked out in the
1928 main repository, you must save uncommitted changes (see
1929 @command{git@tie{}stash}) and do
1930 @command{git@tie{}reset@tie{}--hard} in the main repository in
1931 order to apply pushed changes in the working tree of the main
1939 The commands above don't only bring you the latest version of the
1940 sources, but also the full history of revisions (revisions, also
1941 called commits, are changes made to the sources), stored in the
1942 @file{.git} directory. You can browse this history with
1945 git log # only shows the logs (author, committish and commit message)
1946 git log -p # also shows diffs
1947 gitk # shows history graphically
1950 @warning{The @code{gitk} command may require a separate
1951 @code{gitk} package, available in the appropriate distribution's
1955 @node Applying remote patches
1956 @subsection Applying remote patches
1959 TODO: Explain how to determine if a patch was created with
1960 @code{git@tie{}format-patch}.
1962 Well-formed git patches created with @code{git@tie{}format-patch}
1963 should be committed with the following command:
1969 Patches created without @code{git@tie{}format-patch} can be
1970 applied in two steps. The first step is to apply the patch to the
1971 working tree and the index:
1974 git apply --index @var{patch}
1978 The second step is to commit the changes and give credit to the
1979 author of the patch. This can be done with the following command:
1982 git commit --author="@var{John Smith} <@var{john@@example.com}>"
1985 Please note that using the @code{--index} option for patching is quite
1986 important here and @emph{cannot} reliably be replaced by using the
1987 @code{-a} option when committing: that would only commit files from the
1988 working tree that are already registered with git, so every file that
1989 the patch actually @emph{adds}, like a regtest for a fixed bug, would
1990 get lost. For the same reason, you should not use the git-independent
1991 @samp{patch} program for applying patches.
1995 @node Cleaning up multiple patches
1996 @subsection Cleaning up multiple patches
1998 If you have been developing on your own branch for a while, you
1999 may have more commmits than is really sensible. To revise your
2000 work and condense commits, use:
2003 git rebase origin/master
2004 git rebase -i origin/master
2007 @warning{Be a bit cautious -- if you completely remove commits
2008 during the interactive session, you will... err... completely
2009 remove those commits.}
2013 @subsection Commit access
2015 Most contributors are not able to commit patches directly to the
2016 main repository---only members of the LilyPond development team
2017 have @emph{commit access}. If you are a contributor and are
2018 interested in joining the development team, contact the Project
2019 Manager through the mailing list
2020 (@email{lilypond-devel@@gnu.org}). Generally, only contributors
2021 who have already provided a number of patches which have been
2022 pushed to the main repository will be considered for membership.
2024 If you have been approved by the Project Manager, use the
2025 following procedure to obtain commit access:
2029 If you don't already have one, set up a Savannah user account at
2030 @uref{https://savannah.gnu.org/account/register.php}. If your web
2031 browser responds with an @qq{untrusted connection} message when
2032 you visit the link, follow the steps for including the CAcert root
2033 certificate in your browser, given at
2034 @uref{http://savannah.gnu.org/tls/tutorial/}.
2036 @warning{Savannah will silently put your username in lower-case --
2037 do not try to use capital letters.}
2041 After registering, if you are not logged in automatically, login
2042 at @uref{https://savannah.gnu.org/account/login.php}---this should
2043 take you to your @qq{my} page
2044 (@uref{https://savannah.gnu.org/my/}).
2048 Click on the @qq{My Groups} link to access the @qq{My Group
2049 Membership} page. From there, find the @qq{Request for Inclusion}
2050 box and search for @qq{LilyPond}. Among the search results, check
2051 the box labeled @qq{GNU LilyPond Music Typesetter} and write a
2052 brief (required) message for the Project Manager (@qq{Hey it's
2053 me!} should be fine).
2055 Note that you will not have commit access until the Project
2056 Manager activates your membership. Once your membership is
2057 activated, LilyPond should appear under the heading @qq{Groups I'm
2058 Contributor of} on your @qq{My Group Membership} page.
2062 Generate an SSH @q{rsa} key pair. Enter the following at the
2069 When prompted for a location to save the key, press <ENTER> to
2070 accept the default location (@file{~/.ssh/id_rsa}).
2072 Next you are asked to enter an optional passphrase. On most
2073 systems, if you use a passphrase, you will likely be prompted for
2074 it every time you use @command{git@tie{}push} or
2075 @command{git@tie{}pull}. You may prefer this since it can protect
2076 you from your own mistakes (like pushing when you mean to pull),
2077 though you may find it tedious to keep re-entering it.
2079 You can change/enable/disable your passphrase at any time with:
2082 ssh-keygen -f ~/.ssh/id_rsa -p
2085 Note that the GNOME desktop has a feature which stores your
2086 passphrase for you for an entire GNOME session. If you use a
2087 passphrase to @qq{protect you from yourself}, you will want to
2088 disable this feature, since you'll only be prompted once. Run the
2089 following command, then logout of GNOME and log back in:
2092 gconftool-2 --set -t bool \
2093 /apps/gnome-keyring/daemon-components/ssh false
2096 After setting up your passphrase, your private key is saved as
2097 @file{~/.ssh/id_rsa} and your public key is saved as
2098 @file{~/.ssh/id_rsa.pub}.
2102 Register your public SSH @q{rsa} key with Savannah. From the
2103 @qq{My Account Configuration} page, click on @qq{Edit SSH Keys},
2104 then paste the contents of your @file{~/.ssh/id_rsa.pub} file into
2105 one of the @qq{Authorized keys} text fields, and click
2108 Savannah should respond with something like:
2111 Success: Key #1 seen Keys registered
2116 Configure Git to use the SSH protocol (instead of the GIT
2117 protocol). From your local Git repository, enter:
2120 git config remote.origin.url \
2121 ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
2125 replacing @var{user} with your Savannah username.
2129 After your membership has been activated and you've configured Git
2130 to use SSH, test the connection with:
2136 SSH should issue the following warning:
2139 The authenticity of host 'git.sv.gnu.org (140.186.70.72)' can't
2141 RSA key fingerprint is
2142 80:5a:b0:0c:ec:93:66:29:49:7e:04:2b:fd:ba:2c:d5.
2143 Are you sure you want to continue connecting (yes/no)?
2146 Make sure the RSA key fingerprint displayed matches the one above.
2147 If it doesn't, respond @qq{no} and check that you configured Git
2148 properly in the previous step. If it does match, respond
2149 @qq{yes}. SSH should then issue another warning:
2152 Warning: Permanently added 'git.sv.gnu.org,140.186.70.72' (RSA) to
2153 the list of known hosts.
2156 The list of known hosts is stored in the file
2157 @file{~/.ssh/known_hosts}.
2159 At this point, you are prompted for your passphrase if you have
2160 one, then Git will attempt a pull.
2162 If @command{git@tie{}pull@tie{}--verbose} fails, you should see
2163 error messages like these:
2166 Permission denied (publickey).
2167 fatal: The remote end hung up unexpectedly
2170 If you get the above error, you may have made a mistake when
2171 registering your SSH key at Savannah. If the key is properly
2172 registered, you probably just need to wait for the Savannah server
2173 to activate it. It usually takes a few minutes for the key to be
2174 active after registering it, but if it still doesn't work after an
2175 hour, ask for help on the mailing list.
2177 If @command{git@tie{}pull@tie{}--verbose} succeeds, the output
2178 will include a @q{From} line that shows @q{ssh} as the protocol:
2181 From ssh://git.sv.gnu.org/srv/git/lilypond
2184 If the protocol shown is not @q{ssh}, check that you configured
2185 Git properly in the previous step.
2189 Test your commit access with a dry run:
2191 @warning{Do not push directly to master; instead, push to staging.
2192 See @ref{Pushing to staging}.}
2195 git push --dry-run --verbose
2198 Note that recent versions of Git (Git 1.6.3 or later) will issue a
2199 big warning if the above command is used. The simplest solution
2200 is to tell Git to push all matching branches by default:
2203 git config push.default matching
2207 Then @code{git@tie{}push} should work as before. For more
2208 details, consult the @code{git@tie{}push} man page.
2212 Repeat the steps from generating an RSA key through to testing
2213 your commit access, for each machine from which you will be
2214 making commits, or you may simply copy the files from your
2215 local @file{~/.ssh} folder to the same folder on the other
2220 @subsubheading Technical details
2224 On Firefox, to view or remove the CAcert root certificate, go to:
2225 Edit > Preferences > Advanced > Encryption > View Certificates >
2226 Authorities > Certificate Name > Root CA > CA Cert Signing
2230 The @command{git@tie{}config} commands above should modify your
2231 local repository's @file{.git/config} file. These lines:
2235 url = git://git.sv.gnu.org/lilypond.git/
2239 should now be changed to:
2243 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
2247 where @var{user} is your login name on Savannah.
2251 @command{git@tie{}config@tie{}push.default@tie{}matching} command
2252 should add these lines to @file{.git/config}:
2261 Encryption protocols, including ssh, generally do not permit packet
2262 fragmentation to avoid introducing a point of insecurity. This
2263 means that the maximum packet size must not exceed the smallest
2264 MTU (Maximum Transmission Unit) set in the routers along the path.
2265 This smallest MTU is determined by a procedure during call set-up
2266 which relies on the transmission over the path of ICMP packets.
2267 If any of the routers in the path block ICMP packets this mechanism
2268 fails, resulting in the possibility of packets being transmitted
2269 which exceed the MTU of one of the routers. If this happens the
2270 packet is discarded, causing the ssh session to hang, timeout or
2271 terminate with the error message
2274 ssh: connect to host <host ip addr> port 22: Bad file number
2275 fatal: The remote end hung up unexpectedly
2278 depending on precisely when in the proceedings the first large
2279 packet is transmitted. Most routers on the internet have MTU
2280 set to 1500, but routers installed in homes to connect via
2281 broadband may use a slightly smaller MTU for efficient transmission
2282 over ATM. If this problem is encountered a possible work-around is
2283 to set the MTU in the local router to 1500.
2286 @node Pushing to staging
2287 @subsection Pushing to staging
2289 Do not push directly to the git @code{master} branch. Instead,
2290 push to @code{staging}.
2292 You will not see your patch on @code{origin/master} until some
2293 automatic tests have been run. These tests are run every couple
2294 of hours; please wait at least 12 hours before wondering if your
2295 patch has been lost. Note that you can check the commits on
2296 @code{origin/staging} by looking at the git web interface on
2299 It may happen occasionally that the staging branch breaks automated
2300 testing. In this case the automatic move of staging material to
2301 master gets halted in order to avoid broken material entering master.
2302 This is a safety net. Please do not try breaking out from it by
2303 adding fixes on top of staging: in that case the whole sequence will
2304 end up in master after all, defeating the purpose of the system. The
2305 proper fix usually involves rewriting the staging branch and is best
2306 left to core developers after discussion on the developer list.
2308 Before pushing to staging it is a good practice to check whether
2309 staging is ahead of master, and if so, wait until master has caught up
2310 with staging before pushing. This simplifies things if changes to
2311 staging have to be backed out for some reason. To check whether
2312 master has caught up with staging you can look at the git web interface
2320 and check that @code{origin/master} is at the same commit as
2321 @code{origin/staging}. Another option is to see if any commits are
2326 git log origin/master..origin/staging
2329 @subsubheading If your work is in a patch file
2331 Assuming that your patch is in a file called
2332 @file{0001-my-patch.patch} (see @ref{Patches}), and you are currently
2336 git checkout staging
2338 git am 0001-my-patch.patch
2340 git push origin staging
2344 @warning{Do not skip the @command{gitk} step; a quick 5-second
2345 check of the visual history can save a great deal of frustration
2346 later on. You should only see that @command{staging} is only 1
2347 commit ahead of @code{origin/staging}.}
2349 @subsubheading If your work is in a branch
2351 If you are working on branches and your work is in
2352 @code{my_branch_name}, then do:
2355 git checkout my_branch_name
2356 git pull -r origin staging
2359 This will rebase your branch on @code{origin/staging}. At this point
2360 git will let you know if there are any conflicts. If so, resolve them
2365 git push origin HEAD:staging
2368 @warning{Do not skip the @command{gitk} step; a quick 5-second
2369 check of the visual history can save a great deal of frustration
2370 later on. You should see that @code{my_branch_name} is only ahead of
2371 @code{origin/staging} by the commits from your branch.}
2375 @node Git on Windows
2376 @section Git on Windows
2378 @warning{We heavily recommend that development be done with our
2379 virtual machine @ref{LilyDev}.}
2381 @c Some of this may duplicate stuff in other sections
2382 @c But it is probably best for windows users to have it all together
2383 @c If necessary, clear this up later -td
2385 TODO: Decide what to do with this... Pare it down? Move
2386 paragraphs next to analogous Unix instructions? -mp
2388 @subsection Background to nomenclature
2390 Git is a system for tracking the changes made to source files by a
2391 distributed set of editors. It is designed to work without a
2392 master repository, but we have chosen to have a master repository
2393 for LilyPond files. Editors hold a local copy of the master
2394 repository together with any changes they have made locally.
2395 Local changes are held in a local @q{branch}, of which there may
2396 be several, but these instructions assume you are using just one.
2397 The files visible in the local repository always correspond to
2398 those on the currently @q{checked out} local branch.
2400 Files are edited on a local branch, and in that state the changes
2401 are said to be @q{unstaged}. When editing is complete, the
2402 changes are moved to being @q{staged for commit}, and finally the
2403 changes are @q{committed} to the local branch. Once committed,
2404 the changes (called a @q{commit}) are given a unique 40-digit
2405 hexadecimal reference number called the @q{Committish} or @q{SHA1
2406 ID} which identifies the commit to Git. Such committed changes
2407 can be sent to the master repository by @q{pushing} them (if you
2408 have write permission) or by sending them by email to someone who
2409 has, either as a complete file or as a @q{diff} or @q{patch}
2410 (which send just the differences from the master repository).
2412 @subsection Installing git
2415 @uref{https://git-for-windows.github.io/}.
2417 Note that most users will not need to install SSH. That is not
2418 required until you have been granted direct push permissions to
2419 the master git repository.
2421 Start Git by clicking on the desktop icon. This will bring up a
2422 command line bash shell. This may be unfamiliar to Windows users.
2423 If so, follow these instructions carefully. Commands are entered
2424 at a $ prompt and are terminated by keying a newline.
2426 @subsection Initialising Git
2428 Decide where you wish to place your local Git repository, creating
2429 the folders in Windows as necessary. Here we call the folder to
2430 contain the repository @code{[path]/Git}, but if you intend using
2431 Git for other projects a directory name like @code{lilypond-git}
2432 might be better. You will need to have space for around
2435 Start the Git bash shell by clicking on the desk-top icon
2436 installed with Git and type
2442 to position the shell at your new Git repository.
2444 Note: if [path] contains folders with names containing spaces use
2456 to initialize your Git repository.
2458 Then type (all on one line; the shell will wrap automatically)
2461 git remote add -ft master origin git://git.sv.gnu.org/lilypond.git
2464 to download the lilypond master files.
2466 @warning{Be patient! Even on a broadband connection this can take
2467 10 minutes or more. Wait for lots of [new tag] messages and the $
2470 We now need to generate a local copy of the downloaded files in a
2471 new local branch. Your local branch needs to have a name. It is
2472 usual to call it @q{master} and we shall do that here.
2477 git checkout -b master origin/master
2480 This creates a second branch called @q{master}. You will see two
2481 warnings (ignore these), and a message advising you that your
2482 local branch @q{master} has been set up to track the remote
2483 branch. You now have two branches, a local branch called
2484 @q{master}, and a tracking branch called @q{origin/master}, which
2485 is a shortened form of @q{remotes/origin/master}.
2487 Return to Windows Explorer and look in your Git repository. You
2488 should see lots of folders. For example, the LilyPond
2489 documentation can be found in [path]/Git/Documentation/.
2491 The Git bash shell is terminated by typing @code{exit} or by
2492 clicking on the usual Windows close-window widget.
2496 Almost all subsequent work will use the Git Graphical User
2497 Interface, which avoids having to type command line commands. To
2498 start Git GUI first start the Git bash shell by clicking on the
2499 desktop icon, and type
2506 The Git GUI will open in a new window. It contains four panels
2507 and 7 pull-down menus. At this stage do not use any of the
2508 commands under Branch, Commit, Merge or Remote. These will be
2511 The top panel on the left contains the names of files which you
2512 are in the process of editing (Unstaged Changes), and the lower
2513 panel on the left contains the names of files you have finished
2514 editing and have staged ready for committing (Staged Changes). At
2515 present, these panels will be empty as you have not yet made any
2516 changes to any file. After a file has been edited and saved the
2517 top panel on the right will display the differences between the
2518 edited file selected in one of the panels on the left and the last
2519 version committed on the current branch.
2521 The panel at bottom right is used to enter a descriptive message
2522 about the change before committing it.
2524 The Git GUI is terminated by entering CNTL-Q while it is the
2525 active window or by clicking on the usual Windows close-window
2528 @subsection Personalising your local git repository
2530 Open the Git GUI, click on
2536 and enter your name and email address in the left-hand (Git
2537 Repository) panel. Leave everything else unchanged and save it.
2539 Note that Windows users must leave the default setting for line
2540 endings unchanged. All files in a git repository must have lines
2541 terminated by just a LF, as this is required for Merge to work,
2542 but Windows files are terminated by CRLF by default. The git
2543 default setting causes the line endings of files in a Windows git
2544 repository to be flipped automatically between LF and CRLF as
2545 required. This enables files to be edited by any Windows editor
2546 without causing problems in the git repository.
2548 @subsection Checking out a branch
2550 At this stage you have two branches in your local repository,
2551 both identical. To see them click on
2557 You should have one local branch called @q{master} and one
2558 tracking branch called @q{origin/master}. The latter is your
2559 local copy of the @q{remotes/origin/master} branch in the master
2560 LilyPond repository. The local @q{master} branch is where you
2561 will make your local changes.
2563 When a particular branch is selected, i.e., checked out, the files
2564 visible in your repository are changed to reflect the state of the
2565 files on that branch.
2567 @subsection Updating files from @q{remote/origin/master}
2569 Before starting the editing of a file, ensure your local
2570 repository contains the latest version of the files in the remote
2571 repository by first clicking
2574 Remote -> Fetch from -> origin
2580 This will place the latest version of every file, including all
2581 the changes made by others, into the @q{origin/master} branch of
2582 the tracking branches in your git repository. You can see these
2583 files by checking out this branch, but you must @emph{never} edit
2584 any files while this branch is checked out. Check out your local
2585 @q{master} branch again.
2587 You then need to merge these fetched files into your local
2588 @q{master} branch by clicking on
2591 Merge -> Local Merge
2595 and if necessary select the local @q{master} branch.
2597 Note that a merge cannot be completed if you have made any local
2598 changes which have not yet been committed.
2600 This merge will update all the files in the @q{master} branch to
2601 reflect the current state of the @q{origin/master} branch. If any
2602 of the changes conflict with changes you have made yourself
2603 recently you will be notified of the conflict (see below).
2605 @subsection Editing files
2607 First ensure your @q{master} branch is checked out, then simply
2608 edit the files in your local Git repository with your favourite
2609 editor and save them back there. If any file contains non-ASCII
2610 characters ensure you save it in UTF-8 format. Git will detect
2611 any changes whenever you restart Git GUI and the file names will
2612 then be listed in the Unstaged Changes panel. Or you can click
2613 the Rescan button to refresh the panel contents at any time. You
2614 may break off and resume editing any time.
2616 The changes you have made may be displayed in diff form in the top
2617 right-hand panel of Git GUI by clicking on the file name shown in
2618 one of the left panels.
2620 When your editing is complete, move the files from being Unstaged
2621 to Staged by clicking the document symbol to the left of each
2622 name. If you change your mind it can be moved back by clicking on
2623 the ticked box to the left of the name.
2625 Finally the changes you have made may be committed to your
2626 @q{master} branch by entering a brief message in the Commit
2627 Message box and clicking the Commit button.
2629 If you wish to amend your changes after a commit has been made,
2630 the original version and the changes you made in that commit may
2631 be recovered by selecting
2634 Commit -> Amend Last Commit
2638 or by checking the Amend Last Commit radio button at bottom right.
2639 This will return the changes to the Staged state, so further
2640 editing made be carried out within that commit. This must only be
2641 done @emph{before} the changes have been Pushed or sent to your
2642 mentor for Pushing - after that it is too late and corrections
2643 have to be made as a separate commit.
2646 @subsection Sending changes to @q{remotes/origin/master}
2648 If you do not have write access to @q{remotes/origin/master} you
2649 will need to send your changes by email to someone who does.
2651 First you need to create a diff or patch file containing your
2652 changes. To create this, the file must first be committed. Then
2653 terminate the Git GUI. In the git bash shell first cd to your Git
2660 if necessary, then produce the patch with
2663 git format-patch origin
2666 This will create a patch file for all the locally committed files
2667 which differ from @q{origin/master}. The patch file can be found
2668 in [path]/Git and will have a name formed from the commit message.
2670 @subsection Resolving merge conflicts
2672 As soon as you have committed a changed file your local
2673 @code{master} branch has diverged from @code{origin/master}, and
2674 will remain diverged until your changes have been committed in
2675 @code{remotes/origin/master} and Fetched back into your
2676 @code{origin/master} branch. Similarly, if a new commit has been
2677 made to @code{remotes/origin/master} by someone else and Fetched,
2678 your local @code{master} branch is divergent. You can detect a
2679 divergent branch by clicking on
2682 Repository -> Visualise all branch history
2685 This opens up a very useful new window called @q{gitk}. Use this
2686 to browse all the commits made by yourself and others.
2688 If the diagram at top left of the resulting window does not show
2689 your @code{master} tag on the same node as the
2690 @code{remotes/origin/master} tag your branch has diverged from
2691 @code{origin/master}. This is quite normal if files you have
2692 modified yourself have not yet been Pushed to
2693 @code{remotes/origin/master} and Fetched, or if files modified and
2694 committed by others have been Fetched since you last Merged
2695 @code{origin/master} into your local @code{master} branch.
2697 If a file being merged from @code{origin/master} differs from one
2698 you have modified in a way that cannot be resolved automatically
2699 by git, Merge will report a Conflict which you must resolve by
2700 editing the file to create the version you wish to keep.
2702 This could happen if the person updating
2703 @code{remotes/origin/master} for you has added some changes of his
2704 own before committing your changes to
2705 @code{remotes/origin/master}, or if someone else has changed the
2706 same file since you last fetched the file from
2707 @code{remotes/origin/master}.
2709 Open the file in your editor and look for sections which are
2712 [to be completed when I next have a merge conflict to be sure I
2713 give the right instructions -td]
2716 @subsection Other actions
2718 The instructions above describe the simplest way of using git on
2719 Windows. Other git facilities which may usefully supplement these
2723 @item Using multiple local branches (Create, Rename, Delete)
2724 @item Resetting branches
2725 @item Cherry-picking commits
2726 @item Pushing commits to @w{remote/origin/master}
2727 @item Using gitk to review history
2730 Once familiarity with using git on Windows has been gained the
2731 standard git manuals can be used to learn about these.
2734 @node Repository directory structure
2735 @section Repository directory structure
2738 @c TODO: integrate the roadmap better
2739 @verbatiminclude ROADMAP
2742 @node Other Git documentation
2743 @section Other Git documentation
2747 Official git man pages:
2748 @uref{http://www.kernel.org/pub/software/scm/git/docs/}
2751 More in-depth tutorials: @uref{http://git-scm.com/documentation}
2754 Book about git: @uref{http://progit.org/,Pro Git}
2757 Github help: @uref{http://help.github.com/}
2758 (very highly recommended by Graham)