@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.
+@warning{New contributors should read @ref{Quick start}, and in
+particular @ref{Using lily-git}, instead of this chapter.}
-Advanced contributors will find the rest of this material quite
-useful, particularly if they are working on major new features.
+Advanced contributors will find this material quite useful,
+particularly if they are working on major new features.
@menu
-* Using lily-git::
+* Manually installing lily-git.tcl::
* Starting with Git::
* Basic Git procedures::
* Advanced Git procedures::
@end menu
-@node Using lily-git
-@section Using lily-git
+@node Manually installing lily-git.tcl
+@section Manually installing lily-git.tcl
-@subsubheading Install and Configuration
+We have created an easy-to-use GUI to simplify git for new
+contributors. If you are comfortable with the command-line, then
+skip ahead to @ref{Starting with Git}.
+
+@warning{These instructions are only for people who are @emph{not}
+using @ref{Lilydev}.}
+
+@c there's some duplication in this section with stuff covered in
+@c Quick Start, but moving it into a macro inside included/ would
+@c be getting a bit icky. -gp
@enumerate
@item
@itemize
-@item
-Lilybuntu users: git has already been installed for you.
-
@item Windows users: download the @code{.exe} file labeled
@qq{Full installer for official Git} from:
@item
-Download the lily-git script from:
+Download the @command{lily-git.tcl} script from:
@c don't change the cgit link below to gitweb; gitweb uses
@c long filenames like "scripts_auxiliar_lily-git.tcl"
-@example
+@smallexample
@uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
-@end example
+@end smallexample
@item
To run the program from the command line, navigate to the
-directory containing @file{lily-git.tcl} and enter:
+directory containing @command{lily-git.tcl} and enter:
@example
wish lily-git.tcl
@end example
-@end enumerate
-
-
-@subsubheading 1. Get source / Update source
+@item
+Click on the @qq{Get source} button.
-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 source code into that
+This will 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}.
+@item
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.
-
-@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
-
-
-@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
-multiple files at the same time.
-
-When you're finished making the changes for your first commit,
-click the @qq{New local commit} button. This will open the
-@qq{Git Commit Message} window. The message header is required,
-and the message body is optional. See @ref{Commits and patches}
-for more information regarding commits and commit messages.
-
-After entering a commit message, click @qq{OK} to finalize the
-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 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 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 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
-the most recent remote snapshot.
-
-When you click the @qq{Make patch set} button, @command{lily-git}
-will produce patch files for any new commits, saving them to the
-current directory. The command output will display the name of
-the new patch files near the end of the output:
-
-@example
-0001-CG-add-lily-git-instructions.patch
-Done.
-@end example
-
-Send patch files to your mentor if you have one. Otherwise, write
-an email (must be less than 64 KB) to
-@email{lilypond-devel@@gnu.org} briefly explaining your work, with
-the patch files attached. Translators should send patches to
-@email{translations@@lilynet.net}.
+files.
+@end enumerate
-@subsubheading The @qq{Abort changes -- Reset to origin} button
+@warning{Throughout the rest of this manual, most command-line
+input should be entered from @file{~/lilypond-git/}. This is
+referred to as the @emph{top source directory}.}
-@warning{Only use this if your local commit history gets
-hopelessly confused!}
+Further instructions are in @ref{Daily use of lily-git.tcl}.
-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
-current state of the remote repository (at @code{git.sv.gnu.org}).
+@advanced{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.tcl}, the @qq{Update
+source} button will take any new additions and add it to whatever
+is currently in your repository's history.}
@node Starting with Git
@section Starting with Git
-
Using the Git program directly (as opposed to using the
-@command{lily-git} GUI) allows you to have much greater control
+@command{lily-git.tcl} GUI) allows you to have much greater control
over the contributing process. You should consider using Git if
you want to work on complex projects, or if you want to work on
multiple projects concurrently.
@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
-referred to as a @emph{top source directory}.}
+referred to as the @emph{top source directory}.}
Before downloading a copy of the main LilyPond repository, you
should configure some basic settings with the
global and repository-specific options.
To configure settings that affect all repositories, use the
-@command{--global} command line option. For example, the first
+@option{--global} command line option. For example, the first
two options that you should always set are your @var{name} and
@var{email}, since Git needs these to keep track of commit
authors:
@end example
Using the @command{git@tie{}config} command @emph{without} the
-@command{--global} option configures repository-specific settings,
+@option{--global} option configures repository-specific settings,
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
If you're tracking the remote @code{master} branch, you should add
-the @code{-r} option (short for @code{--rebase}) to keep commits
+the @option{-r} option (short for @option{--rebase}) to keep commits
on your local branch current:
@example
@end example
If you don't edit translated documentation and don't want to type
-@code{-r} every time, configure the master branch to rebase by
+@option{-r} every time, configure the master branch to rebase by
default with this command:
@example
@end example
Git will ask you for confirmation if it sees that data would be
-lost by deleting the branch. Use @code{-D} instead of @code{-d}
+lost by deleting the branch. Use @option{-D} instead of @option{-d}
to bypass this. Note that you cannot delete a branch if it is
currently checked out.
@end example
@noindent
-The @code{-a} is short for @code{--all} which includes modified
+The @option{-a} is short for @option{--all} which includes modified
and deleted files, but only those newly created files that have
previously been added.
alternate method here.
You should always run @command{git@tie{}pull@tie{}-r} (translators
-should leave off the @code{-r}) before doing this to ensure that
+should leave off the @option{-r}) before doing this to ensure that
your patches are as current as possible.
Once you have made one or more commits in your local repository,
@uref{http://codereview.appspot.com/}
@end example
-@subsubheading Initial setup
+@subsubheading @command{git-cl} install
-This requires the use of an external package, git-cl, and an email
-account on Google.
+LilyDev users should skip over these @q{install} instructions.
-@command{git-cl} is installed by:
+@enumerate
+
+@item
+Install @command{git-cl} by entering:
@example
git clone git://neugierig.org/git-cl.git
@end example
-Then, add the @file{git-cl} directory to your PATH, or create a
-symbolic link to the @command{git-cl} and @command{upload.py} in
-one of your PATH directories (like @file{usr/bin}). Then
-configure the program by running:
+@item
+Add the @file{git-cl/} directory to your PATH, or create a
+symbolic link to the @command{git-cl} and @command{upload.py}
+scripts in one of your PATH directories (such as
+@file{$HOME/bin}).
+
+@end enumerate
+
+@subsubheading @command{git-cl} configuration
+
+LilyDev users should perform these @q{configuration} instructions.
+
+@enumerate
+@item
+You must have a gmail account; please create one if you do not
+have one already.
+
+@item
+Move into the top source directory and then configure @command{git
+cl} with the following commands. If you do not understand any
+question, just answer with a newline (CR).
@example
+cd $HOME/lilypond-git/
git cl config
@end example
-@noindent
-in the LilyPond git directory and answering the questions that
-are asked. If you do not understand the question answer with just
-a newline (CR).
+The @qq{CC list} question should be answered with:
+
+@example
+lilypond-devel@@gnu.org
+@end example
+
+@end enumerate
@subsubheading Uploading patch set
+@warning{Unless you are familiar with branches, only work on one
+set of changes at once.}
+
There are two methods, depending on your git setup.
@itemize
@item
-@strong{Separate branch}:
+@strong{Master branch}: (easy option, and used in @command{lily-git.tcl})
+
+If you added your patch to @code{master}, then:
+
+@example
+git pull -r
+git cl upload origin/master
+@end example
+
+If you have git push ability, make sure that you @emph{remove}
+your patch (with @command{git rebase} or @command{git reset})
+before pushing other stuff.
+
+@item
+@strong{Separate branch}: (complicated option)
Ensure your changes are committed in a separate branch, which
should differ from the reference branch to be used by just the
@noindent
can be used.
-@item
-@strong{Master branch}:
-
-If you added your patch to @code{master}, then make sure that you
-are up-to-date (by running @code{git pull -r}), and then run:
-
-@example
-git cl upload origin/master
-@end example
-
-If you have git push ability, make sure that you @emph{remove}
-your patch (with @command{git rebase} or @command{git reset})
-before pushing other stuff.
-
@end itemize
After prompting for your Google email address and password, the
-patch set will be posted to Rietveld.
+patch set will be posted to Rietveld, and you will be given a URL
+for your patch.
+
+@warning{Some installations of git-cl fail when uploading a patch
+set that includes a .scm file. When this happens, it can
+generally be fixed by editing the file @file{/etc/mime.types}.
+Add a line to this file containing @code{text/x-script.scheme scm}.}
@subsubheading Announcing your patch set
-You should then announce the patch by sending an email to
-@code{lilypond-devel}, with a subject line starting with PATCH:,
-asking for comments on the patch. Alternately, you may Publish +
-Mail a (bogus) comment, in order to send an email to
-lilypond-devel.
+You should then announce the patch by logging into the code review
+issue webpage and using @qq{Publish + Mail Comments} to add a
+(mostly bogus) comment to your issue. The text of your comment
+will be sent to our developer mailing list.
+
+@warning{There is no automatic notification of a new patch; you
+must add a comment yourself.}
@subsubheading Revisions
* Git log::
* Applying remote patches::
* Sending and receiving patches via email::
+* Cleaning up multiple patches::
* Commit access::
@end menu
Sometimes git will become hopelessly confused, and you just want
to get back to a known, stable state. This command destroys any
-local changes you have made, but at least you get back to the
-current online version:
+local changes you have made in the currently checked-out branch,
+but at least you get back to the current online version:
@example
git reset --hard origin/master
@uref{http://wiki.winehq.org/GitWine}.
+@node Cleaning up multiple patches
+@subsection Cleaning up multiple patches
+
+If you have been developing on your own branch for a while, you
+may have more commmits than is really sensible. To revise your
+work and condense commits, use:
+
+@example
+git rebase origin/master
+git rebase -i origin/master
+@end example
+
+@warning{Be a bit cautious -- if you completely remove commits
+during the interactive session, you will... err... completely
+remove those commits.}
+
+
@node Commit access
@subsection Commit access
certificate in your browser, given at
@uref{http://savannah.gnu.org/tls/tutorial/}.
+@warning{Savannah will silently put your username in lower-case --
+do not try to use capital letters.}
+
@item
After registering, if you are not logged in automatically, login
projects / lilypond.git / blobdiff