1 @c -*- coding: utf-8; mode: texinfo; -*-
4 @node Working with source code
5 @chapter Working with source code
7 New contributors should only read @ref{Using lily-git}. Please
8 ignore the rest of this chapter.
10 Advanced contributors will find the rest of this material quite
11 useful, particularly if they are working on major new features.
16 * Basic Git procedures::
17 * Advanced Git procedures::
19 * Repository directory structure::
20 * Other Git documentation::
25 @section Using lily-git
27 @subsubheading Install and Configuration
31 If you haven't already, download and install Git.
36 Lilybuntu users: git has already been installed for you.
38 @item Windows users: download the @code{.exe} file labeled
39 @qq{Full installer for official Git} from:
42 @uref{http://code.google.com/p/msysgit/downloads/list}
45 @item Other operating systems: either install @command{git} with
46 your package manager, or download it from the @qq{Binaries}
50 @uref{http://git-scm.com/download}
57 Download the lily-git script from:
59 @c don't change the cgit link below to gitweb; gitweb uses
60 @c long filenames like "scripts_auxiliar_lily-git.tcl"
63 @uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
67 To run the program from the command line, navigate to the
68 directory containing @file{lily-git.tcl} and enter:
77 @subsubheading 1. Get source / Update source
79 When you click the @qq{Get source} button, @command{lily-git} will
80 create a directory called @file{lilypond-git/} within your home
81 directory, and will download the source code into that
82 directory (around 55Mb). When the process is finished, the
83 @qq{Command output} window will display @qq{Done}, and the button
84 label will change to say @qq{Update source}.
86 Navigate to the @file{lilypond-git/} directory to view the source
87 files. You should now be able to modify the source files using
88 your normal text editor.
91 Advanced note: The @qq{Get source} button does not fetch the
92 entire history of the git repository, so utilities like
93 @command{gitk} will only be able to display the most recent
94 additions. As you continue to work with @command{lily-git}, the
95 @qq{Update source} button will take any new additions and add it
96 to whatever is currently in your repository's history.
100 @subsubheading 2a. New local commit
102 A single commit typically represents one logical set of related
103 changes (such as a bug-fix), and may incorporate changes to
104 multiple files at the same time.
106 When you're finished making the changes for your first commit,
107 click the @qq{New local commit} button. This will open the
108 @qq{Git Commit Message} window. The message header is required,
109 and the message body is optional. See @ref{Commits and patches}
110 for more information regarding commits and commit messages.
112 After entering a commit message, click @qq{OK} to finalize the
116 @subsubheading 2b. Amend previous commit
118 You can go back and make changes to the most recent commit with
119 the @qq{Amend previous commit} button. This is useful if a
120 mistake is found after you have clicked the @qq{New local commit}
123 To amend the most recent commit, re-edit the source files as
124 needed and then click the @qq{Amend previous commit} button. The
125 earlier version of the commit is not saved, but is replaced by the
128 Note that this does not update the patch @strong{files}; if you
129 have a patch file from an earlier version of the commit, you will
130 need to make another patch set when using this feature. The old
131 patch file will not be saved, but will be replaced by the new one
132 after you click on @qq{Make patch set}.
135 @subsubheading 3. Make patch set
137 Before making a patch set from any commits, you should click the
138 @qq{Update source} button to make sure the commits are based on
139 the most recent remote snapshot.
141 When you click the @qq{Make patch set} button, @command{lily-git}
142 will produce patch files for any new commits, saving them to the
143 current directory. The command output will display the name of
144 the new patch files near the end of the output:
147 0001-CG-add-lily-git-instructions.patch
151 Send patch files to your mentor if you have one. Otherwise, write
152 an email (must be less than 64 KB) to
153 @email{lilypond-devel@@gnu.org} briefly explaining your work, with
154 the patch files attached. Translators should send patches to
155 @email{translations@@lilynet.net}.
158 @subsubheading The @qq{Abort changes -- Reset to origin} button
160 @warning{Only use this if your local commit history gets
161 hopelessly confused!}
163 The button labeled @qq{Abort changes -- Reset to origin} will copy
164 all changed files to a subdirectory of @file{lilypond-git/} named
165 @file{aborted_edits/}, and will reset the repository to the
166 current state of the remote repository (at @code{git.sv.gnu.org}).
169 @node Starting with Git
170 @section Starting with Git
173 Using the Git program directly (as opposed to using the
174 @command{lily-git} GUI) allows you to have much greater control
175 over the contributing process. You should consider using Git if
176 you want to work on complex projects, or if you want to work on
177 multiple projects concurrently.
182 * Downloading remote branches::
187 @subsection Setting up
190 TODO: Remove this note if incorporating Windows instructions
191 throughout this section:
193 @warning{These instructions assume that you are using the
194 command-line version of Git 1.5 or higher. Windows users should
195 skip to @ref{Git on Windows}.}
199 * Initializing a repository::
205 @unnumberedsubsubsec Installing Git
208 If you are using a Unix-based machine, the easiest way to download
209 and install Git is through a package manager such as @command{rpm}
210 or @command{apt-get}---the installation is generally automatic.
211 The only required package is (usually) called @command{git-core},
212 although some of the auxiliary @command{git@var{*}} packages are
213 also useful (such as @command{gitk}).
215 Alternatively, you can visit the Git website
216 (@uref{http://git-scm.com/}) for downloadable binaries and
219 TODO: add Windows installation instructions (or @@ref@{Git on
223 @node Initializing a repository
224 @unnumberedsubsubsec Initializing a repository
227 Once Git is installed, you'll need to create a new directory where
228 your initial repository will be stored (the example below uses
229 @file{~/lilypond-git/}, where @code{~} represents your home
230 directory). Run @command{git@tie{}init} from within the new
231 directory to initialize an empty repository:
234 mkdir ~/lilypond-git/; cd ~/lilypond-git/
238 @subsubheading Technical details
240 This creates (within the @file{~/lilypond-git/} directory) a
241 subdirectory called @file{.git/}, which Git uses to keep track of
242 changes to the repository, among other things. Normally you don't
243 need to access it, but it's good to know it's there.
246 @node Configuring Git
247 @unnumberedsubsubsec Configuring Git
249 @warning{Throughout the rest of this manual, all command-line
250 input should be entered from the top directory of the Git
251 repository being discussed (eg. @file{~/lilypond-git/}). This is
252 referred to as a @emph{top source directory}.}
254 Before downloading a copy of the main LilyPond repository, you
255 should configure some basic settings with the
256 @command{git@tie{}config} command. Git allows you to set both
257 global and repository-specific options.
259 To configure settings that affect all repositories, use the
260 @command{--global} command line option. For example, the first
261 two options that you should always set are your @var{name} and
262 @var{email}, since Git needs these to keep track of commit
266 git config --global user.name "@var{John Smith}"
267 git config --global user.email @var{john@@example.com}
270 To configure Git to use colored output where possible, use:
273 git config --global color.ui auto
276 The text editor that opens when using @command{git@tie{}commit}
277 can also be changed. If none of your editor-related environment
278 variables are set ($GIT_EDITOR, $VISUAL, or $EDITOR), the default
279 editor is usually @command{vi} or @command{vim}. If you're not
280 familiar with either of these, you should probably change the
281 default to an editor that you know how to use. For example, to
282 change the default editor to @command{nano}, enter:
285 git config --global core.editor @var{nano}
288 TODO: Add instructions for changing the editor on Windows, which
289 is a little different, I think. -mp
291 @subsubheading Technical details
293 Git stores the information entered with
294 @command{git@tie{}config@tie{}--global} in the file
295 @file{.gitconfig}, located in your home directory. This file can
296 also be modified directly, without using
297 @command{git@tie{}config}. The @file{.gitconfig} file generated
298 by the above commands would look like this:
303 email = john@@example.com
310 Using the @command{git@tie{}config} command @emph{without} the
311 @command{--global} option configures repository-specific settings,
312 which are stored in the file @file{.git/config}. This file is
313 created when a repository is initialized (using
314 @command{git@tie{}init}), and by default contains these lines:
318 repositoryformatversion = 0
321 logallrefupdates = true
324 However, since different repository-specific options are
325 recommended for different development tasks, it is best to avoid
326 setting any now. Specific recommendations will be mentioned later
330 @node Downloading remote branches
331 @subsection Downloading remote branches
335 * Organization of remote branches::
336 * LilyPond repository sources::
337 * Downloading individual branches::
338 * Downloading all remote branches::
343 @node Organization of remote branches
344 @unnumberedsubsubsec Organization of remote branches
347 The main LilyPond repository is organized into @emph{branches} to
348 facilitate development. These are often called @emph{remote}
349 branches to distinguish them from @emph{local} branches you might
350 create yourself (see @ref{Using local branches}).
352 The @code{master} branch contains all the source files used to
353 build LilyPond, which includes the program itself (both stable and
354 development releases), the documentation (and its translations),
355 and the website. Generally, the @code{master} branch is expected
356 to compile successfully.
358 The @code{lilypond/translation} branch is a side branch that
359 allows translators to work without needing to worry about
360 compilation problems. Periodically, the Translation Meister
361 (after verifying that it doesn't break compilation), will
362 @emph{merge} this branch back into @code{master} to incorporate
363 recent translations. Similarly, the @code{master} branch is
364 usually merged into the @code{lilypond/translation} branch after
365 significant changes to the English documentation. See
366 @ref{Translating the documentation} for details.
369 @node LilyPond repository sources
370 @unnumberedsubsubsec LilyPond repository sources
373 The recommended source for downloading a copy of the main
377 git://git.sv.gnu.org/lilypond.git
380 However, if your internet router filters out connections using the
381 GIT protocol, or if you experience difficulty connecting via GIT,
382 you can try these other sources:
385 ssh://git.sv.gnu.org/srv/git/lilypond.git
386 http://git.sv.gnu.org/r/lilypond.git
389 The SSH protocol can only be used if your system is properly set
390 up to use it. Also, the HTTP protocol is slowest, so it should
391 only be used as a last resort.
394 @node Downloading individual branches
395 @unnumberedsubsubsec Downloading individual branches
398 Once you have initialized an empty Git repository on your system
399 (see @ref{Initializing a repository}), you can download a remote
400 branch into it. Make sure you know which branch you want to start
403 To download the @code{master} branch, enter the following:
406 git remote add -ft master -m master \
407 origin git://git.sv.gnu.org/lilypond.git/
410 To download the @code{lilypond/translation} branch, enter:
413 git remote add -ft lilypond/translation -m \
414 lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
417 The @command{git@tie{}remote@tie{}add} process could take up to
418 ten minutes, depending on the speed of your connection. The
419 output will be something like this:
423 remote: Counting objects: 235967, done.
424 remote: Compressing objects: 100% (42721/42721), done.
425 remote: Total 235967 (delta 195098), reused 233311 (delta 192772)
426 Receiving objects: 100% (235967/235967), 68.37 MiB | 479 KiB/s, done.
427 Resolving deltas: 100% (195098/195098), done.
428 From git://git.sv.gnu.org/lilypond
429 * [new branch] master -> origin/master
430 From git://git.sv.gnu.org/lilypond
431 * [new tag] flower/1.0.1 -> flower/1.0.1
432 * [new tag] flower/1.0.10 -> flower/1.0.10
434 * [new tag] release/2.9.6 -> release/2.9.6
435 * [new tag] release/2.9.7 -> release/2.9.7
438 When @command{git@tie{}remote@tie{}add} is finished, the remote
439 branch should be downloaded into your repository---though not yet
440 in a form that you can use. In order to browse the source code
441 files, you need to @emph{create} and @emph{checkout} your own
442 local branch. In this case, however, it is easier to have Git
443 create the branch automatically by using the @command{checkout}
444 command on a non-existent branch. Enter the following:
447 git checkout -b @var{branch} origin/@var{branch}
451 where @code{@var{branch}} is the name of your tracking branch,
452 either @code{master} or @code{lilypond/translation}.
454 Git will issue some warnings; this is normal:
457 warning: You appear to be on a branch yet to be born.
458 warning: Forcing checkout of origin/master.
459 Branch master set up to track remote branch master from origin.
463 By now the source files should be accessible---you should be able
464 to edit any files in the @file{lilypond-git/} directory using a
465 text editor of your choice. But don't start just yet! Before
466 editing any source files, learn how to keep your changes organized
467 and prevent problems later---read @ref{Basic Git procedures}.
469 @subsubheading Technical Details
471 The @command{git@tie{}remote@tie{}add} command should add some
472 lines to your local repository's @file{.git/config} file:
476 url = git://git.sv.gnu.org/lilypond.git/
477 fetch = +refs/heads/master:refs/remotes/origin/master
481 @node Downloading all remote branches
482 @unnumberedsubsubsec Downloading all remote branches
485 To download all remote branches at once, you can @command{clone}
486 the entire repository:
489 git clone git://git.sv.gnu.org/lilypond.git
494 @unnumberedsubsubsec Other branches
496 Most contributors will never need to touch the other branches. If
497 you wish to do so, you will need more familiarity with Git; please
498 see @ref{Other Git documentation}.
501 @item @code{dev/XYZ}:
502 These branches are for individual developers. They store code
503 which is not yet stable enough to be added to the @code{master}
506 @item @code{stable/XYZ}:
507 The branches are kept for archival reasons.
511 Another item of interest might be the Grand Unified Builder, our
512 cross-platform building tool. Since it is used by projects as
513 well, it is not stored in our gub repository. For more info, see
514 @uref{http://lilypond.org/gub}. The git location is
515 @uref{http://github.com/janneke/gub}.
518 @node Basic Git procedures
519 @section Basic Git procedures
523 * The Git contributor's cycle::
524 * Pulling and rebasing::
525 * Using local branches::
526 * Commits and patches::
530 @node The Git contributor's cycle
531 @subsection The Git contributor's cycle
534 Here is a simplified view of the contribution process on Git:
538 Update your local repository by @emph{pulling} the most recent
539 updates from the remote repository.
542 Edit source files within your local repository's @emph{working
546 @emph{Commit} the changes you've made to a local @emph{branch}.
549 Generate a @emph{patch} to share your changes with the developers.
553 @node Pulling and rebasing
554 @subsection Pulling and rebasing
557 When developers push new patches to the @code{git.sv.gnu.org}
558 repository, your local repository is @strong{not} automatically
559 updated. It is important to keep your repository up-to-date by
560 periodically @emph{pulling} the most recent @emph{commits} from
561 the remote branch. Developers expect patches to be as current as
562 possible, since outdated patches require extra work before they
565 Occasionally you may need to rework some of your own modifications
566 to match changes made to the remote branch (see @ref{Resolving
567 conflicts}), and it's considerably easier to rework things
568 incrementally. If you don't update your repository along the way,
569 you may have to spend a lot of time resolving branch conflicts and
570 reconfiguring much of the work you've already done.
572 Fortunately, Git is able to resolve certain types of branch
573 conflicts automatically with a process called @emph{rebasing}.
574 When rebasing, Git tries to modify your old commits so they appear
575 as new commits (based on the latest updates). For a more involved
576 explanation, see the @command{git-rebase} man page.
578 To pull without rebasing (recommended for translators), use the
582 git pull # recommended for translators
585 If you're tracking the remote @code{master} branch, you should add
586 the @code{-r} option (short for @code{--rebase}) to keep commits
587 on your local branch current:
590 git pull -r # use with caution when translating
593 If you don't edit translated documentation and don't want to type
594 @code{-r} every time, configure the master branch to rebase by
595 default with this command:
598 git config branch.master.rebase true
601 If pull fails because of a message like
604 error: Your local changes to 'Documentation/learning/tutorial.itely'
605 would be overwritten by merge. Aborting.
612 Documentation/learning/tutorial.itely: needs update
613 refusing to pull with rebase: your working tree is not up-to-date
617 it means that you have modified some files in you working tree
618 without committing changes (see @ref{Commits and patches}); you
619 can use the @command{git@tie{}stash} command to work around this:
622 git stash # save uncommitted changes
623 git pull -r # pull using rebase (translators omit "-r")
624 git stash pop # reapply previously saved changes
627 Note that @command{git@tie{}stash@tie{}pop} will try to apply a
628 patch, and this may create a conflict. If this happens, see
629 @ref{Resolving conflicts}.
631 TODO: I think the next paragraph is confusing. Perhaps prepare
632 the reader for new terms `committish' and `head'? -mp
634 @warning{translators and documentation editors, if you have
635 changed committishes in the head of translated files using commits
636 you have not yet pushed to @code{git.sv.gnu.org}, please do not
637 rebase. If you want to avoid wondering whether you should rebase
638 each time you pull, please always use committishes from master
639 and/or lilypond/translation branch on @code{git.sv.gnu.org}, which
640 in particular implies that you must push your changes to
641 documentation except committishes updates (possibly after having
642 rebased), then update the committishes and push them.}
644 TODO: when committishes automatic conditional update have been
645 tested and documented, append the following to the warning above:
646 Note that using update-committishes make target generally touches
649 @subsubheading Technical details
651 The @command{git@tie{}config} command mentioned above adds the
652 line @code{rebase = true} to the master branch in your local
653 repository's @file{.git/config} file:
658 merge = refs/heads/master
663 @node Using local branches
664 @subsection Using local branches
668 * Creating and removing branches::
669 * Listing branches and remotes::
670 * Checking out branches::
675 @node Creating and removing branches
676 @unnumberedsubsubsec Creating and removing branches
679 Local branches are useful when you're working on several different
680 projects concurrently. To create a new branch, enter:
683 git branch @var{name}
686 To delete a branch, enter:
689 git branch -d @var{name}
692 Git will ask you for confirmation if it sees that data would be
693 lost by deleting the branch. Use @code{-D} instead of @code{-d}
694 to bypass this. Note that you cannot delete a branch if it is
695 currently checked out.
698 @node Listing branches and remotes
699 @unnumberedsubsubsec Listing branches and remotes
701 You can get the exact path or URL of all remote branches by
708 To list Git branches on your local repositories, run
711 git branch # list local branches only
712 git branch -r # list remote branches
713 git branch -a # list all branches
717 @node Checking out branches
718 @unnumberedsubsubsec Checking out branches
720 To know the currently checked out branch, i.e. the branch whose
721 source files are present in your working tree, read the first line
729 The currently checked out branch is also marked with an asterisk
730 in the output of @command{git branch}.
732 You can check out another branch @code{@var{other_branch}}, i.e.
733 check out @code{@var{other_branch}} to the working tree, by
737 git checkout @var{other_branch}
740 Note that it is possible to check out another branch while having
741 uncommitted changes, but it is not recommended unless you know
742 what you are doing; it is recommended to run @command{git status}
743 to check this kind of issue before checking out another branch.
745 @node Merging branches
746 @unnumberedsubsubsec Merging branches
748 To merge branch @code{@var{foo}} into branch @code{@var{bar}},
749 i.e. to @qq{add} all changes made in branch @code{@var{foo}} to
750 branch @code{@var{bar}}, run
753 git checkout @var{bar}
757 If any conflict happens, see @ref{Resolving conflicts}.
759 There are common usage cases for merging: as a translator, you
760 will often want to merge @code{master} into
761 @code{lilypond/translation}; on the other hand, the Translations
762 meister wants to merge @code{lilypond/translation} into
763 @code{master} whenever he has checked that
764 @code{lilypond/translation} builds successfully.
767 @node Commits and patches
768 @subsection Commits and patches
772 * Understanding commits::
776 * Uploading a patch for review::
780 @node Understanding commits
781 @unnumberedsubsubsec Understanding commits
783 Technically, a @emph{commit} is a single point in the history of a
784 branch, but most developers use the term to mean a @emph{commit
785 object}, which stores information about a particular revision. A
786 single commit can record changes to multiple source files, and
787 typically represents one logical set of related changes (such as a
788 bug-fix). You can list the ten most recent commits in your
789 current branch with this command:
792 git log -10 --oneline
795 If you're using an older version of Git and get an @q{unrecognized
796 argument} error, use this instead:
799 git log -10 --pretty=oneline --abbrev-commit
802 More interactive lists of the commits on the remote @code{master}
803 branch are available at
804 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=shortlog} and
805 @uref{http://git.sv.gnu.org/cgit/lilypond.git/log/}.
809 @unnumberedsubsubsec Making commits
812 Once you have modified some source files in your working
813 directory, you can make a commit with the following procedure:
817 Make sure you've configured Git properly (see @ref{Configuring
818 Git}). Check that your changes meet the requirements described in
819 @ref{Code style} and/or @ref{Documentation policy}. For advanced
820 edits, you may also want to verify that the changes don't break
821 the compilation process.
824 Run the following command:
831 to make sure you're on the right branch, and to see which files
832 have been modified, added or removed, etc. You may need to tell
833 Git about any files you've added by running one of these:
836 git add @var{file} # add untracked @var{file} individually
837 git add . # add all untracked files in current directory
841 After @command{git@tie{}add}, run @command{git@tie{}status} again
842 to make sure you got everything. You may also need to modify
846 Preview the changes about to be committed (to make sure everything
854 The @code{HEAD} argument refers to the most recent commit on the
855 currently checked-out branch.
858 Generate the commit with:
865 The @code{-a} is short for @code{--all} which includes modified
866 and deleted files, but only those newly created files that have
867 previously been added.
872 @node Commit messages
873 @unnumberedsubsubsec Commit messages
876 When you run the @command{git@tie{}commit@tie{}-a} command, Git
877 automatically opens the default text editor so you can enter a
878 @emph{commit message}. If you find yourself in a foreign editing
879 environment, you're probably in @command{vi} or @command{vim}. If
880 you want to switch to an editor you're more familiar with, quit by
881 typing @code{:q!} and pressing @code{<Enter>}. See
882 @ref{Configuring Git} for instructions on changing the default
885 In any case, Git will open a text file for your commit message
886 that looks like this:
890 # Please enter the commit message for your changes. Lines starting
891 # with '#' will be ignored, and an empty message aborts the commit.
893 # Changes to be committed:
894 # (use "git reset HEAD <file>..." to unstage)
896 # modified: working.itexi
900 Your commit message should begin with a one-line summary
901 describing the change (no more than 50 characters long), and if
902 necessary a blank line followed by several lines giving the
905 @c $ git log -1 --pretty=medium 4d6f1e5
907 Doc: add Baerenreiter and Henle solo cello suites
909 Added comparison of solo cello suite engravings to new essay with
910 high-res images, fixed cropping on Finale example.
913 Commit messages often start with a short prefix describing the
914 general location of the changes. If a commit affects the
915 documentation in English (or in several languages simultaneously)
916 the commit message should be prefixed with @qq{Doc:@tie{}}. If
917 the commit affects only one of the translations, the commit
918 message should be prefixed with @qq{Doc-@var{**}:@tie{}}, where
919 @var{**} is the two-letter language code. Commits that affect the
920 website should use @qq{Web:@tie{}} for English, and
921 @qq{Web-@var{**}:@tie{}} for the other languages. Also, changes
922 to a single file are often prefixed with the name of the file
923 involved. Visit the links listed in @ref{Understanding commits}
928 @unnumberedsubsubsec Making patches
930 If you want to share your changes with other contributors and
931 developers, you need to generate @emph{patches} from your commits.
932 We prefer it if you follow the instructions in
933 @ref{Uploading a patch for review}. However, we present an
934 alternate method here.
936 You should always run @command{git@tie{}pull@tie{}-r} (translators
937 should leave off the @code{-r}) before doing this to ensure that
938 your patches are as current as possible.
940 Once you have made one or more commits in your local repository,
941 and pulled the most recent commits from the remote branch, you can
942 generate patches from your local commits with the command:
945 git format-patch origin
948 The @code{origin} argument refers to the remote tracking branch at
949 @code{git.sv.gnu.org}. This command generates a separate patch
950 for each commit that's in the current branch but not in the remote
951 branch. Patches are placed in the current working directory and
952 will have names that look something like this:
955 0001-Doc-Fix-typos.patch
956 0002-Web-Remove-dead-links.patch
960 Send an email (must be less than 64 KB) to
961 @email{lilypond-devel@@gnu.org} briefly explaining your work, with
962 the patch files attached. Translators should send patches to
963 @email{translations@@lilynet.net}. After your patches are
964 reviewed, the developers may push one or more of them to the main
965 repository or discuss them with you.
968 @node Uploading a patch for review
969 @unnumberedsubsubsec Uploading a patch for review
971 Any non-trivial change should be uploaded to our @qq{Rietveld}
975 @uref{http://codereview.appspot.com/}
978 @subsubheading Initial setup
980 This requires the use of an external package, git-cl, and an email
983 @command{git-cl} is installed by:
986 git clone git://neugierig.org/git-cl.git
989 Then, add the @file{git-cl} directory to your PATH, or create a
990 symbolic link to the @command{git-cl} and @command{upload.py} in
991 one of your PATH directories (like @file{usr/bin}). Then
992 configure the program by running:
999 in the LilyPond git directory and answering the questions that
1000 are asked. If you do not understand the question answer with just
1003 @subsubheading Uploading patch set
1005 There are two methods, depending on your git setup.
1009 @strong{Separate branch}:
1011 Ensure your changes are committed in a separate branch, which
1012 should differ from the reference branch to be used by just the
1013 changes to be uploaded. If the reference branch is to be
1014 origin/master, ensure this is up-to-date. If necessary, use git
1015 rebase to rebase the branch containing the changes to the head of
1016 origin/master. Finally, check out branch with the changes and
1020 git cl upload <reference SHA1 ID>
1024 where <reference SHA1 ID> is the SHA1 ID of the commit to be used
1025 as a reference source for the patch. Generally, this will be the
1026 SHA1 ID of origin/master, and in that case the command:
1029 git cl upload origin/master
1036 @strong{Master branch}:
1038 If you added your patch to @code{master}, then make sure that you
1039 are up-to-date (by running @code{git pull -r}), and then run:
1042 git cl upload origin/master
1045 If you have git push ability, make sure that you @emph{remove}
1046 your patch (with @command{git rebase} or @command{git reset})
1047 before pushing other stuff.
1051 After prompting for your Google email address and password, the
1052 patch set will be posted to Rietveld.
1054 @subsubheading Announcing your patch set
1056 You should then announce the patch by sending an email to
1057 @code{lilypond-devel}, with a subject line starting with PATCH:,
1058 asking for comments on the patch. Alternately, you may Publish +
1059 Mail a (bogus) comment, in order to send an email to
1062 @subsubheading Revisions
1064 As revisions are made in response to comments, successive patch sets
1065 for the same issue can be uploaded by reissuing the git-cl command
1066 with the modified branch checked out.
1068 Sometimes in response to comments on revisions, the best way to
1069 work may require creation of a new branch in git. In order to
1070 associate the new branch with an existing Rietveld issue,
1071 the following command can be used:
1074 git cl issue issue-number
1078 where @code{issue-number} is the number of the existing Rietveld
1081 @subsubheading Resetting git cl
1083 If @command{git cl} becomes confused, you can @qq{reset} it by
1091 @node Advanced Git procedures
1092 @section Advanced Git procedures
1095 @warning{This section is not necessary for normal contributors;
1096 these commands are presented for information for people interested
1097 in learning more about git.}
1099 It is possible to work with several branches on the same local Git
1100 repository; this is especially useful for translators who may have
1101 to deal with both @code{lilypond/translation} and a stable branch,
1102 e.g. @code{stable/2.12}.
1104 Some Git commands are introduced first, then a workflow with
1105 several Git branches of LilyPond source code is presented.
1109 * Advanced Git concepts::
1110 * Resolving conflicts::
1111 * Reverting all local changes::
1112 * Working with remote branches::
1114 * Applying remote patches::
1115 * Sending and receiving patches via email::
1120 @node Advanced Git concepts
1121 @subsection Advanced Git concepts
1124 A bit of Git vocabulary will be explained below. The following is
1125 only introductory; for a better understanding of Git concepts, you
1126 may wish to read @ref{Other Git documentation}.
1128 The @code{git@tie{}pull@tie{}origin} command above is just a
1129 shortcut for this command:
1132 git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
1136 where @code{@var{branch}} is typically @code{master} or
1137 @code{lilypond/translation}; if you do not know or remember, see
1138 @ref{Downloading remote branches} to remember which commands you
1139 issued or which source code you wanted to get.
1141 A @emph{commit} is a set of changes made to the sources; it also
1142 includes the committish of the parent commit, the name and e-mail
1143 of the @emph{author} (the person who wrote the changes), the name
1144 and e-mail of the @emph{committer} (the person who brings these
1145 changes into the Git repository), and a commit message.
1147 A @emph{committish} is the SHA1 checksum of a commit, a number
1148 made of 40 hexadecimal digits, which acts as the internal unique
1149 identifier for this commit. To refer to a particular revision,
1150 don't use vague references like the (approximative) date, simply
1151 copy and paste the committish.
1153 A @emph{branch} is nothing more than a pointer to a particular
1154 commit, which is called the @emph{head} of the branch; when
1155 referring to a branch, one often actually thinks about its head
1156 and the ancestor commits of the head.
1158 Now we will explain the two last commands you used to get the
1159 source code from Git---see @ref{Downloading individual branches}.
1162 git remote add -ft @var{branch} -m @var{branch} \
1163 origin git://git.sv.gnu.org/lilypond.git/
1165 git checkout -b @var{branch} origin/@var{branch}
1168 The @command{git@tie{}remote} has created a branch called
1169 @code{origin/@var{branch}} in your local Git repository. As this
1170 branch is a copy of the remote branch web from git.sv.gnu.org
1171 LilyPond repository, it is called a @emph{remote branch}, and is
1172 meant to track the changes on the branch from git.sv.gnu.org: it
1173 will be updated every time you run
1174 @command{git@tie{}pull@tie{}origin} or
1175 @command{git@tie{}fetch@tie{}origin}.
1177 The @command{git@tie{}checkout} command has created a branch named
1178 @code{@var{branch}}. At the beginning, this branch is identical
1179 to @code{origin/@var{branch}}, but it will differ as soon as you
1180 make changes, e.g. adding newly translated pages or editing some
1181 documentation or code source file. Whenever you pull, you merge
1182 the changes from @code{origin/@var{branch}} and
1183 @code{@var{branch}} since the last pulling. If you do not have
1184 push (i.e. @qq{write}) access on git.sv.gnu.org, your
1185 @code{@var{branch}} will always differ from
1186 @code{origin/@var{branch}}. In this case, remember that other
1187 people working like you with the remote branch @code{@var{branch}}
1188 of git://git.sv.gnu.org/lilypond.git/ (called
1189 @code{origin/@var{branch}} on your local repository) know nothing
1190 about your own @code{@var{branch}}: this means that whenever you
1191 use a committish or make a patch, others expect you to take the
1192 latest commit of @code{origin/@var{branch}} as a reference.
1194 Finally, please remember to read the man page of every Git command
1195 you will find in this manual in case you want to discover
1196 alternate methods or just understand how it works.
1199 @node Resolving conflicts
1200 @subsection Resolving conflicts
1203 Occasionally an update may result in conflicts -- this happens
1204 when you and somebody else have modified the same part of the same
1205 file and git cannot figure out how to merge the two versions
1206 together. When this happens, you must manually merge the two
1209 If you need some documentation to understand and resolve
1210 conflicts, see paragraphs @emph{How conflicts are presented} and
1211 @emph{How to resolve conflicts} in @command{git merge} man page.
1213 If all else fails, you can follow the instructions in
1214 @ref{Reverting all local changes}. Be aware that this eliminates
1215 any changes you have made!
1218 @node Reverting all local changes
1219 @subsection Reverting all local changes
1221 Sometimes git will become hopelessly confused, and you just want
1222 to get back to a known, stable state. This command destroys any
1223 local changes you have made, but at least you get back to the
1224 current online version:
1227 git reset --hard origin/master
1231 @node Working with remote branches
1232 @subsection Working with remote branches
1235 @subsubheading Fetching new branches from git.sv.gnu.org
1237 To fetch and check out a new branch named @code{@var{branch}} on
1238 git.sv.gnu.org, run from top of the Git repository
1241 git config --add remote.origin.fetch \
1242 +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
1244 git checkout --track -b @var{branch} origin/@var{branch}
1247 After this, you can pull @code{@var{branch}} from git.sv.gnu.org
1254 Note that this command generally fetches all branches you added
1255 with @command{git@tie{}remote@tie{}add} (when you initialized the
1256 repository) or @command{git@tie{}config@tie{}--add}, i.e. it
1257 updates all remote branches from remote @code{origin}, then it
1258 merges the remote branch tracked by the current branch into the
1259 current branch. For example, if your current branch is
1260 @code{master}, @code{origin/master} will be merged into
1264 @subsubheading Local clones, or having several working trees
1266 If you play with several Git branches, e.g. @code{master},
1267 @code{lilypond/translation}, @code{stable/2.12}), you may want to
1268 have one source and build tree for each branch; this is possible
1269 with subdirectories of your local Git repository, used as local
1270 cloned subrepositories. To create a local clone for the branch
1271 named @code{@var{branch}}, run
1274 git checkout @var{branch}
1275 git clone -lsn . @var{subdir}
1280 Note that @code{@var{subdir}} must be a directory name which does
1281 not already exist. In @code{@var{subdir}}, you can use all Git
1282 commands to browse revisions history, commit and uncommit changes;
1283 to update the cloned subrepository with changes made on the main
1284 repository, cd into @code{@var{subdir}} and run
1285 @command{git@tie{}pull}; to send changes made on the subrepository
1286 back to the main repository, run @command{git@tie{}push} from
1287 @code{@var{subdir}}. Note that only one branch (the currently
1288 checked out branch) is created in the subrepository by default; it
1289 is possible to have several branches in a subrepository and do
1290 usual operations (checkout, merge, create, delete...) on these
1291 branches, but this possibility is not detailed here.
1293 When you push @code{@var{branch}} from @code{@var{subdir}} to the
1294 main repository, and @code{@var{branch}} is checked out in the
1295 main repository, you must save uncommitted changes (see
1296 @command{git@tie{}stash}) and do
1297 @command{git@tie{}reset@tie{}--hard} in the main repository in
1298 order to apply pushed changes in the working tree of the main
1306 The commands above don't only bring you the latest version of the
1307 sources, but also the full history of revisions (revisions, also
1308 called commits, are changes made to the sources), stored in the
1309 @file{.git} directory. You can browse this history with
1312 git log # only shows the logs (author, committish and commit message)
1313 git log -p # also shows diffs
1314 gitk # shows history graphically
1317 @warning{The @code{gitk} command may require a separate
1318 @code{gitk} package, available in the appropriate distribution's
1322 @node Applying remote patches
1323 @subsection Applying remote patches
1326 TODO: Explain how to determine if a patch was created with
1327 @code{git@tie{}format-patch}.
1329 Well-formed git patches created with @code{git@tie{}format-patch}
1330 should be committed with the following command:
1336 Patches created without @code{git@tie{}format-patch} can be
1337 applied in two steps. The first step is to apply the patch to the
1341 git apply @var{patch}
1345 The second step is to commit the changes and give credit to the
1346 author of the patch. This can be done with the following command:
1349 git commit -a --author="@var{John Smith} <@var{john@@example.com}>"
1353 @node Sending and receiving patches via email
1354 @subsection Sending and receiving patches via email
1357 The default @code{x-diff} MIME type associated with patch files
1358 (i.e., files whose name ends in @code{.patch}) means that the
1359 encoding of line endings may be changed from UNIX to DOS format
1360 when they are sent as attachments. Attempting to apply such an
1361 inadvertently altered patch will cause git to fail with a message
1362 about @q{whitespace errors}.
1364 The solution to such problems is surprisingly simple---just change
1365 the default file extension of patches generated by git to end in
1366 @code{.txt}, for example:
1369 git config format.suffix '.patch.txt'
1372 This should cause email programs to apply the correct base64
1373 encoding to attached patches.
1375 If you receive a patch with DOS instead of UNIX line-endings, it
1376 can be converted back using the @code{dos2unix} utility.
1378 Lots of useful information on email complications with patches is
1379 provided on the Wine wiki at
1380 @uref{http://wiki.winehq.org/GitWine}.
1384 @subsection Commit access
1387 Most contributors are not able to commit patches directly to the
1388 main repository---only members of the LilyPond development team
1389 have @emph{commit access}. If you are a contributor and are
1390 interested in joining the development team, contact the Project
1391 Manager through the mailing list
1392 (@email{lilypond-devel@@gnu.org}). Generally, only contributors
1393 who have already provided a number of patches which have been
1394 pushed to the main repository will be considered for membership.
1396 If you have been approved by the Project Manager, use the
1397 following procedure to obtain commit access:
1401 If you don't already have one, set up a Savannah user account at
1402 @uref{https://savannah.gnu.org/account/register.php}. If your web
1403 browser responds with an @qq{untrusted connection} message when
1404 you visit the link, follow the steps for including the CAcert root
1405 certificate in your browser, given at
1406 @uref{http://savannah.gnu.org/tls/tutorial/}.
1410 After registering, if you are not logged in automatically, login
1411 at @uref{https://savannah.gnu.org/account/login.php}---this should
1412 take you to your @qq{my} page
1413 (@uref{https://savannah.gnu.org/my/}).
1417 Click on the @qq{My Groups} link to access the @qq{My Group
1418 Membership} page. From there, find the @qq{Request for Inclusion}
1419 box and search for @qq{LilyPond}. Among the search results, check
1420 the box labeled @qq{GNU LilyPond Music Typesetter} and write a
1421 brief (required) message for the Project Manager (@qq{Hey it's
1422 me!} should be fine).
1424 Note that you will not have commit access until the Project
1425 Manager activates your membership. Once your membership is
1426 activated, LilyPond should appear under the heading @qq{Groups I'm
1427 Contributor of} on your @qq{My Group Membership} page.
1431 Generate an SSH @q{dsa} key pair. Enter the following at the
1438 When prompted for a location to save the key, press <ENTER> to
1439 accept the default location (@file{~/.ssh/id_dsa}).
1441 Next you are asked to enter an optional passphrase. On most
1442 systems, if you use a passphrase, you will likely be prompted for
1443 it every time you use @command{git@tie{}push} or
1444 @command{git@tie{}pull}. You may prefer this since it can protect
1445 you from your own mistakes (like pushing when you mean to pull),
1446 though you may find it tedious to keep re-entering it.
1448 You can change/enable/disable your passphrase at any time with:
1451 ssh-keygen -f ~/.ssh/id_dsa -p
1454 Note that the GNOME desktop has a feature which stores your
1455 passphrase for you for an entire GNOME session. If you use a
1456 passphrase to @qq{protect you from yourself}, you will want to
1457 disable this feature, since you'll only be prompted once. Run the
1458 following command, then logout of GNOME and log back in:
1461 gconftool-2 --set -t bool \
1462 /apps/gnome-keyring/daemon-components/ssh false
1465 After setting up your passphrase, your private key is saved as
1466 @file{~/.ssh/id_dsa} and your public key is saved as
1467 @file{~/.ssh/id_dsa.pub}.
1471 Register your public SSH @q{dsa} key with Savannah. From the
1472 @qq{My Account Configuration} page, click on @qq{Edit SSH Keys},
1473 then paste the contents of your @file{~/.ssh/id_dsa.pub} file into
1474 one of the @qq{Authorized keys} text fields, and click
1477 Savannah should respond with something like:
1480 Success: Key #1 seen Keys registered
1485 Configure Git to use the SSH protocol (instead of the GIT
1486 protocol). From your local Git repository, enter:
1489 git config remote.origin.url \
1490 ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1494 where @var{user} is your username on Savannah.
1498 After your membership has been activated and you've configured Git
1499 to use SSH, test the connection with:
1505 SSH should issue the following warning:
1508 The authenticity of host 'git.sv.gnu.org (140.186.70.72)' can't
1510 RSA key fingerprint is
1511 80:5a:b0:0c:ec:93:66:29:49:7e:04:2b:fd:ba:2c:d5.
1512 Are you sure you want to continue connecting (yes/no)?
1515 Make sure the RSA key fingerprint displayed matches the one above.
1516 If it doesn't, respond @qq{no} and check that you configured Git
1517 properly in the previous step. If it does match, respond
1518 @qq{yes}. SSH should then issue another warning:
1521 Warning: Permanently added 'git.sv.gnu.org,140.186.70.72' (RSA) to
1522 the list of known hosts.
1525 The list of known hosts is stored in the file
1526 @file{~/.ssh/known_hosts}.
1528 At this point, you are prompted for your passphrase if you have
1529 one, then Git will attempt a pull.
1531 If @command{git@tie{}pull@tie{}--verbose} fails, you should see
1532 error messages like these:
1535 Permission denied (publickey).
1536 fatal: The remote end hung up unexpectedly
1539 If you get the above error, you may have made a mistake when
1540 registering your SSH key at Savannah. If the key is properly
1541 registered, you probably just need to wait for the Savannah server
1542 to activate it. It usually takes a few minutes for the key to be
1543 active after registering it, but if it still doesn't work after an
1544 hour, ask for help on the mailing list.
1546 If @command{git@tie{}pull@tie{}--verbose} succeeds, the output
1547 will include a @q{From} line that shows @q{ssh} as the protocol:
1550 From ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond
1553 If the protocol shown is not @q{ssh}, check that you configured
1554 Git properly in the previous step.
1558 Test your commit access with a dry run:
1561 git push --dry-run --verbose
1564 Note that recent versions of Git (Git 1.6.3 or later) will issue a
1565 big warning if the above command is used. The simplest solution
1566 is to tell Git to push all matching branches by default:
1569 git config push.default matching
1573 Then @code{git@tie{}push} should work as before. For more
1574 details, consult the @code{git@tie{}push} man page.
1578 @subsubheading Technical details
1582 On Firefox, to view or remove the CAcert root certificate, go to:
1583 Edit > Preferences > Advanced > Encryption > View Certificates >
1584 Authorities > Certificate Name > Root CA > CA Cert Signing
1588 The @command{git@tie{}config} commands above should modify your
1589 local repository's @file{.git/config} file. These lines:
1593 url = git://git.sv.gnu.org/lilypond.git/
1597 should now be changed to:
1601 url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
1605 where @var{user} is your login name on Savannah.
1609 @command{git@tie{}config@tie{}push.default@tie{}matching} command
1610 should add these lines to @file{.git/config}:
1619 Encryption protocols, including ssh, generally do not permit packet
1620 fragmentation to avoid introducing a point of insecurity. This
1621 means that the maximum packet size must not exceed the smallest
1622 MTU (Maximum Transmission Unit) set in the routers along the path.
1623 This smallest MTU is determined by a procedure during call set-up
1624 which relies on the transmission over the path of ICMP packets.
1625 If any of the routers in the path block ICMP packets this mechanism
1626 fails, resulting in the possibility of packets being transmitted
1627 which exceed the MTU of one of the routers. If this happens the
1628 packet is discarded, causing the ssh session to hang, timeout or
1629 terminate with the error message
1632 ssh: connect to host <host ip addr> port 22: Bad file number
1633 fatal: The remote end hung up unexpectedly
1636 depending on precisely when in the proceedings the first large
1637 packet is transmitted. Most routers on the internet have MTU
1638 set to 1500, but routers installed in homes to connect via
1639 broadband may use a slightly smaller MTU for efficient transmission
1640 over ATM. If this problem is encountered a possible work-around is
1641 to set the MTU in the local router to 1500.
1643 @node Git on Windows
1644 @section Git on Windows
1646 @c Some of this may duplicate stuff in other sections
1647 @c But it is probably best for windows users to have it all together
1648 @c If necessary, clear this up later -td
1650 TODO: Decide what to do with this... Pare it down? Move
1651 paragraphs next to analogous Unix instructions? -mp
1653 @subsection Background to nomenclature
1655 Git is a system for tracking the changes made to source files by a
1656 distributed set of editors. It is designed to work without a
1657 master repository, but we have chosen to have a master repository
1658 for LilyPond files. Editors hold a local copy of the master
1659 repository together with any changes they have made locally.
1660 Local changes are held in a local @q{branch}, of which there may
1661 be several, but these instructions assume you are using just one.
1662 The files visible in the local repository always correspond to
1663 those on the currently @q{checked out} local branch.
1665 Files are edited on a local branch, and in that state the changes
1666 are said to be @q{unstaged}. When editing is complete, the
1667 changes are moved to being @q{staged for commit}, and finally the
1668 changes are @q{committed} to the local branch. Once committed,
1669 the changes (called a @q{commit}) are given a unique 40-digit
1670 hexadecimal reference number called the @q{Committish} or @q{SHA1
1671 ID} which identifies the commit to Git. Such committed changes
1672 can be sent to the master repository by @q{pushing} them (if you
1673 have write permission) or by sending them by email to someone who
1674 has, either as a complete file or as a @q{diff} or @q{patch}
1675 (which send just the differences from the master repository).
1677 @subsection Installing git
1680 @uref{http://code.google.com/p/msysgit/downloads/list} (note, not
1681 msysGit, which is for Git developers and not PortableGit, which is
1682 not a full git installation) and install it.
1684 Note that most users will not need to install SSH. That is not
1685 required until you have been granted direct push permissions to
1686 the master git repository.
1688 Start Git by clicking on the desktop icon. This will bring up a
1689 command line bash shell. This may be unfamiliar to Windows users.
1690 If so, follow these instructions carefully. Commands are entered
1691 at a $ prompt and are terminated by keying a newline.
1693 @subsection Initialising Git
1695 Decide where you wish to place your local Git repository, creating
1696 the folders in Windows as necessary. Here we call the folder to
1697 contain the repository @code{[path]/Git}, but if you intend using
1698 Git for other projects a directory name like @code{lilypond-git}
1699 might be better. You will need to have space for around
1702 Start the Git bash shell by clicking on the desk-top icon
1703 installed with Git and type
1709 to position the shell at your new Git repository.
1711 Note: if [path] contains folders with names containing spaces use
1723 to initialize your Git repository.
1725 Then type (all on one line; the shell will wrap automatically)
1728 git remote add -ft master origin git://git.sv.gnu.org/lilypond.git
1731 to download the lilypond master files.
1733 @warning{Be patient! Even on a broadband connection this can take
1734 10 minutes or more. Wait for lots of [new tag] messages and the $
1737 We now need to generate a local copy of the downloaded files in a
1738 new local branch. Your local branch needs to have a name. It is
1739 usual to call it @q{master} and we shall do that here.
1744 git checkout -b master origin/master
1747 This creates a second branch called @q{master}. You will see two
1748 warnings (ignore these), and a message advising you that your
1749 local branch @q{master} has been set up to track the remote
1750 branch. You now have two branches, a local branch called
1751 @q{master}, and a tracking branch called @q{origin/master}, which
1752 is a shortened form of @q{remotes/origin/master}.
1754 Return to Windows Explorer and look in your Git repository. You
1755 should see lots of folders. For example, the LilyPond
1756 documentation can be found in [path]/Git/Documentation/.
1758 The Git bash shell is terminated by typing @code{exit} or by
1759 clicking on the usual Windows close-window widget.
1763 Almost all subsequent work will use the Git Graphical User
1764 Interface, which avoids having to type command line commands. To
1765 start Git GUI first start the Git bash shell by clicking on the
1766 desktop icon, and type
1773 The Git GUI will open in a new window. It contains four panels
1774 and 7 pull-down menus. At this stage do not use any of the
1775 commands under Branch, Commit, Merge or Remote. These will be
1778 The top panel on the left contains the names of files which you
1779 are in the process of editing (Unstaged Changes), and the lower
1780 panel on the left contains the names of files you have finished
1781 editing and have staged ready for committing (Staged Changes). At
1782 present, these panels will be empty as you have not yet made any
1783 changes to any file. After a file has been edited and saved the
1784 top panel on the right will display the differences between the
1785 edited file selected in one of the panels on the left and the last
1786 version committed on the current branch.
1788 The panel at bottom right is used to enter a descriptive message
1789 about the change before committing it.
1791 The Git GUI is terminated by entering CNTL-Q while it is the
1792 active window or by clicking on the usual Windows close-window
1795 @subsection Personalising your local git repository
1797 Open the Git GUI, click on
1803 and enter your name and email address in the left-hand (Git
1804 Repository) panel. Leave everything else unchanged and save it.
1806 Note that Windows users must leave the default setting for line
1807 endings unchanged. All files in a git repository must have lines
1808 terminated by just a LF, as this is required for Merge to work,
1809 but Windows files are terminated by CRLF by default. The git
1810 default setting causes the line endings of files in a Windows git
1811 repository to be flipped automatically between LF and CRLF as
1812 required. This enables files to be edited by any Windows editor
1813 without causing problems in the git repository.
1815 @subsection Checking out a branch
1817 At this stage you have two branches in your local repository,
1818 both identical. To see them click on
1824 You should have one local branch called @q{master} and one
1825 tracking branch called @q{origin/master}. The latter is your
1826 local copy of the @q{remotes/origin/master} branch in the master
1827 LilyPond repository. The local @q{master} branch is where you
1828 will make your local changes.
1830 When a particular branch is selected, i.e., checked out, the files
1831 visible in your repository are changed to reflect the state of the
1832 files on that branch.
1834 @subsection Updating files from @q{remote/origin/master}
1836 Before starting the editing of a file, ensure your local
1837 repository contains the latest version of the files in the remote
1838 repository by first clicking
1841 Remote -> Fetch from -> origin
1847 This will place the latest version of every file, including all
1848 the changes made by others, into the @q{origin/master} branch of
1849 the tracking branches in your git repository. You can see these
1850 files by checking out this branch, but you must @emph{never} edit
1851 any files while this branch is checked out. Check out your local
1852 @q{master} branch again.
1854 You then need to merge these fetched files into your local
1855 @q{master} branch by clicking on
1858 Merge -> Local Merge
1862 and if necessary select the local @q{master} branch.
1864 Note that a merge cannot be completed if you have made any local
1865 changes which have not yet been committed.
1867 This merge will update all the files in the @q{master} branch to
1868 reflect the current state of the @q{origin/master} branch. If any
1869 of the changes conflict with changes you have made yourself
1870 recently you will be notified of the conflict (see below).
1872 @subsection Editing files
1874 First ensure your @q{master} branch is checked out, then simply
1875 edit the files in your local Git repository with your favourite
1876 editor and save them back there. If any file contains non-ASCII
1877 characters ensure you save it in UTF-8 format. Git will detect
1878 any changes whenever you restart Git GUI and the file names will
1879 then be listed in the Unstaged Changes panel. Or you can click
1880 the Rescan button to refresh the panel contents at any time. You
1881 may break off and resume editing any time.
1883 The changes you have made may be displayed in diff form in the top
1884 right-hand panel of Git GUI by clicking on the file name shown in
1885 one of the left panels.
1887 When your editing is complete, move the files from being Unstaged
1888 to Staged by clicking the document symbol to the left of each
1889 name. If you change your mind it can be moved back by clicking on
1890 the ticked box to the left of the name.
1892 Finally the changes you have made may be committed to your
1893 @q{master} branch by entering a brief message in the Commit
1894 Message box and clicking the Commit button.
1896 If you wish to amend your changes after a commit has been made,
1897 the original version and the changes you made in that commit may
1898 be recovered by selecting
1901 Commit -> Amend Last Commit
1905 or by checking the Amend Last Commit radio button at bottom right.
1906 This will return the changes to the Staged state, so further
1907 editing made be carried out within that commit. This must only be
1908 done @emph{before} the changes have been Pushed or sent to your
1909 mentor for Pushing - after that it is too late and corrections
1910 have to be made as a separate commit.
1913 @subsection Sending changes to @q{remotes/origin/master}
1915 If you do not have write access to @q{remotes/origin/master} you
1916 will need to send your changes by email to someone who does.
1918 First you need to create a diff or patch file containing your
1919 changes. To create this, the file must first be committed. Then
1920 terminate the Git GUI. In the git bash shell first cd to your Git
1927 if necessary, then produce the patch with
1930 git format-patch origin
1933 This will create a patch file for all the locally committed files
1934 which differ from @q{origin/master}. The patch file can be found
1935 in [path]/Git and will have a name formed from the commit message.
1937 @subsection Resolving merge conflicts
1939 As soon as you have committed a changed file your local
1940 @code{master} branch has diverged from @code{origin/master}, and
1941 will remain diverged until your changes have been committed in
1942 @code{remotes/origin/master} and Fetched back into your
1943 @code{origin/master} branch. Similarly, if a new commit has been
1944 made to @code{remotes/origin/master} by someone else and Fetched,
1945 your local @code{master} branch is divergent. You can detect a
1946 divergent branch by clicking on
1949 Repository -> Visualise all branch history
1952 This opens up a very useful new window called @q{gitk}. Use this
1953 to browse all the commits made by yourself and others.
1955 If the diagram at top left of the resulting window does not show
1956 your @code{master} tag on the same node as the
1957 @code{remotes/origin/master} tag your branch has diverged from
1958 @code{origin/master}. This is quite normal if files you have
1959 modified yourself have not yet been Pushed to
1960 @code{remotes/origin/master} and Fetched, or if files modified and
1961 committed by others have been Fetched since you last Merged
1962 @code{origin/master} into your local @code{master} branch.
1964 If a file being merged from @code{origin/master} differs from one
1965 you have modified in a way that cannot be resolved automatically
1966 by git, Merge will report a Conflict which you must resolve by
1967 editing the file to create the version you wish to keep.
1969 This could happen if the person updating
1970 @code{remotes/origin/master} for you has added some changes of his
1971 own before committing your changes to
1972 @code{remotes/origin/master}, or if someone else has changed the
1973 same file since you last fetched the file from
1974 @code{remotes/origin/master}.
1976 Open the file in your editor and look for sections which are
1979 [to be completed when I next have a merge conflict to be sure I
1980 give the right instructions -td]
1983 @subsection Other actions
1985 The instructions above describe the simplest way of using git on
1986 Windows. Other git facilities which may usefully supplement these
1990 @item Using multiple local branches (Create, Rename, Delete)
1991 @item Resetting branches
1992 @item Cherry-picking commits
1993 @item Pushing commits to @w{remote/origin/master}
1994 @item Using gitk to review history
1997 Once familiarity with using git on Windows has been gained the
1998 standard git manuals can be used to learn about these.
2001 @node Repository directory structure
2002 @section Repository directory structure
2005 @c TODO: integrate the roadmap better
2006 @verbatiminclude ROADMAP
2009 @node Other Git documentation
2010 @section Other Git documentation
2014 Official git man pages:
2015 @uref{http://www.kernel.org/pub/software/scm/git/docs/}
2018 More in-depth tutorials: @uref{http://git-scm.com/documentation}
2021 Book about git: @uref{http://progit.org/,Pro Git}