Revert "CG merge duplicated sections about conflicts and branches"

[lilypond.git] / Documentation / contributor / source-code.itexi

diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi
index ea8fc8775c59007ed7831b1b3c07260edc1e9887..7b60706ab1b75377c6098887a85144519a7f92aa 100644 (file)
--- a/Documentation/contributor/source-code.itexi
+++ b/Documentation/contributor/source-code.itexi
@@ -5,7 +5,7 @@
 @chapter Working with source code
 
 @warning{New contributors should read @ref{Quick start}, and in
 @chapter Working with source code
 
 @warning{New contributors should read @ref{Quick start}, and in

-particular @ref{Using lily-git}, instead of this chapter.}
+particular @ref{lily-git}, instead of this chapter.}

 
 Advanced contributors will find 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.


@@ -29,7 +29,7 @@ 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}
 skip ahead to @ref{Starting with Git}.
 
 @warning{These instructions are only for people who are @emph{not}

-using @ref{Lilydev}.}
+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 there's some duplication in this section with stuff covered in
 @c Quick Start, but moving it into a macro inside included/ would


@@ -93,10 +93,10 @@ files.
 @end enumerate
 
 @warning{Throughout the rest of this manual, most command-line
 @end enumerate
 
 @warning{Throughout the rest of this manual, most command-line

-input should be entered from @file{~/lilypond-git/}.  This is
+input should be entered from @file{$LILYPOND_GIT}.  This is

 referred to as the @emph{top source directory}.}
 
 referred to as the @emph{top source directory}.}
 

-Further instructions are in @ref{Daily use of lily-git.tcl}.
+Further instructions are in @ref{How to use lily-git}.

 
 
 @node Starting with Git
 
 
 @node Starting with Git


@@ -111,6 +111,8 @@ multiple projects concurrently.
 
 @menu
 * Setting up::
 
 @menu
 * Setting up::

+* Git for the impatient::
+* Other repositories::

 * Downloading remote branches::
 @end menu
 
 * Downloading remote branches::
 @end menu
 


@@ -119,8 +121,7 @@ multiple projects concurrently.
 @subsection Setting up
 
 @warning{These instructions assume that you are using the
 @subsection Setting up
 
 @warning{These instructions assume that you are using the

-command-line version of Git 1.5 or higher.  Windows users should
-skip to @ref{Git on Windows}.}
+command-line version of Git 1.7 or higher.}

 
 @menu
 * Installing Git::
 
 @menu
 * Installing Git::


@@ -158,7 +159,7 @@ The above command will put the it in @file{~/lilypond-git}, where
 
 @subsubheading Technical details
 
 
 @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.
 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.


@@ -169,7 +170,7 @@ 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
 
 @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 the @emph{top source directory}.}
 
 Before working with the copy of the main LilyPond repository, you
 referred to as the @emph{top source directory}.}
 
 Before working with the copy of the main LilyPond repository, you


@@ -206,6 +207,19 @@ change the default editor to @command{nano}, enter:
 git config --global core.editor @var{nano}
 @end example
 
 git config --global core.editor @var{nano}
 @end example
 

+Finally, and in some ways most importantly, let's make sure that
+we know what branch we're on.  If you're not using LilyDev, add
+this to your @file{~/.bashrc}:
+
+@verbatim
+export PS1="\u@\h \w\$(__git_ps1)$ "
+@end verbatim
+
+If you are not using LilyDev, you may need to install the
+additional @code{git-completion} package, but it is definitely
+worth it.
+
+

 @subsubheading Technical details
 
 Git stores the information entered with
 @subsubheading Technical details
 
 Git stores the information entered with


@@ -245,168 +259,413 @@ setting any now.  Specific recommendations will be mentioned later
 in this manual.
 
 
 in this manual.
 
 

-@node Downloading remote branches
-@subsection Downloading remote branches
+@node Git for the impatient
+@subsection Git for the impatient

 
 

+@advanced{The intent of this subsection is to get you working on lilypond as
+soon as possible.  If you want to learn about git, go read
+@ref{Other Git documentation}.
+@*
+Also, these instructions are designed to eliminate the most common
+problems we have found in using git.  If you already know git and
+have a different way of working, great!  Feel free to ignore the
+advice in this subsection.}

 
 

-@menu
-* Organization of remote branches::
-* LilyPond repository sources::
-* Downloading individual branches::
-* Downloading all remote branches::
-* Other branches::
-@end menu

 
 

+Ok, so you've been using @command{lily-git.tcl} for a while, but
+it's time to take the next step.  Since our review process delays
+patches by 60-120 hours, and you want to be able to work on other
+stuff while your previous work is getting reviewed, you're going
+to use @strong{branches}.

 
 

