@node Working with source code
@chapter Working with source code
+New contributors should only read @ref{Using lily-git}. Please
+ignore the rest of this chapter.
+
+Advanced contributors will find the rest of this material quite
+useful, particularly if they are working on major new features.
@menu
* Using lily-git::
@node Using lily-git
@section Using lily-git
+@subsubheading Install and Configuration
+
+@enumerate
+@item
+If you haven't already, download and install Git.
+
+@itemize
+
+@item Windows users: download the @code{.exe} file labeled
+@qq{Full installer for official Git} from:
+
+@example
+@uref{http://code.google.com/p/msysgit/downloads/list}
+@end example
-If you haven't already, download and install Git. Go to
-@uref{http://git-scm.com/download}, and in the @qq{Binaries}
-section, select the appropriate package for your operating system.
-Windows users should visit
-@uref{http://code.google.com/p/msysgit/downloads/list} and
-download the @file{.exe} file labeled @qq{Full installer for
-official Git}.
+@item Other operating systems: either install @command{git} with
+your package manager, or download it from the @qq{Binaries}
+section of:
+@example
+@uref{http://git-scm.com/download}
+@end example
+
+@end itemize
+
+
+@item
Download the lily-git script from:
@c don't change the cgit link below to gitweb; gitweb uses
@uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
@end example
+@item
To run the program from the command line, navigate to the
-directory containing @file{lily-git.tcl} and enter:
+directory containing @file{lily@/-git@/.tcl} and enter:
@example
wish lily-git.tcl
@end example
+@end enumerate
+
-@subsubheading Get source / Update source
+@subsubheading 1. Get source / Update source
When you click the @qq{Get source} button, @command{lily-git} will
-create a directory called @file{lilypond-git/} within your home
-directory, and will download the complete source code into that
+create a directory called @file{lilypond@/-git/} within your home
+directory, and will download the source code into that
directory (around 55Mb). When the process is finished, the
@qq{Command output} window will display @qq{Done}, and the button
label will change to say @qq{Update source}.
-Navigate to the @file{lilypond-git/} directory to view the source
+Navigate to the @file{lilypond@/-git/} directory to view the source
files. You should now be able to modify the source files using
your normal text editor.
-@knownissues
+@quotation
+Advanced note: The @qq{Get source} button does not fetch the
+entire history of the git repository, so utilities like
+@command{gitk} will only be able to display the most recent
+additions. As you continue to work with @command{lily-git}, the
+@qq{Update source} button will take any new additions and add it
+to whatever is currently in your repository's history.
+@end quotation
-The @qq{Get source} button does not fetch the entire history of
-the git repository, so utilities like @command{gitk} will only
-be able to display the most recent additions. As you continue to
-work with @command{lily-git}, the @qq{Update source} button will take
-any new additions and add it to whatever is currently in your repository's
-history.
-
-@subsubheading New local commit
+@subsubheading 2a. New local commit
A single commit typically represents one logical set of related
changes (such as a bug-fix), and may incorporate changes to
commit.
-@subsubheading Amend previous commit
+@subsubheading 2b. Amend previous commit
You can go back and make changes to the most recent commit with
the @qq{Amend previous commit} button. This is useful if a
-mistake is found after you've clicked the @qq{New local commit}
-button. To amend the most recent commit, edit the source files as
-needed and click the button. The earlier version of the commit is
-not saved, but is replaced by the new one.
+mistake is found after you have clicked the @qq{New local commit}
+button.
+
+To amend the most recent commit, re-edit the source files as
+needed and then click the @qq{Amend previous commit} button. The
+earlier version of the commit is not saved, but is replaced by the
+new one.
-Note that this does not update patch files; if you have a patch
-file from an earlier version of the commit, you will need to make
-another patch set when using this feature. The old patch file is
-not saved, but is replaced by the new one.
+Note that this does not update the patch @strong{files}; if you
+have a patch file from an earlier version of the commit, you will
+need to make another patch set when using this feature. The old
+patch file will not be saved, but will be replaced by the new one
+after you click on @qq{Make patch set}.
-@subsubheading Make patch set
+@subsubheading 3. Make patch set
Before making a patch set from any commits, you should click the
@qq{Update source} button to make sure the commits are based on
hopelessly confused!}
The button labeled @qq{Abort changes -- Reset to origin} will copy
-all changed files to a subdirectory of @file{lilypond-git/} named
-@file{aborted_edits/}, and will reset the repository to the
+all changed files to a subdirectory of @file{lilypond@/-git/} named
+@file{aborted@/_edits/}, and will reset the repository to the
current state of the remote repository (at @code{git.sv.gnu.org}).
Once Git is installed, you'll need to create a new directory where
your initial repository will be stored (the example below uses
-@file{~/lilypond-git/}, where @code{~} represents your home
+@file{~/lilypond@/-git/}, where @code{~} represents your home
directory). Run @command{git@tie{}init} from within the new
directory to initialize an empty repository:
@subsubheading Technical details
-This creates (within the @file{~/lilypond-git/} directory) a
+This creates (within the @file{~/lilypond@/-git/} directory) a
subdirectory called @file{.git/}, which Git uses to keep track of
changes to the repository, among other things. Normally you don't
need to access it, but it's good to know it's there.
@warning{Throughout the rest of this manual, all command-line
input should be entered from the top directory of the Git
-repository being discussed (eg. @file{~/lilypond-git/}). This is
+repository being discussed (eg. @file{~/lilypond@/-git/}). This is
referred to as a @emph{top source directory}.}
Before downloading a copy of the main LilyPond repository, you
Using the @command{git@tie{}config} command @emph{without} the
@command{--global} option configures repository-specific settings,
-which are stored in the file @file{.git/config}. This file is
+which are stored in the file @file{.git/@/config}. This file is
created when a repository is initialized (using
@command{git@tie{}init}), and by default contains these lines:
@end example
By now the source files should be accessible---you should be able
-to edit any files in the @file{lilypond-git/} directory using a
+to edit any files in the @file{lilypond@/-git/} directory using a
text editor of your choice. But don't start just yet! Before
editing any source files, learn how to keep your changes organized
and prevent problems later---read @ref{Basic Git procedures}.
@subsubheading Technical Details
The @command{git@tie{}remote@tie{}add} command should add some
-lines to your local repository's @file{.git/config} file:
+lines to your local repository's @file{.git/@/config} file:
@example
[remote "origin"]
The @command{git@tie{}config} command mentioned above adds the
line @code{rebase = true} to the master branch in your local
-repository's @file{.git/config} file:
+repository's @file{.git/@/config} file:
@example
[branch "master"]
@example
-# Please enter the commit message for your changes. Lines starting
+# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch master
# Changes to be committed:
A @emph{branch} is nothing more than a pointer to a particular
commit, which is called the @emph{head} of the branch; when
-referring to a branch, one often acutally thinks about its head
+referring to a branch, one often actually thinks about its head
and the ancestor commits of the head.
Now we will explain the two last commands you used to get the
The commands above don't only bring you the latest version of the
-sources, but also the full history of revisions (revisons, also
+sources, but also the full history of revisions (revisions, also
called commits, are changes made to the sources), stored in the
@file{.git} directory. You can browse this history with
@end example
When prompted for a location to save the key, press <ENTER> to
-accept the default location (@file{~/.ssh/id_dsa}).
+accept the default location (@file{~/.ssh/@/id_dsa}).
Next you are asked to enter an optional passphrase. On most
systems, if you use a passphrase, you will likely be prompted for
@end example
After setting up your passphrase, your private key is saved as
-@file{~/.ssh/id_dsa} and your public key is saved as
-@file{~/.ssh/id_dsa.pub}.
+@file{~/.ssh/@/id_dsa} and your public key is saved as
+@file{~/.ssh/@/id_dsa@/.pub}.
@item
Register your public SSH @q{dsa} key with Savannah. From the
@qq{My Account Configuration} page, click on @qq{Edit SSH Keys},
-then paste the contents of your @file{~/.ssh/id_dsa.pub} file into
+then paste the contents of your @file{~/.ssh/@/id_dsa@/.pub} file into
one of the @qq{Authorized keys} text fields, and click
@qq{Update}.
@item
-After your membership has been activated and you’ve configured Git
+After your membership has been activated and you've configured Git
to use SSH, test the connection with:
@example
@end example
The list of known hosts is stored in the file
-@file{~/.ssh/known_hosts}.
+@file{~/.ssh/@/known@/_hosts}.
At this point, you are prompted for your passphrase if you have
one, then Git will attempt a pull.
@item
The @command{git@tie{}config} commands above should modify your
-local repository's @file{.git/config} file. These lines:
+local repository's @file{.git/@/config} file. These lines:
@example
[remote "origin"]
@item
Similarly, the
@command{git@tie{}config@tie{}push.default@tie{}matching} command
-should add these lines to @file{.git/config}:
+should add these lines to @file{.git/@/config}:
@example
[push]
Git is a system for tracking the changes made to source files by a
distributed set of editors. It is designed to work without a
-master repository, but we have chosen to have a master respository
+master repository, but we have chosen to have a master repository
for LilyPond files. Editors hold a local copy of the master
repository together with any changes they have made locally.
Local changes are held in a local @q{branch}, of which there may
@subsection Git GUI
Almost all subsequent work will use the Git Graphical User
-Interface, which avoids having to type command line commands. To
+Interface, which avoids having to type command line commands. To
start Git GUI first start the Git bash shell by clicking on the
desktop icon, and type
projects / lilypond.git / blobdiff