@subsection Setting up
@warning{These instructions assume that you are using the
-command-line version of Git 1.7 or higher.}
+command-line version of Git 1.5 or higher. Windows users should
+skip to @ref{Git on Windows}.}
@menu
* Installing Git::
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.
+You may need to install the additional @code{bash-completion}
+package, but it is definitely worth it. After installation
+you must log out, and then log back in again to enable it.
@subsubheading Technical details
@menu
* lilypond-extra::
* Grand Unified Builder (GUB)::
-* lilypad::
+* LilyPad::
* yet more repositories::
@end menu
@end example
-@node lilypad
-@unnumberedsubsubsec lilypad
+@node LilyPad
+@unnumberedsubsubsec LilyPad
Our binary releases on MacOS X and Windows contain a lightweight
-text editor. This code is here:
+text editor.
+
+To make any modifications the Windows editor, you will need to do the
+following:
+
+@enumerate
+@item
+Clone the git repository from @code{https://github.com/gperciva/lilypad}
+
+@item
+Make changes to the source, and check it compiles. In a Windows environment
+@code{MinGW} provides both a @code{Git} installation and a @code{gcc}
+compiler. This can be obtained from @code{http://www.mingw.org/}
+
+@item
+Update the version which is contained in the @file{rsrc.rc}. Check
+this compiles, too.
+
+@item
+Commit the changes with an informative commit message.
+
+@item
+Push the changes to github. You will need to use syntax similiar to this:
@example
-https://github.com/gperciva/lilypad
+git push https://UserName@@github.com/gperciva/lilypad.git
@end example
+You will need to have push access to the git repository for this to be
+successful.
+
+@item
+Make a tarball of the source code to be used by GUB by pulling the updated
+repository from GitHub. Ensure that the tarball has the correct Version
+number.
+
+@item
+Copy the tarball to @code{http://lilypond.org/download/gub-sources/lilypad/}.
+You will need to have SSH access to @code{lilypond.org}. If you do not, contact
+the Release Manager via the lilypond-devel mailing list.
+
+@item
+Update GUB to make it use the new tarball by editing
+@file{gub/specs/lilypad.py} and changing the @code{source =} line to point to
+the new source.
+
+@item
+Push this updated @file{lilypad.py} version to the GUB repository on GitHub.
+
+@item
+Test the changes with a new GUB compile.
+
+@end enumerate
@node yet more repositories
@unnumberedsubsubsec yet more repositories
@menu
* Organization of remote branches::
* LilyPond repository sources::
+* Downloading individual branches::
+* Downloading all remote branches::
+* Other branches::
@end menu
@ref{Translating the documentation} for details.
-Most contributors will never need to touch the other branches. If
-you wish to do so, you will need more familiarity with Git; please
-see @ref{Other Git documentation}.
-
-@itemize
-@item @code{dev/XYZ}:
-These branches are for individual developers. They store code
-which is not yet stable enough to be added to the @code{master}
-branch.
-
-@item @code{stable/XYZ}:
-The branches are kept for archival reasons.
-
-@item @code{archive/XYZ}:
-The branches are kept for archival reasons.
-
-@end itemize
-
-
@node LilyPond repository sources
@unnumberedsubsubsec LilyPond repository sources
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
+
+Most contributors will never need to touch the other branches. If
+you wish to do so, you will need more familiarity with Git; please
+see @ref{Other Git documentation}.
+
+@itemize
+@item @code{dev/XYZ}:
+These branches are for individual developers. They store code
+which is not yet stable enough to be added to the @code{master}
+branch.
+
+@item @code{stable/XYZ}:
+The branches are kept for archival reasons.
+
+@item @code{archive/XYZ}:
+The branches are kept for archival reasons.
+
+@end itemize
+
+
@node Basic Git procedures
@section Basic Git procedures
can be used.
Occasionally you may need to rework some of your own modifications
-to match changes made to the remote branch (see @ref{Merge
+to match changes made to the remote branch (see @ref{Resolving
conflicts}), and it's considerably easier to rework things
incrementally. If you don't update your repository along the way,
you may have to spend a lot of time resolving branch conflicts and
Note that @command{git@tie{}stash@tie{}pop} will try to apply a
patch, and this may create a conflict. If this happens, see
-@ref{Merge conflicts}.
+@ref{Resolving conflicts}.
TODO: I think the next paragraph is confusing. Perhaps prepare
the reader for new terms `committish' and `head'? -mp
git merge @var{foo}
@end example
-If any conflict happens, see @ref{Merge conflicts}.
+If any conflict happens, see @ref{Resolving conflicts}.
There are common usage cases for merging: as a translator, you will
often want the Translations meister to merge @code{master} into
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 GNU/Linux you can add directories to PATH
by adding this line to a hidden file @file{.bashrc},
located in your home directory:
@enumerate
@item
-You must have a google account; please create one if you do not
+You must own a Google account login; please create one if you do not
have one already.
-Note that a google account does not need to be a gmail account; you can
-use any email address for your google account when you sign up.
+@noindent
+Note that a google account does not need to be a Gmail account; you can
+use @emph{any} email address for your google account when you sign up.
+
+@warning{In order for @code{git-cl} to work as expected, your Google
+Account Settings must have the @q{Access for less secure apps} set to
+@q{Allowed}. This is normally the default setting.}
@item
-Move into the top source directory and then configure @command{git
-cl} with the following commands:
+Move into the top source directory and then configure
+@command{git-cl} with the following commands:
@example
cd $LILYPOND_GIT
-git cl config
+git-cl config
@end example
For the @qq{Rietveld server} question, the default value
@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
+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).
@subsubheading Uploading patch set
+This section assumes that you have already configured the
+@command{git-cl} @q{helper-script}. See @ref{git-cl}.
+
@warning{Unless you are familiar with branches, only work on one
set of changes at once.}
@itemize
@item
-@strong{Master branch}: (easy option, and used in @command{lily-git.tcl})
+@strong{Master branch}: (easy option)
If you added your patch to @code{master}, then:
@example
git pull -r
-git cl upload origin/master
+git-cl upload origin/master
@end example
@c Mention staging here?
@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
-changes to be uploaded. If the reference branch is to be
-origin/master, ensure this is up-to-date. If necessary, use git
-rebase to rebase the branch containing the changes to the head of
-origin/master. Finally, check out branch with the changes and
-enter the command:
+Ensure your changes are committed in a separate branch, which should
+differ from the reference branch to be used (usually
+@code{origin/master}) by just the changes to be uploaded. Checkout the
+branch with the changes:
@example
-git cl upload <reference SHA1 ID>
+git checkout some-branch-with-changes
+@end example
+
+If the reference branch is to be @code{origin/master}, ensure that the
+branch containing the changes is up-to-date with it. Use
+@command{git rebase} or @command{git pull -r} to rebase the branch to
+the head of @code{origin/master}. For example:
+
+@example
+git pull -r origin master
+@end example
+
+Finally, start the upload by entering:
+
+@example
+git-cl upload <reference SHA1 ID>
@end example
@noindent
SHA1 ID of origin/master, and in that case the command:
@example
-git cl upload origin/master
+git-cl upload origin/master
@end example
@noindent
the following command can be used:
@example
-git cl issue issue-number
+git-cl issue issue-number
@end example
@noindent
where @code{issue-number} is the number of the existing Rietveld
issue.
-@subsubheading Resetting git cl
+@subsubheading Resetting git-cl
-If @command{git cl} becomes confused, you can @qq{reset} it by
+If @command{git-cl} becomes confused, you can @qq{reset} it by
running:
@example
-git cl issue 0
+git-cl issue 0
@end example
@subsubheading Wait for a countdown
@menu
* Merge conflicts::
* Advanced Git concepts::
+* Resolving conflicts::
* Reverting all local changes::
+* Working with remote branches::
* Git log::
* Applying remote patches::
* Sending and receiving patches via email::
@node Merge conflicts
@subsection Merge conflicts
-
-Occasionally an update may result in conflicts -- this happens
-when you and somebody else have modified the same part of the same
-file and git cannot figure out how to merge the two versions
-together. When this happens, you must manually merge the two
-versions.
-
-If you need some documentation to understand and resolve
-conflicts, see paragraphs @emph{How conflicts are presented} and
-@emph{How to resolve conflicts} in @command{git merge} man page.
-
-If all else fails, you can follow the instructions in
-@ref{Reverting all local changes}. Be aware that this eliminates
-any changes you have made!
+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
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
+
+
+Occasionally an update may result in conflicts -- this happens
+when you and somebody else have modified the same part of the same
+file and git cannot figure out how to merge the two versions
+together. When this happens, you must manually merge the two
+versions.
+
+If you need some documentation to understand and resolve
+conflicts, see paragraphs @emph{How conflicts are presented} and
+@emph{How to resolve conflicts} in @command{git merge} man page.
+
+If all else fails, you can follow the instructions in
+@ref{Reverting all local changes}. Be aware that this eliminates
+any changes you have made!
+
@node Reverting all local changes
@subsection Reverting all local changes
@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
projects / lilypond.git / blobdiff