-@node Organization of remote branches
-@unnumberedsubsubsec Organization of remote branches
+You can think of a branch as being a separate copy of the source
+code.  But don't worry about it.

 
 

+@subsubheading Start work: make a new branch

 
 

-The main LilyPond repository is organized into @emph{branches} to
-facilitate development.  These are often called @emph{remote}
-branches to distinguish them from @emph{local} branches you might
-create yourself (see @ref{Using local branches}).
+Let's pretend you want to add a section to the Contributor's Guide
+about using branches.

 
 

-The @code{master} branch contains all the source files used to
-build LilyPond, which includes the program itself (both stable and
-development releases), the documentation (and its translations),
-and the website.  Generally, the @code{master} branch is expected
-to compile successfully.
+Start by updating the repository, then making a new branch.  Call
+the branch anything you want as long as the name starts with
+@code{dev/}.  Branch names that don't begin with @code{dev/} are
+reserved for special things in lilypond.

 
 

-The @code{lilypond/translation} branch is a side branch that
-allows translators to work without needing to worry about
-compilation problems.  Periodically, the Translation Meister
-(after verifying that it doesn't break compilation), will
-@emph{merge} this branch back into @code{master} to incorporate
-recent translations.  Similarly, the @code{master} branch is
-usually merged into the @code{lilypond/translation} branch after
-significant changes to the English documentation.  See
-@ref{Translating the documentation} for details.
+@example
+git checkout master
+git pull -r origin master
+git branch dev/cg
+@end example

 
 

+@subsubheading Switch to that branch

 
 

-@node LilyPond repository sources
-@unnumberedsubsubsec LilyPond repository sources
+Nothing has happened to the files yet.  Let's change into the new
+branch.  You can think of this as @qq{loading a file}, although in
+this case it's really @qq{loading a directory and subdirectories
+full of files}.

 
 

+@example
+git checkout dev/cg
+@end example

 
 

-The recommended source for downloading a copy of the main
-repository is:
+Your prompt now shows you that you're on the other branch:

 
 @example
 
 @example

-git://git.sv.gnu.org/lilypond.git
+gperciva@@LilyDev:~/lilypond-git (dev/cg)$

 @end example
 
 @end example
 

-However, if your internet router filters out connections using the
-GIT protocol, or if you experience difficulty connecting via GIT,
-you can try these other sources:
+To be able to manage multiple lilypond issues at once, you'll need to switch
+branches.  You should have each lilypond issue on a separate branch.
+Switching branches is easy:

 
 @example
 
 @example

-ssh://git.sv.gnu.org/srv/git/lilypond.git
-http://git.sv.gnu.org/r/lilypond.git
+git checkout master
+git checkout origin/staging
+git checkout origin/release/unstable
+git checkout dev/cg

 @end example
 
 @end example
 

-The SSH protocol can only be used if your system is properly set
-up to use it.  Also, the HTTP protocol is slowest, so it should
-only be used as a last resort.
+Branches that begin with @code{origin/} are part of the remote repository,
+rather than your local repository, so when you check them out you get a 
+temporary local branch.  You should never make changes directly on a
+branch beginning with @code{origin/}.  You get changes into the remote
+repository by making them in local branches, and then pushing them to
+@code{origin/staging} as described below. 
+
+@subsubheading Make your changes
+
+Edit files, then commit them.
+
+@example
+git commit -a
+@end example
+
+
+Remember how I said that switching to a branch was like
+@qq{loading a directory}?  Well, you've just @qq{saved a
+directory}, so that you can @qq{load} it later.
+
+@advanced{If you have used @command{cvs} or @command{svn}, you may
+be very confused: those programs use @qq{commit} to mean
+@qq{upload my changes to the shared source repository}.
+Unfortunately, just to be different, @w{@command{git commit}}
+means @qq{save my changes to the files}.}
+
+When you create a new file, you need to add it to git, then commit it:
+
+@example
+git add input/regression/avoid-crash-on-condition.ly
+git commit -a
+@end example

 
 
 
 

-@node Downloading individual branches
-@unnumberedsubsubsec Downloading individual branches
+Edit more files.  Commit them again.  Edit yet more files, commit
+them again.  Go eat dinner.  Switch to @code{master} so you can
+play with the latest changes from other developers.  Switch back
+to your branch and edit some more.  Commit those changes.

 
 

+At this stage, don't worry about how many commits you have.

 
 

