@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}.}
Further instructions are in @ref{How to use lily-git}.
@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::
@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 the @emph{top source directory}.}
Before working with the copy of the main LilyPond repository, you
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 chages first.
+commit your changes first.
@example
git commit -a
@end example
To configure an environment variable in bash (the default for most
-Linux distributions),
+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 projects as
+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, which will hopefully
-be kept up-to-date with each other:
+There are two locations for this repository: the version being used to
+build lilypond, which is at
@example
-@uref{http://github.com/janneke/gub}
@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
@menu
* Organization of remote branches::
* LilyPond repository sources::
-* Downloading individual branches::
-* Downloading all remote branches::
* Other branches::
@end menu
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
+@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
only be used as a last resort.
-@node Downloading individual branches
-@unnumberedsubsubsec Downloading individual branches
-
-@warning{obsolete, should be deleted!}
-
-
-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:
-
-@example
-git remote add -ft master -m master \
- origin git://git.sv.gnu.org/lilypond.git/
-@end example
-
-To download the @code{translation} branch, enter:
-
-@example
-git remote add -ft translation -m \
- translation origin git://git.sv.gnu.org/lilypond.git/
-@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:
-
-@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
-@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:
-
-@example
-git checkout -b @var{branch} origin/@var{branch}
-@end example
-
-@noindent
-where @code{@var{branch}} is the name of your tracking branch,
-either @code{master} or @code{translation}.
-
-Git will issue some warnings; this is normal:
-
-@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'
-@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}.
-
-@subsubheading Technical Details
-
-The @command{git@tie{}remote@tie{}add} command should add some
-lines to your local repository's @file{.git/config} file:
-
-@example
-[remote "origin"]
- url = git://git.sv.gnu.org/lilypond.git/
- fetch = +refs/heads/master:refs/remotes/origin/master
-@end example
-
-
-@node Downloading all remote branches
-@unnumberedsubsubsec Downloading all remote branches
-
-
-To download all remote branches at once, you can @command{clone}
-the entire repository:
-
-@example
-git clone git://git.sv.gnu.org/lilypond.git
-@end example
-
-
@node Other branches
@unnumberedsubsubsec Other branches
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{translation}; on the other hand, the Translations
-meister wants to merge @code{translation} into
-@code{master} whenever he has checked that
-@code{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
@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
-cd $HOME/lilypond-git/
+cd $LILYPOND_GIT
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{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
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.
@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.
* Advanced Git concepts::
* Resolving conflicts::
* Reverting all local changes::
-* Working with remote branches::
* Git log::
* Applying remote patches::
* Sending and receiving patches via email::
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
@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{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
@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
projects / lilypond.git / blobdiff