1 @c -*- coding: utf-8; mode: texinfo; -*-
4 @node Working with source code
5 @chapter Working with source code
7 @warning{New contributors should read @ref{Quick start}, and in
8 particular @ref{Using lily-git}, instead of this chapter.}
10 Advanced contributors will find this material quite useful,
11 particularly if they are working on major new features.
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{http://code.google.com/p/msysgit/downloads/list}
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 55Mb). 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{Daily use of lily-git.tcl}.
101 @advanced{the @qq{Get source} button does not fetch the entire
102 history of the git repository, so utilities like @command{gitk}
103 will only be able to display the most recent additions. As you
104 continue to work with @command{lily-git.tcl}, the @qq{Update
105 source} button will take any new additions and add it to whatever
106 is currently in your repository's history.}
109 @node Starting with Git
110 @section Starting with Git
112 Using the Git program directly (as opposed to using the
113 @command{lily-git.tcl} GUI) allows you to have much greater control
114 over the contributing process. You should consider using Git if
115 you want to work on complex projects, or if you want to work on
116 multiple projects concurrently.
121 * Downloading remote branches::
126 @subsection Setting up
129 TODO: Remove this note if incorporating Windows instructions
130 throughout this section:
132 @warning{These instructions assume that you are using the
133 command-line version of Git 1.5 or higher. Windows users should
134 skip to @ref{Git on Windows}.}
138 * Initializing a repository::
144 @unnumberedsubsubsec Installing Git
147 If you are using a Unix-based machine, the easiest way to download
148 and install Git is through a package manager such as @command{rpm}
149 or @command{apt-get}---the installation is generally automatic.
150 The only required package is (usually) called @command{git-core},
151 although some of the auxiliary @command{git@var{*}} packages are
152 also useful (such as @command{gitk}).
154 Alternatively, you can visit the Git website
155 (@uref{http://git-scm.com/}) for downloadable binaries and
158 TODO: add Windows installation instructions (or @@ref@{Git on
162 @node Initializing a repository
163 @unnumberedsubsubsec Initializing a repository
166 Once Git is installed, you'll need to create a new directory where
167 your initial repository will be stored (the example below uses
168 @file{~/lilypond-git/}, where @code{~} represents your home
169 directory). Run @command{git@tie{}init} from within the new
170 directory to initialize an empty repository:
173 mkdir ~/lilypond-git/; cd ~/lilypond-git/
177 @subsubheading Technical details
179 This creates (within the @file{~/lilypond-git/} directory) a
180 subdirectory called @file{.git/}, which Git uses to keep track of
181 changes to the repository, among other things. Normally you don't
182 need to access it, but it's good to know it's there.
185 @node Configuring Git
186 @unnumberedsubsubsec Configuring Git
188 @warning{Throughout the rest of this manual, all command-line
189 input should be entered from the top directory of the Git
190 repository being discussed (eg. @file{~/lilypond-git/}). This is
191 referred to as the @emph{top source directory}.}
193 Before downloading a copy of the main LilyPond repository, you
194 should configure some basic settings with the
195 @command{git@tie{}config} command. Git allows you to set both
196 global and repository-specific options.
198 To configure settings that affect all repositories, use the
199 @option{--global} command line option. For example, the first
200 two options that you should always set are your @var{name} and
201 @var{email}, since Git needs these to keep track of commit
205 git config --global user.name "@var{John Smith}"
206 git config --global user.email @var{john@@example.com}
209 To configure Git to use colored output where possible, use:
212 git config --global color.ui auto
215 The text editor that opens when using @command{git@tie{}commit}
216 can also be changed. If none of your editor-related environment
217 variables are set ($GIT_EDITOR, $VISUAL, or $EDITOR), the default
218 editor is usually @command{vi} or @command{vim}. If you're not
219 familiar with either of these, you should probably change the
220 default to an editor that you know how to use. For example, to
221 change the default editor to @command{nano}, enter:
224 git config --global core.editor @var{nano}
227 TODO: Add instructions for changing the editor on Windows, which
228 is a little different, I think. -mp
230 @subsubheading Technical details
232 Git stores the information entered with
233 @command{git@tie{}config@tie{}--global} in the file
234 @file{.gitconfig}, located in your home directory. This file can
235 also be modified directly, without using
236 @command{git@tie{}config}. The @file{.gitconfig} file generated
237 by the above commands would look like this:
242 email = john@@example.com
249 Using the @command{git@tie{}config} command @emph{without} the
250 @option{--global} option configures repository-specific settings,
251 which are stored in the file @file{.git/config}. This file is
252 created when a repository is initialized (using
253 @command{git@tie{}init}), and by default contains these lines:
257 repositoryformatversion = 0
260 logallrefupdates = true
263 However, since different repository-specific options are
264 recommended for different development tasks, it is best to avoid
265 setting any now. Specific recommendations will be mentioned later
269 @node Downloading remote branches
270 @subsection Downloading remote branches
274 * Organization of remote branches::
275 * LilyPond repository sources::
276 * Downloading individual branches::
277 * Downloading all remote branches::
282 @node Organization of remote branches
283 @unnumberedsubsubsec Organization of remote branches
286 The main LilyPond repository is organized into @emph{branches} to
287 facilitate development. These are often called @emph{remote}
288 branches to distinguish them from @emph{local} branches you might
289 create yourself (see @ref{Using local branches}).
291 The @code{master} branch contains all the source files used to
292 build LilyPond, which includes the program itself (both stable and
293 development releases), the documentation (and its translations),
294 and the website. Generally, the @code{master} branch is expected
295 to compile successfully.
297 The @code{lilypond/translation} branch is a side branch that
298 allows translators to work without needing to worry about
299 compilation problems. Periodically, the Translation Meister
300 (after verifying that it doesn't break compilation), will
301 @emph{merge} this branch back into @code{master} to incorporate
302 recent translations. Similarly, the @code{master} branch is
303 usually merged into the @code{lilypond/translation} branch after
304 significant changes to the English documentation. See
305 @ref{Translating the documentation} for details.
308 @node LilyPond repository sources
309 @unnumberedsubsubsec LilyPond repository sources
312 The recommended source for downloading a copy of the main
316 git://git.sv.gnu.org/lilypond.git
319 However, if your internet router filters out connections using the
320 GIT protocol, or if you experience difficulty connecting via GIT,
321 you can try these other sources:
324 ssh://git.sv.gnu.org/srv/git/lilypond.git
325 http://git.sv.gnu.org/r/lilypond.git
328 The SSH protocol can only be used if your system is properly set
329 up to use it. Also, the HTTP protocol is slowest, so it should
330 only be used as a last resort.
333 @node Downloading individual branches
334 @unnumberedsubsubsec Downloading individual branches
337 Once you have initialized an empty Git repository on your system
338 (see @ref{Initializing a repository}), you can download a remote
339 branch into it. Make sure you know which branch you want to start
342 To download the @code{master} branch, enter the following:
345 git remote add -ft master -m master \
346 origin git://git.sv.gnu.org/lilypond.git/
349 To download the @code{lilypond/translation} branch, enter:
352 git remote add -ft lilypond/translation -m \
353 lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
356 The @command{git@tie{}remote@tie{}add} process could take up to
357 ten minutes, depending on the speed of your connection. The
358 output will be something like this:
362 remote: Counting objects: 235967, done.
363 remote: Compressing objects: 100% (42721/42721), done.
364 remote: Total 235967 (delta 195098), reused 233311 (delta 192772)
365 Receiving objects: 100% (235967/235967), 68.37 MiB | 479 KiB/s, done.
366 Resolving deltas: 100% (195098/195098), done.
367 From git://git.sv.gnu.org/lilypond
368 * [new branch] master -> origin/master
369 From git://git.sv.gnu.org/lilypond
370 * [new tag] flower/1.0.1 -> flower/1.0.1
371 * [new tag] flower/1.0.10 -> flower/1.0.10
373 * [new tag] release/2.9.6 -> release/2.9.6
374 * [new tag] release/2.9.7 -> release/2.9.7
377 When @command{git@tie{}remote@tie{}add} is finished, the remote
378 branch should be downloaded into your repository---though not yet
379 in a form that you can use. In order to browse the source code
380 files, you need to @emph{create} and @emph{checkout} your own
381 local branch. In this case, however, it is easier to have Git
382 create the branch automatically by using the @command{checkout}
383 command on a non-existent branch. Enter the following:
386 git checkout -b @var{branch} origin/@var{branch}
390 where @code{@var{branch}} is the name of your tracking branch,
391 either @code{master} or @code{lilypond/translation}.
393 Git will issue some warnings; this is normal:
396 warning: You appear to be on a branch yet to be born.
397 warning: Forcing checkout of origin/master.
398 Branch master set up to track remote branch master from origin.
402 By now the source files should be accessible---you should be able
403 to edit any files in the @file{lilypond-git/} directory using a
404 text editor of your choice. But don't start just yet! Before
405 editing any source files, learn how to keep your changes organized
406 and prevent problems later---read @ref{Basic Git procedures}.
408 @subsubheading Technical Details
410 The @command{git@tie{}remote@tie{}add} command should add some
411 lines to your local repository's @file{.git/config} file:
415 url = git://git.sv.gnu.org/lilypond.git/
416 fetch = +refs/heads/master:refs/remotes/origin/master
420 @node Downloading all remote branches
421 @unnumberedsubsubsec Downloading all remote branches
424 To download all remote branches at once, you can @command{clone}
425 the entire repository:
428 git clone git://git.sv.gnu.org/lilypond.git
433 @unnumberedsubsubsec Other branches
435 Most contributors will never need to touch the other branches. If
436 you wish to do so, you will need more familiarity with Git; please
437 see @ref{Other Git documentation}.
440 @item @code{dev/XYZ}:
441 These branches are for individual developers. They store code
442 which is not yet stable enough to be added to the @code{master}
445 @item @code{stable/XYZ}:
446 The branches are kept for archival reasons.
450 Another item of interest might be the Grand Unified Builder, our
451 cross-platform building tool. Since it is used by projects as
452 well, it is not stored in our gub repository. For more info, see
453 @uref{http://lilypond.org/gub}. The git location is
454 @uref{http://github.com/janneke/gub}.
457 @node Basic Git procedures
458 @section Basic Git procedures
462 * The Git contributor's cycle::
463 * Pulling and rebasing::
464 * Using local branches::
465 * Commits and patches::
469 @node The Git contributor's cycle
470 @subsection The Git contributor's cycle
473 Here is a simplified view of the contribution process on Git:
477 Update your local repository by @emph{pulling} the most recent
478 updates from the remote repository.
481 Edit source files within your local repository's @emph{working
485 @emph{Commit} the changes you've made to a local @emph{branch}.
488 Generate a @emph{patch} to share your changes with the developers.
492 @node Pulling and rebasing
493 @subsection Pulling and rebasing
496 When developers push new patches to the @code{git.sv.gnu.org}
497 repository, your local repository is @strong{not} automatically
498 updated. It is important to keep your repository up-to-date by
499 periodically @emph{pulling} the most recent @emph{commits} from
500 the remote branch. Developers expect patches to be as current as
501 possible, since outdated patches require extra work before they
504 Occasionally you may need to rework some of your own modifications
505 to match changes made to the remote branch (see @ref{Resolving
506 conflicts}), and it's considerably easier to rework things
507 incrementally. If you don't update your repository along the way,
508 you may have to spend a lot of time resolving branch conflicts and
509 reconfiguring much of the work you've already done.
511 Fortunately, Git is able to resolve certain types of branch
512 conflicts automatically with a process called @emph{rebasing}.
513 When rebasing, Git tries to modify your old commits so they appear
514 as new commits (based on the latest updates). For a more involved
515 explanation, see the @command{git-rebase} man page.
517 To pull without rebasing (recommended for translators), use the
521 git pull # recommended for translators
524 If you're tracking the remote @code{master} branch, you should add
525 the @option{-r} option (short for @option{--rebase}) to keep commits
526 on your local branch current:
529 git pull -r # use with caution when translating
532 If you don't edit translated documentation and don't want to type
533 @option{-r} every time, configure the master branch to rebase by
534 default with this command:
537 git config branch.master.rebase true
540 If pull fails because of a message like
543 error: Your local changes to 'Documentation/learning/tutorial.itely'
544 would be overwritten by merge. Aborting.
551 Documentation/learning/tutorial.itely: needs update
552 refusing to pull with rebase: your working tree is not up-to-date
556 it means that you have modified some files in you working tree
557 without committing changes (see @ref{Commits and patches}); you
558 can use the @command{git@tie{}stash} command to work around this:
561 git stash # save uncommitted changes
562 git pull -r # pull using rebase (translators omit "-r")
563 git stash pop # reapply previously saved changes
566 Note that @command{git@tie{}stash@tie{}pop} will try to apply a
567 patch, and this may create a conflict. If this happens, see
568 @ref{Resolving conflicts}.
570 TODO: I think the next paragraph is confusing. Perhaps prepare
571 the reader for new terms `committish' and `head'? -mp
573 @warning{translators and documentation editors, if you have
574 changed committishes in the head of translated files using commits
575 you have not yet pushed to @code{git.sv.gnu.org}, please do not
576 rebase. If you want to avoid wondering whether you should rebase
577 each time you pull, please always use committishes from master
578 and/or lilypond/translation branch on @code{git.sv.gnu.org}, which
579 in particular implies that you must push your changes to
580 documentation except committishes updates (possibly after having
581 rebased), then update the committishes and push them.}
583 TODO: when committishes automatic conditional update have been
584 tested and documented, append the following to the warning above:
585 Note that using update-committishes make target generally touches
588 @subsubheading Technical details
590 The @command{git@tie{}config} command mentioned above adds the
591 line @code{rebase = true} to the master branch in your local
592 repository's @file{.git/config} file:
597 merge = refs/heads/master
602 @node Using local branches
603 @subsection Using local branches
607 * Creating and removing branches::
608 * Listing branches and remotes::
609 * Checking out branches::
614 @node Creating and removing branches
615 @unnumberedsubsubsec Creating and removing branches
618 Local branches are useful when you're working on several different
619 projects concurrently. To create a new branch, enter:
622 git branch @var{name}
625 To delete a branch, enter:
628 git branch -d @var{name}
631 Git will ask you for confirmation if it sees that data would be
632 lost by deleting the branch. Use @option{-D} instead of @option{-d}
633 to bypass this. Note that you cannot delete a branch if it is
634 currently checked out.
637 @node Listing branches and remotes
638 @unnumberedsubsubsec Listing branches and remotes
640 You can get the exact path or URL of all remote branches by
647 To list Git branches on your local repositories, run
650 git branch # list local branches only
651 git branch -r # list remote branches
652 git branch -a # list all branches
656 @node Checking out branches
657 @unnumberedsubsubsec Checking out branches
659 To know the currently checked out branch, i.e. the branch whose
660 source files are present in your working tree, read the first line
668 The currently checked out branch is also marked with an asterisk
669 in the output of @command{git branch}.
671 You can check out another branch @code{@var{other_branch}}, i.e.
672 check out @code{@var{other_branch}} to the working tree, by
676 git checkout @var{other_branch}
679 Note that it is possible to check out another branch while having
680 uncommitted changes, but it is not recommended unless you know
681 what you are doing; it is recommended to run @command{git status}
682 to check this kind of issue before checking out another branch.
684 @node Merging branches
685 @unnumberedsubsubsec Merging branches
687 To merge branch @code{@var{foo}} into branch @code{@var{bar}},
688 i.e. to @qq{add} all changes made in branch @code{@var{foo}} to
689 branch @code{@var{bar}}, run
692 git checkout @var{bar}
696 If any conflict happens, see @ref{Resolving conflicts}.
698 There are common usage cases for merging: as a translator, you
699 will often want to merge @code{master} into
700 @code{lilypond/translation}; on the other hand, the Translations
701 meister wants to merge @code{lilypond/translation} into
702 @code{master} whenever he has checked that
703 @code{lilypond/translation} builds successfully.
706 @node Commits and patches
707 @subsection Commits and patches
711 * Understanding commits::
715 * Uploading a patch for review::
719 @node Understanding commits
720 @unnumberedsubsubsec Understanding commits
722 Technically, a @emph{commit} is a single point in the history of a
723 branch, but most developers use the term to mean a @emph{commit
724 object}, which stores information about a particular revision. A
725 single commit can record changes to multiple source files, and
726 typically represents one logical set of related changes (such as a
727 bug-fix). You can list the ten most recent commits in your
728 current branch with this command:
731 git log -10 --oneline
734 If you're using an older version of Git and get an @q{unrecognized
735 argument} error, use this instead:
738 git log -10 --pretty=oneline --abbrev-commit
741 More interactive lists of the commits on the remote @code{master}
742 branch are available at
743 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=shortlog} and
744 @uref{http://git.sv.gnu.org/cgit/lilypond.git/log/}.
748 @unnumberedsubsubsec Making commits
751 Once you have modified some source files in your working
752 directory, you can make a commit with the following procedure:
756 Make sure you've configured Git properly (see @ref{Configuring
757 Git}). Check that your changes meet the requirements described in
758 @ref{Code style} and/or @ref{Documentation policy}. For advanced
759 edits, you may also want to verify that the changes don't break
760 the compilation process.
763 Run the following command:
770 to make sure you're on the right branch, and to see which files
771 have been modified, added or removed, etc. You may need to tell
772 Git about any files you've added by running one of these:
775 git add @var{file} # add untracked @var{file} individually
776 git add . # add all untracked files in current directory
780 After @command{git@tie{}add}, run @command{git@tie{}status} again
781 to make sure you got everything. You may also need to modify
785 Preview the changes about to be committed (to make sure everything
793 The @code{HEAD} argument refers to the most recent commit on the
794 currently checked-out branch.
797 Generate the commit with:
804 The @option{-a} is short for @option{--all} which includes modified
805 and deleted files, but only those newly created files that have
806 previously been added.
811 @node Commit messages
812 @unnumberedsubsubsec Commit messages
815 When you run the @command{git@tie{}commit@tie{}-a} command, Git
816 automatically opens the default text editor so you can enter a
817 @emph{commit message}. If you find yourself in a foreign editing
818 environment, you're probably in @command{vi} or @command{vim}. If
819 you want to switch to an editor you're more familiar with, quit by
820 typing @code{:q!} and pressing @code{<Enter>}. See
821 @ref{Configuring Git} for instructions on changing the default
824 In any case, Git will open a text file for your commit message
825 that looks like this:
829 # Please enter the commit message for your changes. Lines starting
830 # with '#' will be ignored, and an empty message aborts the commit.
832 # Changes to be committed:
833 # (use "git reset HEAD <file>..." to unstage)
835 # modified: working.itexi
839 Your commit message should begin with a one-line summary
840 describing the change (no more than 50 characters long), and if
841 necessary a blank line followed by several lines giving the
844 @c $ git log -1 --pretty=medium 4d6f1e5
846 Doc: add Baerenreiter and Henle solo cello suites
848 Added comparison of solo cello suite engravings to new essay with
849 high-res images, fixed cropping on Finale example.
852 Commit messages often start with a short prefix describing the
853 general location of the changes. If a commit affects the
854 documentation in English (or in several languages simultaneously)
855 the commit message should be prefixed with @qq{Doc:@tie{}}. If
856 the commit affects only one of the translations, the commit
857 message should be prefixed with @qq{Doc-@var{**}:@tie{}}, where
858 @var{**} is the two-letter language code. Commits that affect the
859 website should use @qq{Web:@tie{}} for English, and
860 @qq{Web-@var{**}:@tie{}} for the other languages. Also, changes
861 to a single file are often prefixed with the name of the file
862 involved. Visit the links listed in @ref{Understanding commits}
867 @unnumberedsubsubsec Making patches
869 If you want to share your changes with other contributors and
870 developers, you need to generate @emph{patches} from your commits.
871 We prefer it if you follow the instructions in
872 @ref{Uploading a patch for review}. However, we present an
873 alternate method here.
875 You should always run @command{git@tie{}pull@tie{}-r} (translators
876 should leave off the @option{-r}) before doing this to ensure that
877 your patches are as current as possible.
879 Once you have made one or more commits in your local repository,
880 and pulled the most recent commits from the remote branch, you can
881 generate patches from your local commits with the command:
884 git format-patch origin
887 The @code{origin} argument refers to the remote tracking branch at
888 @code{git.sv.gnu.org}. This command generates a separate patch
889 for each commit that's in the current branch but not in the remote
890 branch. Patches are placed in the current working directory and
891 will have names that look something like this:
894 0001-Doc-Fix-typos.patch
895 0002-Web-Remove-dead-links.patch
899 Send an email (must be less than 64 KB) to
900 @email{lilypond-devel@@gnu.org} briefly explaining your work, with
901 the patch files attached. Translators should send patches to
902 @email{translations@@lilynet.net}. After your patches are
903 reviewed, the developers may push one or more of them to the main
904 repository or discuss them with you.
907 @node Uploading a patch for review
908 @unnumberedsubsubsec Uploading a patch for review
910 Any non-trivial change should be uploaded to our @qq{Rietveld}
914 @uref{http://codereview.appspot.com/}
917 @subsubheading @command{git-cl} install
919 LilyDev users should skip over these @q{install} instructions.
924 Install @command{git-cl} by entering:
927 git clone https://github.com/gperciva/git-cl.git
930 If that command fails for some reason, try this instead:
933 git clone git://github.com/gperciva/git-cl.git
937 Add the @file{git-cl/} directory to your PATH, or create a
938 symbolic link to the @command{git-cl} and @command{upload.py}
939 scripts in one of your PATH directories (such as
944 @subsubheading @command{git-cl} configuration
946 LilyDev users should perform these @q{configuration} instructions.
950 You must have a google account; please create one if you do not
953 Note that a google account does not need to be a gmail account; you can
954 use any email address for your google account when you sign up.
957 Move into the top source directory and then configure @command{git
958 cl} with the following commands. If you do not understand any
959 question, just answer with a newline (CR).
962 cd $HOME/lilypond-git/
966 The @qq{CC list} question should be answered with:
969 lilypond-devel@@gnu.org
974 @subsubheading Uploading patch set
976 @warning{Unless you are familiar with branches, only work on one
977 set of changes at once.}
979 There are two methods, depending on your git setup.
983 @strong{Master branch}: (easy option, and used in @command{lily-git.tcl})
985 If you added your patch to @code{master}, then:
989 git cl upload origin/master
992 If you have git push ability, make sure that you @emph{remove}
993 your patch (with @command{git rebase} or @command{git reset})
994 before pushing other stuff.
996 @c don't make this one an @example; we don't want to make it easy
997 @c for people to use this accidently
998 Notifications of patches are automatically added to our issue
999 tracker to reduce the chance of patches getting lost. To suppress
1000 this (not recommended), add the @code{-n / --no-code-issue}
1004 @strong{Separate branch}: (complicated option)
1006 Ensure your changes are committed in a separate branch, which
1007 should differ from the reference branch to be used by just the
1008 changes to be uploaded. If the reference branch is to be
1009 origin/master, ensure this is up-to-date. If necessary, use git
1010 rebase to rebase the branch containing the changes to the head of
1011 origin/master. Finally, check out branch with the changes and
1015 git cl upload <reference SHA1 ID>
1019 where <reference SHA1 ID> is the SHA1 ID of the commit to be used
1020 as a reference source for the patch. Generally, this will be the
1021 SHA1 ID of origin/master, and in that case the command:
1024 git cl upload origin/master
1032 After prompting for your Google email address and password, the
1033 patch set will be posted to Rietveld, and you will be given a URL
1036 @warning{Some installations of git-cl fail when uploading a patch
1037 with certain filename extensions. If this happens, it can
1038 generally be fixed by editing the list of exceptions at top of
1041 @subsubheading Announcing your patch set
1043 You should then announce the patch by logging into the code review
1044 issue webpage and using @qq{Publish + Mail Comments} to add a
1045 (mostly bogus) comment to your issue. The text of your comment
1046 will be sent to our developer mailing list.
1048 @warning{There is no automatic notification of a new patch; you
1049 must add a comment yourself.}
1051 @subsubheading Revisions
1053 As revisions are made in response to comments, successive patch sets
1054 for the same issue can be uploaded by reissuing the git-cl command
1055 with the modified branch checked out.
1057 Sometimes in response to comments on revisions, the best way to
1058 work may require creation of a new branch in git. In order to
1059 associate the new branch with an existing Rietveld issue,
1060 the following command can be used:
1063 git cl issue issue-number
1067 where @code{issue-number} is the number of the existing Rietveld
1070 @subsubheading Resetting git cl
1072 If @command{git cl} becomes confused, you can @qq{reset} it by
1080 @node Advanced Git procedures
1081 @section Advanced Git procedures
1084 @warning{This section is not necessary for normal contributors;
1085 these commands are presented for information for people interested
1086 in learning more about git.}
1088 It is possible to work with several branches on the same local Git
1089 repository; this is especially useful for translators who may have
1090 to deal with both @code{lilypond/translation} and a stable branch,
1091 e.g. @code{stable/2.12}.
1093 Some Git commands are introduced first, then a workflow with
1094 several Git branches of LilyPond source code is presented.
1098 * Advanced Git concepts::
1099 * Resolving conflicts::
1100 * Reverting all local changes::
1101 * Working with remote branches::
1103 * Applying remote patches::
1104 * Sending and receiving patches via email::
1105 * Cleaning up multiple patches::
1110 @node Advanced Git concepts
1111 @subsection Advanced Git concepts
1114 A bit of Git vocabulary will be explained below. The following is
1115 only introductory; for a better understanding of Git concepts, you
1116 may wish to read @ref{Other Git documentation}.
1118 The @code{git@tie{}pull@tie{}origin} command above is just a
1119 shortcut for this command:
1122 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
1126 where @code{@var{branch}} is typically @code{master} or
1127 @code{lilypond/translation}; if you do not know or remember, see
1128 @ref{Downloading remote branches} to remember which commands you
1129 issued or which source code you wanted to get.
1131 A @emph{commit} is a set of changes made to the sources; it also
1132 includes the committish of the parent commit, the name and e-mail
1133 of the @emph{author} (the person who wrote the changes), the name
1134 and e-mail of the @emph{committer} (the person who brings these
1135 changes into the Git repository), and a commit message.
1137 A @emph{committish} is the SHA1 checksum of a commit, a number
1138 made of 40 hexadecimal digits, which acts as the internal unique
1139 identifier for this commit. To refer to a particular revision,
1140 don't use vague references like the (approximative) date, simply
1141 copy and paste the committish.
1143 A @emph{branch} is nothing more than a pointer to a particular
1144 commit, which is called the @emph{head} of the branch; when
1145 referring to a branch, one often actually thinks about its head
1146 and the ancestor commits of the head.
1148 Now we will explain the two last commands you used to get the
1149 source code from Git---see @ref{Downloading individual branches}.
1152 git remote add -ft @var{branch} -m @var{branch} \
1153 origin git://git.sv.gnu.org/lilypond.git/
1155 git checkout -b @var{branch} origin/@var{branch}
1158 The @command{git@tie{}remote} has created a branch called
1159 @code{origin/@var{branch}} in your local Git repository. As this
1160 branch is a copy of the remote branch web from git.sv.gnu.org
1161 LilyPond repository, it is called a @emph{remote branch}, and is
1162 meant to track the changes on the branch from git.sv.gnu.org: it
1163 will be updated every time you run
1164 @command{git@tie{}pull@tie{}origin} or
1165 @command{git@tie{}fetch@tie{}origin}.
1167 The @command{git@tie{}checkout} command has created a branch named
1168 @code{@var{branch}}. At the beginning, this branch is identical
1169 to @code{origin/@var{branch}}, but it will differ as soon as you
1170 make changes, e.g. adding newly translated pages or editing some
1171 documentation or code source file. Whenever you pull, you merge
1172 the changes from @code{origin/@var{branch}} and
1173 @code{@var{branch}} since the last pulling. If you do not have
1174 push (i.e. @qq{write}) access on git.sv.gnu.org, your
1175 @code{@var{branch}} will always differ from
1176 @code{origin/@var{branch}}. In this case, remember that other
1177 people working like you with the remote branch @code{@var{branch}}
1178 of git://git.sv.gnu.org/lilypond.git/ (called
1179 @code{origin/@var{branch}} on your local repository) know nothing
1180 about your own @code{@var{branch}}: this means that whenever you
1181 use a committish or make a patch, others expect you to take the
1182 latest commit of @code{origin/@var{branch}} as a reference.
1184 Finally, please remember to read the man page of every Git command
1185 you will find in this manual in case you want to discover
1186 alternate methods or just understand how it works.
1189 @node Resolving conflicts
1190 @subsection Resolving conflicts
1193 Occasionally an update may result in conflicts -- this happens
1194 when you and somebody else have modified the same part of the same
1195 file and git cannot figure out how to merge the two versions
1196 together. When this happens, you must manually merge the two
1199 If you need some documentation to understand and resolve
1200 conflicts, see paragraphs @emph{How conflicts are presented} and
1201 @emph{How to resolve conflicts} in @command{git merge} man page.
1203 If all else fails, you can follow the instructions in
1204 @ref{Reverting all local changes}. Be aware that this eliminates
1205 any changes you have made!
1208 @node Reverting all local changes
1209 @subsection Reverting all local changes
1211 Sometimes git will become hopelessly confused, and you just want
1212 to get back to a known, stable state. This command destroys any
1213 local changes you have made in the currently checked-out branch,
1214 but at least you get back to the current online version:
1217 git reset --hard origin/master
1221 @node Working with remote branches
1222 @subsection Working with remote branches
1225 @subsubheading Fetching new branches from git.sv.gnu.org
1227 To fetch and check out a new branch named @code{@var{branch}} on
1228 git.sv.gnu.org, run from top of the Git repository
1231 git config --add remote.origin.fetch \
1232 +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
1234 git checkout --track -b @var{branch} origin/@var{branch}
1237 After this, you can pull @code{@var{branch}} from git.sv.gnu.org
1244 Note that this command generally fetches all branches you added
1245 with @command{git@tie{}remote@tie{}add} (when you initialized the
1246 repository) or @command{git@tie{}config@tie{}--add}, i.e. it
1247 updates all remote branches from remote @code{origin}, then it
1248 merges the remote branch tracked by the current branch into the
1249 current branch. For example, if your current branch is
1250 @code{master}, @code{origin/master} will be merged into
1254 @subsubheading Local clones, or having several working trees
1256 If you play with several Git branches, e.g. @code{master},
1257 @code{lilypond/translation}, @code{stable/2.12}), you may want to
1258 have one source and build tree for each branch; this is possible
1259 with subdirectories of your local Git repository, used as local
1260 cloned subrepositories. To create a local clone for the branch
1261 named @code{@var{branch}}, run
1264 git checkout @var{branch}
1265 git clone -lsn . @var{subdir}
1270 Note that @code{@var{subdir}} must be a directory name which does
1271 not already exist. In @code{@var{subdir}}, you can use all Git
1272 commands to browse revisions history, commit and uncommit changes;
1273 to update the cloned subrepository with changes made on the main
1274 repository, cd into @code{@var{subdir}} and run
1275 @command{git@tie{}pull}; to send changes made on the subrepository
1276 back to the main repository, run @command{git@tie{}push} from
1277 @code{@var{subdir}}. Note that only one branch (the currently
1278 checked out branch) is created in the subrepository by default; it
1279 is possible to have several branches in a subrepository and do
1280 usual operations (checkout, merge, create, delete...) on these
1281 branches, but this possibility is not detailed here.
1283 When you push @code{@var{branch}} from @code{@var{subdir}} to the
1284 main repository, and @code{@var{branch}} is checked out in the
1285 main repository, you must save uncommitted changes (see
1286 @command{git@tie{}stash}) and do
1287 @command{git@tie{}reset@tie{}--hard} in the main repository in
1288 order to apply pushed changes in the working tree of the main
1296 The commands above don't only bring you the latest version of the
1297 sources, but also the full history of revisions (revisions, also
1298 called commits, are changes made to the sources), stored in the
1299 @file{.git} directory. You can browse this history with
1302 git log # only shows the logs (author, committish and commit message)
1303 git log -p # also shows diffs
1304 gitk # shows history graphically
1307 @warning{The @code{gitk} command may require a separate
1308 @code{gitk} package, available in the appropriate distribution's
1312 @node Applying remote patches
1313 @subsection Applying remote patches
1316 TODO: Explain how to determine if a patch was created with
1317 @code{git@tie{}format-patch}.
1319 Well-formed git patches created with @code{git@tie{}format-patch}
1320 should be committed with the following command:
1326 Patches created without @code{git@tie{}format-patch} can be
1327 applied in two steps. The first step is to apply the patch to the
1331 git apply @var{patch}
1335 The second step is to commit the changes and give credit to the
1336 author of the patch. This can be done with the following command:
1339 git commit -a --author="@var{John Smith} <@var{john@@example.com}>"
1343 @node Sending and receiving patches via email
1344 @subsection Sending and receiving patches via email
1347 The default @code{x-diff} MIME type associated with patch files
1348 (i.e., files whose name ends in @code{.patch}) means that the
1349 encoding of line endings may be changed from UNIX to DOS format
1350 when they are sent as attachments. Attempting to apply such an
1351 inadvertently altered patch will cause git to fail with a message
1352 about @q{whitespace errors}.
1354 The solution to such problems is surprisingly simple---just change
1355 the default file extension of patches generated by git to end in
1356 @code{.txt}, for example:
1359 git config format.suffix '.patch.txt'
1362 This should cause email programs to apply the correct base64
1363 encoding to attached patches.
1365 If you receive a patch with DOS instead of UNIX line-endings, it
1366 can be converted back using the @code{dos2unix} utility.
1368 Lots of useful information on email complications with patches is
1369 provided on the Wine wiki at
1370 @uref{http://wiki.winehq.org/GitWine}.
1373 @node Cleaning up multiple patches
1374 @subsection Cleaning up multiple patches
1376 If you have been developing on your own branch for a while, you
1377 may have more commmits than is really sensible. To revise your
1378 work and condense commits, use:
1381 git rebase origin/master
1382 git rebase -i origin/master
1385 @warning{Be a bit cautious -- if you completely remove commits
1386 during the interactive session, you will... err... completely
1387 remove those commits.}
1391 @subsection Commit access
1394 Most contributors are not able to commit patches directly to the
1395 main repository---only members of the LilyPond development team
1396 have @emph{commit access}. If you are a contributor and are
1397 interested in joining the development team, contact the Project
1398 Manager through the mailing list
1399 (@email{lilypond-devel@@gnu.org}). Generally, only contributors
1400 who have already provided a number of patches which have been
1401 pushed to the main repository will be considered for membership.
1403 If you have been approved by the Project Manager, use the
1404 following procedure to obtain commit access:
1408 If you don't already have one, set up a Savannah user account at
1409 @uref{https://savannah.gnu.org/account/register.php}. If your web
1410 browser responds with an @qq{untrusted connection} message when
1411 you visit the link, follow the steps for including the CAcert root
1412 certificate in your browser, given at
1413 @uref{http://savannah.gnu.org/tls/tutorial/}.
1415 @warning{Savannah will silently put your username in lower-case --
1416 do not try to use capital letters.}
1420 After registering, if you are not logged in automatically, login
1421 at @uref{https://savannah.gnu.org/account/login.php}---this should
1422 take you to your @qq{my} page
1423 (@uref{https://savannah.gnu.org/my/}).
1427 Click on the @qq{My Groups} link to access the @qq{My Group
1428 Membership} page. From there, find the @qq{Request for Inclusion}
1429 box and search for @qq{LilyPond}. Among the search results, check
1430 the box labeled @qq{GNU LilyPond Music Typesetter} and write a
1431 brief (required) message for the Project Manager (@qq{Hey it's
1432 me!} should be fine).
1434 Note that you will not have commit access until the Project
1435 Manager activates your membership. Once your membership is
1436 activated, LilyPond should appear under the heading @qq{Groups I'm
1437 Contributor of} on your @qq{My Group Membership} page.
1441 Generate an SSH @q{rsa} key pair. Enter the following at the
1448 When prompted for a location to save the key, press <ENTER> to
1449 accept the default location (@file{~/.ssh/id_rsa}).
1451 Next you are asked to enter an optional passphrase. On most
1452 systems, if you use a passphrase, you will likely be prompted for
1453 it every time you use @command{git@tie{}push} or
1454 @command{git@tie{}pull}. You may prefer this since it can protect
1455 you from your own mistakes (like pushing when you mean to pull),
1456 though you may find it tedious to keep re-entering it.
1458 You can change/enable/disable your passphrase at any time with:
1461 ssh-keygen -f ~/.ssh/id_rsa -p
1464 Note that the GNOME desktop has a feature which stores your
1465 passphrase for you for an entire GNOME session. If you use a
1466 passphrase to @qq{protect you from yourself}, you will want to
1467 disable this feature, since you'll only be prompted once. Run the
1468 following command, then logout of GNOME and log back in:
1471 gconftool-2 --set -t bool \
1472 /apps/gnome-keyring/daemon-components/ssh false
1475 After setting up your passphrase, your private key is saved as
1476 @file{~/.ssh/id_rsa} and your public key is saved as
1477 @file{~/.ssh/id_rsa.pub}.
1481 Register your public SSH @q{rsa} key with Savannah. From the
1482 @qq{My Account Configuration} page, click on @qq{Edit SSH Keys},
1483 then paste the contents of your @file{~/.ssh/id_rsa.pub} file into
1484 one of the @qq{Authorized keys} text fields, and click
1487 Savannah should respond with something like:
1490 Success: Key #1 seen Keys registered
1495 Configure Git to use the SSH protocol (instead of the GIT
1496 protocol). From your local Git repository, enter:
1499 git config remote.origin.url \
1500 ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1504 replacing @var{user} with your Savannah username.
1508 After your membership has been activated and you've configured Git
1509 to use SSH, test the connection with:
1515 SSH should issue the following warning:
1518 The authenticity of host 'git.sv.gnu.org (140.186.70.72)' can't
1520 RSA key fingerprint is
1521 80:5a:b0:0c:ec:93:66:29:49:7e:04:2b:fd:ba:2c:d5.
1522 Are you sure you want to continue connecting (yes/no)?
1525 Make sure the RSA key fingerprint displayed matches the one above.
1526 If it doesn't, respond @qq{no} and check that you configured Git
1527 properly in the previous step. If it does match, respond
1528 @qq{yes}. SSH should then issue another warning:
1531 Warning: Permanently added 'git.sv.gnu.org,140.186.70.72' (RSA) to
1532 the list of known hosts.
1535 The list of known hosts is stored in the file
1536 @file{~/.ssh/known_hosts}.
1538 At this point, you are prompted for your passphrase if you have
1539 one, then Git will attempt a pull.
1541 If @command{git@tie{}pull@tie{}--verbose} fails, you should see
1542 error messages like these:
1545 Permission denied (publickey).
1546 fatal: The remote end hung up unexpectedly
1549 If you get the above error, you may have made a mistake when
1550 registering your SSH key at Savannah. If the key is properly
1551 registered, you probably just need to wait for the Savannah server
1552 to activate it. It usually takes a few minutes for the key to be
1553 active after registering it, but if it still doesn't work after an
1554 hour, ask for help on the mailing list.
1556 If @command{git@tie{}pull@tie{}--verbose} succeeds, the output
1557 will include a @q{From} line that shows @q{ssh} as the protocol:
1560 From ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond
1563 If the protocol shown is not @q{ssh}, check that you configured
1564 Git properly in the previous step.
1568 Test your commit access with a dry run:
1571 git push --dry-run --verbose
1574 Note that recent versions of Git (Git 1.6.3 or later) will issue a
1575 big warning if the above command is used. The simplest solution
1576 is to tell Git to push all matching branches by default:
1579 git config push.default matching
1583 Then @code{git@tie{}push} should work as before. For more
1584 details, consult the @code{git@tie{}push} man page.
1588 Repeat the steps from generating an RSA key through to testing
1589 your commit access, for each machine from which you will be
1590 making commits, or you may simply copy the files from your
1591 local @file{~/.ssh} folder to the same folder on the other
1596 @subsubheading Technical details
1600 On Firefox, to view or remove the CAcert root certificate, go to:
1601 Edit > Preferences > Advanced > Encryption > View Certificates >
1602 Authorities > Certificate Name > Root CA > CA Cert Signing
1606 The @command{git@tie{}config} commands above should modify your
1607 local repository's @file{.git/config} file. These lines:
1611 url = git://git.sv.gnu.org/lilypond.git/
1615 should now be changed to:
1619 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1623 where @var{user} is your login name on Savannah.
1627 @command{git@tie{}config@tie{}push.default@tie{}matching} command
1628 should add these lines to @file{.git/config}:
1637 Encryption protocols, including ssh, generally do not permit packet
1638 fragmentation to avoid introducing a point of insecurity. This
1639 means that the maximum packet size must not exceed the smallest
1640 MTU (Maximum Transmission Unit) set in the routers along the path.
1641 This smallest MTU is determined by a procedure during call set-up
1642 which relies on the transmission over the path of ICMP packets.
1643 If any of the routers in the path block ICMP packets this mechanism
1644 fails, resulting in the possibility of packets being transmitted
1645 which exceed the MTU of one of the routers. If this happens the
1646 packet is discarded, causing the ssh session to hang, timeout or
1647 terminate with the error message
1650 ssh: connect to host <host ip addr> port 22: Bad file number
1651 fatal: The remote end hung up unexpectedly
1654 depending on precisely when in the proceedings the first large
1655 packet is transmitted. Most routers on the internet have MTU
1656 set to 1500, but routers installed in homes to connect via
1657 broadband may use a slightly smaller MTU for efficient transmission
1658 over ATM. If this problem is encountered a possible work-around is
1659 to set the MTU in the local router to 1500.
1661 @node Git on Windows
1662 @section Git on Windows
1664 @c Some of this may duplicate stuff in other sections
1665 @c But it is probably best for windows users to have it all together
1666 @c If necessary, clear this up later -td
1668 TODO: Decide what to do with this... Pare it down? Move
1669 paragraphs next to analogous Unix instructions? -mp
1671 @subsection Background to nomenclature
1673 Git is a system for tracking the changes made to source files by a
1674 distributed set of editors. It is designed to work without a
1675 master repository, but we have chosen to have a master repository
1676 for LilyPond files. Editors hold a local copy of the master
1677 repository together with any changes they have made locally.
1678 Local changes are held in a local @q{branch}, of which there may
1679 be several, but these instructions assume you are using just one.
1680 The files visible in the local repository always correspond to
1681 those on the currently @q{checked out} local branch.
1683 Files are edited on a local branch, and in that state the changes
1684 are said to be @q{unstaged}. When editing is complete, the
1685 changes are moved to being @q{staged for commit}, and finally the
1686 changes are @q{committed} to the local branch. Once committed,
1687 the changes (called a @q{commit}) are given a unique 40-digit
1688 hexadecimal reference number called the @q{Committish} or @q{SHA1
1689 ID} which identifies the commit to Git. Such committed changes
1690 can be sent to the master repository by @q{pushing} them (if you
1691 have write permission) or by sending them by email to someone who
1692 has, either as a complete file or as a @q{diff} or @q{patch}
1693 (which send just the differences from the master repository).
1695 @subsection Installing git
1698 @uref{http://code.google.com/p/msysgit/downloads/list} (note, not
1699 msysGit, which is for Git developers and not PortableGit, which is
1700 not a full git installation) and install it.
1702 Note that most users will not need to install SSH. That is not
1703 required until you have been granted direct push permissions to
1704 the master git repository.
1706 Start Git by clicking on the desktop icon. This will bring up a
1707 command line bash shell. This may be unfamiliar to Windows users.
1708 If so, follow these instructions carefully. Commands are entered
1709 at a $ prompt and are terminated by keying a newline.
1711 @subsection Initialising Git
1713 Decide where you wish to place your local Git repository, creating
1714 the folders in Windows as necessary. Here we call the folder to
1715 contain the repository @code{[path]/Git}, but if you intend using
1716 Git for other projects a directory name like @code{lilypond-git}
1717 might be better. You will need to have space for around
1720 Start the Git bash shell by clicking on the desk-top icon
1721 installed with Git and type
1727 to position the shell at your new Git repository.
1729 Note: if [path] contains folders with names containing spaces use
1741 to initialize your Git repository.
1743 Then type (all on one line; the shell will wrap automatically)
1746 git remote add -ft master origin git://git.sv.gnu.org/lilypond.git
1749 to download the lilypond master files.
1751 @warning{Be patient! Even on a broadband connection this can take
1752 10 minutes or more. Wait for lots of [new tag] messages and the $
1755 We now need to generate a local copy of the downloaded files in a
1756 new local branch. Your local branch needs to have a name. It is
1757 usual to call it @q{master} and we shall do that here.
1762 git checkout -b master origin/master
1765 This creates a second branch called @q{master}. You will see two
1766 warnings (ignore these), and a message advising you that your
1767 local branch @q{master} has been set up to track the remote
1768 branch. You now have two branches, a local branch called
1769 @q{master}, and a tracking branch called @q{origin/master}, which
1770 is a shortened form of @q{remotes/origin/master}.
1772 Return to Windows Explorer and look in your Git repository. You
1773 should see lots of folders. For example, the LilyPond
1774 documentation can be found in [path]/Git/Documentation/.
1776 The Git bash shell is terminated by typing @code{exit} or by
1777 clicking on the usual Windows close-window widget.
1781 Almost all subsequent work will use the Git Graphical User
1782 Interface, which avoids having to type command line commands. To
1783 start Git GUI first start the Git bash shell by clicking on the
1784 desktop icon, and type
1791 The Git GUI will open in a new window. It contains four panels
1792 and 7 pull-down menus. At this stage do not use any of the
1793 commands under Branch, Commit, Merge or Remote. These will be
1796 The top panel on the left contains the names of files which you
1797 are in the process of editing (Unstaged Changes), and the lower
1798 panel on the left contains the names of files you have finished
1799 editing and have staged ready for committing (Staged Changes). At
1800 present, these panels will be empty as you have not yet made any
1801 changes to any file. After a file has been edited and saved the
1802 top panel on the right will display the differences between the
1803 edited file selected in one of the panels on the left and the last
1804 version committed on the current branch.
1806 The panel at bottom right is used to enter a descriptive message
1807 about the change before committing it.
1809 The Git GUI is terminated by entering CNTL-Q while it is the
1810 active window or by clicking on the usual Windows close-window
1813 @subsection Personalising your local git repository
1815 Open the Git GUI, click on
1821 and enter your name and email address in the left-hand (Git
1822 Repository) panel. Leave everything else unchanged and save it.
1824 Note that Windows users must leave the default setting for line
1825 endings unchanged. All files in a git repository must have lines
1826 terminated by just a LF, as this is required for Merge to work,
1827 but Windows files are terminated by CRLF by default. The git
1828 default setting causes the line endings of files in a Windows git
1829 repository to be flipped automatically between LF and CRLF as
1830 required. This enables files to be edited by any Windows editor
1831 without causing problems in the git repository.
1833 @subsection Checking out a branch
1835 At this stage you have two branches in your local repository,
1836 both identical. To see them click on
1842 You should have one local branch called @q{master} and one
1843 tracking branch called @q{origin/master}. The latter is your
1844 local copy of the @q{remotes/origin/master} branch in the master
1845 LilyPond repository. The local @q{master} branch is where you
1846 will make your local changes.
1848 When a particular branch is selected, i.e., checked out, the files
1849 visible in your repository are changed to reflect the state of the
1850 files on that branch.
1852 @subsection Updating files from @q{remote/origin/master}
1854 Before starting the editing of a file, ensure your local
1855 repository contains the latest version of the files in the remote
1856 repository by first clicking
1859 Remote -> Fetch from -> origin
1865 This will place the latest version of every file, including all
1866 the changes made by others, into the @q{origin/master} branch of
1867 the tracking branches in your git repository. You can see these
1868 files by checking out this branch, but you must @emph{never} edit
1869 any files while this branch is checked out. Check out your local
1870 @q{master} branch again.
1872 You then need to merge these fetched files into your local
1873 @q{master} branch by clicking on
1876 Merge -> Local Merge
1880 and if necessary select the local @q{master} branch.
1882 Note that a merge cannot be completed if you have made any local
1883 changes which have not yet been committed.
1885 This merge will update all the files in the @q{master} branch to
1886 reflect the current state of the @q{origin/master} branch. If any
1887 of the changes conflict with changes you have made yourself
1888 recently you will be notified of the conflict (see below).
1890 @subsection Editing files
1892 First ensure your @q{master} branch is checked out, then simply
1893 edit the files in your local Git repository with your favourite
1894 editor and save them back there. If any file contains non-ASCII
1895 characters ensure you save it in UTF-8 format. Git will detect
1896 any changes whenever you restart Git GUI and the file names will
1897 then be listed in the Unstaged Changes panel. Or you can click
1898 the Rescan button to refresh the panel contents at any time. You
1899 may break off and resume editing any time.
1901 The changes you have made may be displayed in diff form in the top
1902 right-hand panel of Git GUI by clicking on the file name shown in
1903 one of the left panels.
1905 When your editing is complete, move the files from being Unstaged
1906 to Staged by clicking the document symbol to the left of each
1907 name. If you change your mind it can be moved back by clicking on
1908 the ticked box to the left of the name.
1910 Finally the changes you have made may be committed to your
1911 @q{master} branch by entering a brief message in the Commit
1912 Message box and clicking the Commit button.
1914 If you wish to amend your changes after a commit has been made,
1915 the original version and the changes you made in that commit may
1916 be recovered by selecting
1919 Commit -> Amend Last Commit
1923 or by checking the Amend Last Commit radio button at bottom right.
1924 This will return the changes to the Staged state, so further
1925 editing made be carried out within that commit. This must only be
1926 done @emph{before} the changes have been Pushed or sent to your
1927 mentor for Pushing - after that it is too late and corrections
1928 have to be made as a separate commit.
1931 @subsection Sending changes to @q{remotes/origin/master}
1933 If you do not have write access to @q{remotes/origin/master} you
1934 will need to send your changes by email to someone who does.
1936 First you need to create a diff or patch file containing your
1937 changes. To create this, the file must first be committed. Then
1938 terminate the Git GUI. In the git bash shell first cd to your Git
1945 if necessary, then produce the patch with
1948 git format-patch origin
1951 This will create a patch file for all the locally committed files
1952 which differ from @q{origin/master}. The patch file can be found
1953 in [path]/Git and will have a name formed from the commit message.
1955 @subsection Resolving merge conflicts
1957 As soon as you have committed a changed file your local
1958 @code{master} branch has diverged from @code{origin/master}, and
1959 will remain diverged until your changes have been committed in
1960 @code{remotes/origin/master} and Fetched back into your
1961 @code{origin/master} branch. Similarly, if a new commit has been
1962 made to @code{remotes/origin/master} by someone else and Fetched,
1963 your local @code{master} branch is divergent. You can detect a
1964 divergent branch by clicking on
1967 Repository -> Visualise all branch history
1970 This opens up a very useful new window called @q{gitk}. Use this
1971 to browse all the commits made by yourself and others.
1973 If the diagram at top left of the resulting window does not show
1974 your @code{master} tag on the same node as the
1975 @code{remotes/origin/master} tag your branch has diverged from
1976 @code{origin/master}. This is quite normal if files you have
1977 modified yourself have not yet been Pushed to
1978 @code{remotes/origin/master} and Fetched, or if files modified and
1979 committed by others have been Fetched since you last Merged
1980 @code{origin/master} into your local @code{master} branch.
1982 If a file being merged from @code{origin/master} differs from one
1983 you have modified in a way that cannot be resolved automatically
1984 by git, Merge will report a Conflict which you must resolve by
1985 editing the file to create the version you wish to keep.
1987 This could happen if the person updating
1988 @code{remotes/origin/master} for you has added some changes of his
1989 own before committing your changes to
1990 @code{remotes/origin/master}, or if someone else has changed the
1991 same file since you last fetched the file from
1992 @code{remotes/origin/master}.
1994 Open the file in your editor and look for sections which are
1997 [to be completed when I next have a merge conflict to be sure I
1998 give the right instructions -td]
2001 @subsection Other actions
2003 The instructions above describe the simplest way of using git on
2004 Windows. Other git facilities which may usefully supplement these
2008 @item Using multiple local branches (Create, Rename, Delete)
2009 @item Resetting branches
2010 @item Cherry-picking commits
2011 @item Pushing commits to @w{remote/origin/master}
2012 @item Using gitk to review history
2015 Once familiarity with using git on Windows has been gained the
2016 standard git manuals can be used to learn about these.
2019 @node Repository directory structure
2020 @section Repository directory structure
2023 @c TODO: integrate the roadmap better
2024 @verbatiminclude ROADMAP
2027 @node Other Git documentation
2028 @section Other Git documentation
2032 Official git man pages:
2033 @uref{http://www.kernel.org/pub/software/scm/git/docs/}
2036 More in-depth tutorials: @uref{http://git-scm.com/documentation}
2039 Book about git: @uref{http://progit.org/,Pro Git}