-Once you have initialized an empty Git repository on your system
-(see @ref{Initializing a repository}), you can download a remote
-branch into it.  Make sure you know which branch you want to start
-with.

 
 

-To download the @code{master} branch, enter the following:
+@subsubheading Save commits to external files
+
+Branches are nerve-wracking until you get used to them.  You can
+save your hard work as individual @file{.patch} files.  Be sure to
+commit your changes first.

 
 @example
 
 @example

-git remote add -ft master -m master \
-  origin git://git.sv.gnu.org/lilypond.git/
+git commit -a
+git format-patch master

 @end example
 
 @end example
 

-To download the @code{lilypond/translation} branch, enter:
+I personally have between 4 and 20 of those files saved in a
+special folder at any point in time.  Git experts might laugh as
+that behavior, but I feel a @emph{lot} better knowing that I've
+got those backups.
+
+
+@subsubheading Prepare your branch for review
+
+After committing, you can update your branch with the latest master:

 
 @example
 
 @example

-git remote add -ft lilypond/translation -m \
-  lilypond/translation origin git://git.sv.gnu.org/lilypond.git/
+git commit -a
+git checkout master
+git pull -r origin master
+git checkout dev/cg
+git rebase master

 @end example
 
 @end example
 

-The @command{git@tie{}remote@tie{}add} process could take up to
-ten minutes, depending on the speed of your connection.  The
-output will be something like this:
+
+Due to the speed of lilypond development, sometimes
+@code{master} has changed so much that your branch can no
+longer be applied to it.  In that happens, you will have a merge
+conflict.  Stop for a moment to either cry or have a stiff drink,
+then proceed to @ref{Merge conflicts}.
+
+
+@subsubheading Upload your branch
+
+Finally, you're finished your changes.  Time to upload for review.
+Make sure that you're on your branch, then upload:

 
 @example
 
 @example

-Updating origin
-remote: Counting objects: 235967, done.
-remote: Compressing objects: 100% (42721/42721), done.
-remote: Total 235967 (delta 195098), reused 233311 (delta 192772)
-Receiving objects: 100% (235967/235967), 68.37 MiB | 479 KiB/s, done.
-Resolving deltas: 100% (195098/195098), done.
-From git://git.sv.gnu.org/lilypond
- * [new branch]      master     -> origin/master
-From git://git.sv.gnu.org/lilypond
- * [new tag]         flower/1.0.1 -> flower/1.0.1
- * [new tag]         flower/1.0.10 -> flower/1.0.10
-⋮
- * [new tag]         release/2.9.6 -> release/2.9.6
- * [new tag]         release/2.9.7 -> release/2.9.7
+git checkout dev/cg
+git-cl upload master

 @end example
 
 @end example
 

-When @command{git@tie{}remote@tie{}add} is finished, the remote
-branch should be downloaded into your repository---though not yet
-in a form that you can use.  In order to browse the source code
-files, you need to @emph{create} and @emph{checkout} your own
-local branch.  In this case, however, it is easier to have Git
-create the branch automatically by using the @command{checkout}
-command on a non-existent branch.  Enter the following:
+
+@subsubheading Wait for reviews
+
+While you're waiting for a countdown and reviews, go back to
+master, make a @code{dev/doc-beams} branch, and start adding doc
+suggestions from issue 12345 from the tracker.  Or make a
+@code{dev/page-breaks} and fix bug in page breaking.  Or whatever.
+Don't worry, your @code{dev/cg} is safe.
+
+
+@subsubheading Combining commits (optional unless you have broken commits)
+
+Does the history of your branch look good?

 
 @example
 
 @example

-git checkout -b @var{branch} origin/@var{branch}
+gitk

 @end example
 
 @end example
 

-@noindent
-where @code{@var{branch}} is the name of your tracking branch,
-either @code{master} or @code{lilypond/translation}.
+If you have a lot of commits on your branch, you might want to
+combine some of them.  Alternately, you may like your commits, but
+want to edit the commit messages.
+
+@example
+git rebase -i master
+@end example
+
+Follow instructions on the screen.
+
+@warning{This step gives you the power to completely lose your
+work.  Make a backup of your commits by saving them to
+@file{.patch} files before playing with this.  If you do lose
+your work, don't despair.  You can get it back by using @code{git reflog}.
+The use of @code{git reflog} is not covered here.}

 
 

-Git will issue some warnings; this is normal:
+@warning{If any of the commits on your branch represent partial work that will
+not pass @var{make && make doc}, you @strong{must} squash these 
+commits into a working commit.  Otherwise, your push will break staging
+and will not be able to be merged to master.  In general, you will
+be safer to have one commit per push.}
+
+
+@subsubheading Push to staging
+
+When you've got the coveted @code{Patch-push} status, time to
+prepare your upload:

 
 @example
 
 @example

-warning: You appear to be on a branch yet to be born.
-warning: Forcing checkout of origin/master.
-Branch master set up to track remote branch master from origin.
-Already on 'master'
+git fetch
+git rebase origin/staging dev/cg~0
+gitk HEAD 

 @end example
 
 @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
-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}.
+@warning{Do not skip the @command{gitk} step; a quick 5-second
+check of the visual history can save a great deal of frustration
+later on.  You should see a set of your commits that are ahead of
+@code{origin/staging}, with no label for the top commit -- only a
+SHA1 id.}

 
 

-@subsubheading Technical Details
+@warning{If @code{origin/staging} and @code{origin/master} are the
+same commit, your branch (@code{dev/cg} in the example) will also
+be at the top of the @code{gitk} tree.  This is normal.}

 
 

-The @command{git@tie{}remote@tie{}add} command should add some
-lines to your local repository's @file{.git/config} file:
+If everything looks good, push it:

 
 @example
 
 @example

-[remote "origin"]
-        url = git://git.sv.gnu.org/lilypond.git/
-        fetch = +refs/heads/master:refs/remotes/origin/master
+git push origin HEAD:staging

 @end example
 
 @end example
 

+Then change back to your working branch:
+
+@example
+git checkout dev/cg
+@end example
+
+@warning{It is a best practice to avoid rebasing any of your branches
+to @code{origin/staging}.  If @code{origin/staging} is broken, it
+will be deleted and rebuilt.  If you have rebased one of your branches
+to @code{origin/staging}, the broken commits can end up in your branch.
+The commands given above do the rebase on a temporary branch, and avoid
+changing your working branch.}
+
+
+@subsubheading Delete your branch (safe)
+
+After a few hours, if there's nothing wrong with your branch, it
+should be automatically moved to @code{origin/master}.  Update,
+then try removing your branch:
+
+@example
+git checkout master
+git pull -r origin master
+git branch -d dev/cg
+@end example
+
+The last command will fail if the contents of @code{dev/cg} are
+not present in @code{origin/master}.
+
+
+@subsubheading Delete your branch (UNSAFE)
+
+@c don't give explicit commands here -- this is too dangerous to copy and paste
+Sometimes everything goes wrong.  If you want to remove a branch even though 
+it will cause your work to be lost (that is, if the contents of @code{dev/cg}
+are @strong{not} present in master), follow the instructions in @qq{Delete
+your branch (safe)}, but replace the @code{-d} on the final line with 
+a @code{-D}.

 
 

-@node Downloading all remote branches
-@unnumberedsubsubsec Downloading all remote branches

 
 

+@node Other repositories
+@subsection Other repositories

 
 

-To download all remote branches at once, you can @command{clone}
-the entire repository:
+We have a few other code repositories.
+
+@menu
+* lilypond-extra::
+* Grand Unified Builder (GUB)::
+* lilypad::
+* yet more repositories::
+@end menu
+
+@node lilypond-extra
+@unnumberedsubsubsec lilypond-extra
+
+There is a separate repository for general administrative scripts,
+as well as pictures and media files for the website.  People
+interested in working on the website should download this
+repository, and set their @code{$LILYPOND_WEB_MEDIA_GIT}
+environment variable to point to that repository.

 
 @example
 
 @example

-git clone git://git.sv.gnu.org/lilypond.git
+@uref{https://github.com/gperciva/lilypond-extra}

 @end example
 
 @end example
 

+To configure an environment variable in bash (the default for most
+GNU/Linux distributions),
+
+@example
+export LILYPOND_WEB_MEDIA_GIT=$HOME/dir/of/lilypond-extra/
+@end example
+
+Be aware that @code{lilypond-extra} is the definitive source for some binary
+files - in particular PDF versions of papers concerning LilyPond.  To add
+further PDFs of this sort, all that is necessary is to add the PDF to
+@code{lilypond-extra} and then add a reference to it in the documentation.  The
+file will then be copied to the website when @code{make website} is run.
+
+However, pictures that are also used in the documentation build are mastered in
+the main git repository.  If any of these is changed, it should be updated in
+git, and then the updates copied to @code{lilypond-extra}.
+
+@node Grand Unified Builder (GUB)
+@unnumberedsubsubsec Grand Unified Builder (GUB)
+
+Another item of interest might be the Grand Unified Builder, our
+cross-platform building tool.  Since it is used by other projects as
+well, it is not stored in our gub repository.  For more info, see
+@uref{http://lilypond.org/gub}.
+
+There are two locations for this repository: the version being used to
+build lilypond, which is at
+
+@example
+@uref{http://github.com/gperciva/gub}
+@end example
+
+and the original version by Jan Nieuwenhuizen, kept at
+
+@example
+@uref{http://github.com/janneke/gub}
+@end example
+
+
+@node lilypad
+@unnumberedsubsubsec lilypad
+
+Our binary releases on MacOS X and Windows contain a lightweight
+text editor.  This code is here:
+
+@example
+https://github.com/gperciva/lilypad
+@end example
+
+
+@node yet more repositories
+@unnumberedsubsubsec yet more repositories
+
+There are a few other repositories floating around, which will
+hopefully be documented in the near future.
+
+
+@node Downloading remote branches
+@subsection Downloading remote branches
+
+@warning{contains obsolete + misleading info}
+
+@menu
+* Organization of remote branches::
+* LilyPond repository sources::
+* Other branches::
+@end menu
+
+
+@node Organization of remote branches
+@unnumberedsubsubsec Organization of remote branches
+
+
+The main LilyPond repository is organized into @emph{branches} to
+facilitate development.  These are often called @emph{remote}
+branches to distinguish them from @emph{local} branches you might
+create yourself (see @ref{Using local branches}).
+
+The @code{master} branch contains all the source files used to
+build LilyPond, which includes the program itself (both stable and
+development releases), the documentation (and its translations),
+and the website.  Generally, the @code{master} branch is expected
+to compile successfully.
+
+The @code{translation} branch is a side branch that
+allows translators to work without needing to worry about
+compilation problems.  Periodically, the Translation Meister
+(after verifying that it doesn't break compilation), will
+@emph{merge} this branch into @code{staging} to incorporate
+recent translations.  Similarly, the @code{master} branch is
+usually merged into the @code{translation} branch after
+significant changes to the English documentation.  See
+@ref{Translating the documentation} for details.
+
+
+@node LilyPond repository sources
+@unnumberedsubsubsec LilyPond repository sources
+
+
+The recommended source for downloading a copy of the main
+repository is:
+
+@example
+git://git.sv.gnu.org/lilypond.git
+@end example
+
+However, if your internet router filters out connections using the
+GIT protocol, or if you experience difficulty connecting via GIT,
+you can try these other sources:
+
+@example
+ssh://git.sv.gnu.org/srv/git/lilypond.git
+http://git.sv.gnu.org/r/lilypond.git
+@end example
+
+The SSH protocol can only be used if your system is properly set
+up to use it.  Also, the HTTP protocol is slowest, so it should
+only be used as a last resort.
+

 
 @node Other branches
 @unnumberedsubsubsec Other branches
 
 @node Other branches
 @unnumberedsubsubsec Other branches


@@ -424,13 +683,10 @@ branch.
 @item @code{stable/XYZ}:
 The branches are kept for archival reasons.
 
 @item @code{stable/XYZ}:
 The branches are kept for archival reasons.
 

-@end itemize
+@item @code{archive/XYZ}:
+The branches are kept for archival reasons.

 
 

-Another item of interest might be the Grand Unified Builder, our
-cross-platform building tool.  Since it is used by projects as
-well, it is not stored in our gub repository.  For more info, see
-@uref{http://lilypond.org/gub}.  The git location is
-@uref{http://github.com/janneke/gub}.
+@end itemize

 
 
 @node Basic Git procedures
 
 
 @node Basic Git procedures


@@ -554,7 +810,7 @@ changed committishes in the head of translated files using commits
 you have not yet pushed to @code{git.sv.gnu.org}, please do not
 rebase.  If you want to avoid wondering whether you should rebase
 each time you pull, please always use committishes from master
 you have not yet pushed to @code{git.sv.gnu.org}, please do not
 rebase.  If you want to avoid wondering whether you should rebase
 each time you pull, please always use committishes from master

-and/or lilypond/translation branch on @code{git.sv.gnu.org}, which
+and/or translation branch on @code{git.sv.gnu.org}, which

 in particular implies that you must push your changes to
 documentation except committishes updates (possibly after having
 rebased), then update the committishes and push them.}
 in particular implies that you must push your changes to
 documentation except committishes updates (possibly after having
 rebased), then update the committishes and push them.}


@@ -674,12 +930,11 @@ git merge @var{foo}
 
 If any conflict happens, see @ref{Resolving conflicts}.
 
 
 If any conflict happens, see @ref{Resolving conflicts}.
 

-There are common usage cases for merging: as a translator, you
-will often want to merge @code{master} into
-@code{lilypond/translation}; on the other hand, the Translations
-meister wants to merge @code{lilypond/translation} into
-@code{master} whenever he has checked that
-@code{lilypond/translation} builds successfully.
+There are common usage cases for merging: as a translator, you will
+often want the Translations meister to merge @code{master} into
+@code{translation}; on the other hand, the Translations meister wants
+to merge @code{translation} into @code{staging} whenever he has
+checked that @code{translation} builds successfully.

 
 
 @node Commits and patches
 
 
 @node Commits and patches


@@ -918,7 +1173,7 @@ 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}).
 
 and @command{upload.py} scripts in one of your PATH
 directories (such as @file{$HOME/bin}).
 

-In Ubuntu (and Lilydev), you can add directories to PATH
+In Ubuntu (and LilyDev), you can add directories to PATH

 by adding this line to a hidden file @file{.bashrc},
 located in your home directory:
 
 by adding this line to a hidden file @file{.bashrc},
 located in your home directory:
 


@@ -942,20 +1197,28 @@ use any email address for your google account when you sign up.
 
 @item
 Move into the top source directory and then configure @command{git
 
 @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).
+cl} with the following commands:

 
 @example
 
 @example

-cd $HOME/lilypond-git/
+cd $LILYPOND_GIT

 git cl config
 @end example
 
 git cl config
 @end example
 

+For the @qq{Rietveld server} question, the default value
+(@qq{codereview.appspot.com}) should be accepted by
+answering with a newline (CR).
+

 The @qq{CC list} question should be answered with:
 
 @example
 lilypond-devel@@gnu.org
 @end example
 
 The @qq{CC list} question should be answered with:
 
 @example
 lilypond-devel@@gnu.org
 @end example
 

+The @qq{Tree status URL} value should be left blank.  So should
+the @qq{ViewVC URL} value, since it is used by @command{git cl
+dcommit} which is only for repositories which use @command{git
+svn} (LilyPond doesn't).
+

 @end enumerate
 
 @subsubheading Uploading patch set
 @end enumerate
 
 @subsubheading Uploading patch set


@@ -976,6 +1239,7 @@ git pull -r
 git cl upload origin/master
 @end example
 
 git cl upload origin/master
 @end example
 

+@c Mention staging here?

 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.
 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.


@@ -1016,6 +1280,11 @@ can be used.
 
 @end itemize
 
 
 @end itemize
 

+First you will see a terminal editor where you can edit the
+message that will accompany your patch. @command{git-cl} will
+respect the @env{EDITOR} environment variable if defined,
+otherwise it will use @command{vi} as the default editor.
+

 After prompting for your Google email address and password, the
 patch set will be posted to Rietveld, and you will be given a URL
 for your patch.
 After prompting for your Google email address and password, the
 patch set will be posted to Rietveld, and you will be given a URL
 for your patch.


@@ -1091,7 +1360,7 @@ in learning more about git.}
 
 It is possible to work with several branches on the same local Git
 repository; this is especially useful for translators who may have
 
 It is possible to work with several branches on the same local Git
 repository; this is especially useful for translators who may have

-to deal with both @code{lilypond/translation} and a stable branch,
+to deal with both @code{translation} and a stable branch,

 e.g. @code{stable/2.12}.
 
 Some Git commands are introduced first, then a workflow with
 e.g. @code{stable/2.12}.
 
 Some Git commands are introduced first, then a workflow with


@@ -1099,10 +1368,10 @@ several Git branches of LilyPond source code is presented.
 
 
 @menu
 
 
 @menu

+* Merge conflicts::

 * Advanced Git concepts::
 * Resolving conflicts::
 * Reverting all local changes::
 * Advanced Git concepts::
 * Resolving conflicts::
 * Reverting all local changes::

-* Working with remote branches::

 * Git log::
 * Applying remote patches::
 * Sending and receiving patches via email::
 * Git log::
 * Applying remote patches::
 * Sending and receiving patches via email::


@@ -1112,6 +1381,13 @@ several Git branches of LilyPond source code is presented.
 @end menu
 
 
 @end menu
 
 

+@node Merge conflicts
+@subsection Merge conflicts
+
+To be filled in later, and/or moved to a different section.  I
+just wanted to make sure that I had a stub ready somewhere.
+
+

 @node Advanced Git concepts
 @subsection Advanced Git concepts
 
 @node Advanced Git concepts
 @subsection Advanced Git concepts
 


@@ -1129,7 +1405,7 @@ git pull git://git.sv.gnu.org/lilypond.git/ @var{branch}:origin/@var{branch}
 
 @noindent
 where @code{@var{branch}} is typically @code{master} or
 
 @noindent
 where @code{@var{branch}} is typically @code{master} or

-@code{lilypond/translation}; if you do not know or remember, see
+@code{translation}; if you do not know or remember, see

 @ref{Downloading remote branches} to remember which commands you
 issued or which source code you wanted to get.
 
 @ref{Downloading remote branches} to remember which commands you
 issued or which source code you wanted to get.
 


@@ -1150,46 +1426,6 @@ commit, which is called the @emph{head} of the branch; when
 referring to a branch, one often actually thinks about its head
 and the ancestor commits of the 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
-source code from Git---see @ref{Downloading individual branches}.
-
-@example
-git remote add -ft @var{branch} -m @var{branch} \
-  origin git://git.sv.gnu.org/lilypond.git/
-
-git checkout -b @var{branch} origin/@var{branch}
-@end example
-
-The @command{git@tie{}remote} has created a branch called
-@code{origin/@var{branch}} in your local Git repository.  As this
-branch is a copy of the remote branch web from git.sv.gnu.org
-LilyPond repository, it is called a @emph{remote branch}, and is
-meant to track the changes on the branch from git.sv.gnu.org: it
-will be updated every time you run
-@command{git@tie{}pull@tie{}origin} or
-@command{git@tie{}fetch@tie{}origin}.
-
-The @command{git@tie{}checkout} command has created a branch named
-@code{@var{branch}}.  At the beginning, this branch is identical
-to @code{origin/@var{branch}}, but it will differ as soon as you
-make changes, e.g. adding newly translated pages or editing some
-documentation or code source file.  Whenever you pull, you merge
-the changes from @code{origin/@var{branch}} and
-@code{@var{branch}} since the last pulling.  If you do not have
-push (i.e. @qq{write}) access on git.sv.gnu.org, your
-@code{@var{branch}} will always differ from
-@code{origin/@var{branch}}.  In this case, remember that other
-people working like you with the remote branch @code{@var{branch}}
-of git://git.sv.gnu.org/lilypond.git/ (called
-@code{origin/@var{branch}} on your local repository) know nothing
-about your own @code{@var{branch}}: this means that whenever you
-use a committish or make a patch, others expect you to take the
-latest commit of @code{origin/@var{branch}} as a reference.
-
-Finally, please remember to read the man page of every Git command
-you will find in this manual in case you want to discover
-alternate methods or just understand how it works.
-

 
 @node Resolving conflicts
 @subsection Resolving conflicts
 
 @node Resolving conflicts
 @subsection Resolving conflicts


@@ -1223,77 +1459,6 @@ git reset --hard origin/master
 @end example
 
 
 @end example
 
 

-@node Working with remote branches
-@subsection Working with remote branches
-
-
-@subsubheading Fetching new branches from git.sv.gnu.org
-
-To fetch and check out a new branch named @code{@var{branch}} on
-git.sv.gnu.org, run from top of the Git repository
-
-@example
-git config --add remote.origin.fetch \
-  +refs/heads/@var{branch}:refs/remotes/origin/@var{branch}
-
-git checkout --track -b @var{branch} origin/@var{branch}
-@end example
-
-After this, you can pull @code{@var{branch}} from git.sv.gnu.org
-with:
-
-@example
-git pull
-@end example
-
-Note that this command generally fetches all branches you added
-with @command{git@tie{}remote@tie{}add} (when you initialized the
-repository) or @command{git@tie{}config@tie{}--add}, i.e. it
-updates all remote branches from remote @code{origin}, then it
-merges the remote branch tracked by the current branch into the
-current branch.  For example, if your current branch is
-@code{master}, @code{origin/master} will be merged into
-@code{master}.
-
-
-@subsubheading Local clones, or having several working trees
-
-If you play with several Git branches, e.g. @code{master},
-@code{lilypond/translation}, @code{stable/2.12}), you may want to
-have one source and build tree for each branch; this is possible
-with subdirectories of your local Git repository, used as local
-cloned subrepositories.  To create a local clone for the branch
-named @code{@var{branch}}, run
-
-@example
-git checkout @var{branch}
-git clone -lsn . @var{subdir}
-cd @var{subdir}
-git reset --hard
-@end example
-
-Note that @code{@var{subdir}} must be a directory name which does
-not already exist.  In @code{@var{subdir}}, you can use all Git
-commands to browse revisions history, commit and uncommit changes;
-to update the cloned subrepository with changes made on the main
-repository, cd into @code{@var{subdir}} and run
-@command{git@tie{}pull}; to send changes made on the subrepository
-back to the main repository, run @command{git@tie{}push} from
-@code{@var{subdir}}.  Note that only one branch (the currently
-checked out branch) is created in the subrepository by default; it
-is possible to have several branches in a subrepository and do
-usual operations (checkout, merge, create, delete...) on these
-branches, but this possibility is not detailed here.
-
-When you push @code{@var{branch}} from @code{@var{subdir}} to the
-main repository, and @code{@var{branch}} is checked out in the
-main repository, you must save uncommitted changes (see
-@command{git@tie{}stash}) and do
-@command{git@tie{}reset@tie{}--hard} in the main repository in
-order to apply pushed changes in the working tree of the main
-repository.
-
-

 @node Git log
 @subsection Git log
 
 @node Git log
 @subsection Git log
 


@@ -1330,10 +1495,10 @@ git am @var{patch}
 
 Patches created without @code{git@tie{}format-patch} can be
 applied in two steps.  The first step is to apply the patch to the
 
 Patches created without @code{git@tie{}format-patch} can be
 applied in two steps.  The first step is to apply the patch to the

-working tree:
+working tree and the index:

 
 @example
 
 @example

-git apply @var{patch}
+git apply --index @var{patch}

 @end example
 
 @noindent
 @end example
 
 @noindent


@@ -1341,9 +1506,16 @@ The second step is to commit the changes and give credit to the
 author of the patch.  This can be done with the following command:
 
 @example
 author of the patch.  This can be done with the following command:
 
 @example

-git commit -a --author="@var{John Smith} <@var{john@@example.com}>"
+git commit --author="@var{John Smith} <@var{john@@example.com}>"

 @end example
 
 @end example
 

+Please note that using the @code{--index} option for patching is quite
+important here and @emph{cannot} reliably be replaced by using the
+@code{-a} option when committing: that would only commit files from the
+working tree that are already registered with git, so every file that
+the patch actually @emph{adds}, like a regtest for a fixed bug, would
+get lost.  For the same reason, you should not use the git-independent
+@samp{patch} program for applying patches.

 
 @node Sending and receiving patches via email
 @subsection Sending and receiving patches via email
 
 @node Sending and receiving patches via email
 @subsection Sending and receiving patches via email


@@ -1561,7 +1733,7 @@ If @command{git@tie{}pull@tie{}--verbose} succeeds, the output
 will include a @q{From} line that shows @q{ssh} as the protocol:
 
 @example
 will include a @q{From} line that shows @q{ssh} as the protocol:
 
 @example

-From ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond
+From ssh://git.sv.gnu.org/srv/git/lilypond

 @end example
 
 If the protocol shown is not @q{ssh}, check that you configured
 @end example
 
 If the protocol shown is not @q{ssh}, check that you configured


@@ -1679,6 +1851,15 @@ patch has been lost.  Note that you can check the commits on
 @code{origin/staging} by looking at the git web interface on
 savannah.
 
 @code{origin/staging} by looking at the git web interface on
 savannah.
 

+It may happen occasionally that the staging branch breaks automated
+testing.  In this case the automatic move of staging material to
+master gets halted in order to avoid broken material entering master.
+This is a safety net.  Please do not try breaking out from it by
+adding fixes on top of staging: in that case the whole sequence will
+end up in master after all, defeating the purpose of the system.  The
+proper fix usually involves rewriting the staging branch and is best
+left to core developers after discussion on the developer list.
+

 @subsubheading If your work is in a patch file
 
 Assuming that your patch is in a file called
 @subsubheading If your work is in a patch file
 
 Assuming that your patch is in a file called


@@ -1723,7 +1904,7 @@ later on.  You should see that @code{staging} is only ahead of
 @section Git on Windows
 
 @warning{We heavily recommend that development be done with our
 @section Git on Windows
 
 @warning{We heavily recommend that development be done with our

-virtual machine @ref{Lilydev}.}
+virtual machine @ref{LilyDev}.}

 
 @c Some of this may duplicate stuff in other sections
 @c But it is probably best for windows users to have it all together
 
 @c Some of this may duplicate stuff in other sections
 @c But it is probably best for windows users to have it all together


@@ -2101,5 +2282,10 @@ More in-depth tutorials: @uref{http://git-scm.com/documentation}
 
 @item
 Book about git: @uref{http://progit.org/,Pro Git}
 
 @item
 Book about git: @uref{http://progit.org/,Pro Git}

+
+@item
+Github help: @uref{http://help.github.com/}
+(very highly recommended by Graham)
+

 @end itemize
 
 @end itemize