To complete or present in another form the introduction to Git usage
in this chapter, it may be a good idea to look for Git documentation
-at @uref{http://git-scm.com/documentation},
+at @uref{http://git-scm.com/documentation},
@menu
-* Getting the source code::
-* Updating the source code::
-* Working with several Git branches::
-* Sharing your changes::
-* Other interesting Git commands::
-* Git on Windows::
+* Getting the source code::
+* Updating the source code::
+* Sharing your changes::
+* Advanced git stuff::
+* Git on Windows::
@end menu
@section Getting the source code
@menu
-* Git introduction::
-* Main source code::
-* Website source code::
-* Documentation translations source code::
-* Other branches::
-* Other locations for git::
-* Git user configuration::
+* Git introduction::
+* Main source code::
+* Website source code::
+* Documentation translations source code::
+* Other branches::
+* Other locations for git::
+* Git user configuration::
@end menu
@node Git introduction
@item @code{gub}:
This stores the Grand Unified Binary, our cross-platform building
-tool.
+tool.
@c TODO: merge the gub stuff with this CG.
For more info, see @uref{http://lilypond.org/gub}. The git
location is:
@section Updating the source code
@menu
-* Importance of updating::
-* Update command::
-* Resolving conflicts::
-* Introduction to Git concepts::
+* Importance of updating::
+* Update command::
+* Resolving conflicts::
@end menu
the remote @code{git.sv.gnu.org} repository:
@example
-git pull origin
+git pull -r
@end example
resolve conflicts} in @command{git merge} man page.
+@node Sharing your changes
+@section Sharing your changes
+
+@menu
+* Producing a patch::
+* Committing directly::
+@end menu
+
+
+@node Producing a patch
+@subsection Producing a patch
+
+Once you have finished editing your files, checked that your changes
+meet the @ref{Code style}, and/or @ref{Documentation policy}, properly
+set up your name and email in @ref{Git user configuration}, and
+checked that the entire thing compiles, you may:
+
+@example
+git commit -a
+git format-patch origin
+@end example
+
+The commit should include a brief message describing the change.
+This consists of a one-line summary describing the change, and
+if necessary a blank line followed by several lines giving the
+details:
+
+@example
+Did household chores.
+
+I hung up the wet laundry and then washed the car. I also
+vacuumed the floors, rinsed the dirty dishes, fed the cat, and
+recalibrated the temporal flux machine.
+@end example
+
+If the change is to the documentation only then the one-line
+summary should be prefixed with @qq{Docs: }.
+
+If you added a file to the source code, you must add it to git
+with:
+
+@example
+git add FILENAME
+@end example
+
+@noindent
+(and possibly modify the @file{GNUmakefile})
+
+These commands will produce one or more files named
+@file{0001-xyz}, @file{0002-abc}, etc. in the top directory of the
+git tree. Send an email to @email{lilypond-devel@@gnu.org} with
+these files attached, and a developer will review and apply the
+patches to the main repository.
+
+
+@node Committing directly
+@subsection Committing directly
+
+Most contributors do not have permission to commit directly. If you
+do, make sure you have set up your name and email in @ref{Git user
+configuration}, then edit @file{.git/config}: change the line
+
+@example
+url = git://git.sv.gnu.org/lilypond.git/
+@end example
+
+@noindent
+into
+
+@example
+url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
+@end example
+
+@noindent
+where @var{user} is your login name on Savannah.
+
+If you have not already done so, you should generate and upload a SSH
+key: open @uref{https://savannah.gnu.org/my/} in your browser, then go to
+@q{Preferences} then to something like @q{Edit SSH Keys}, and follow
+the instructions on that page.
+
+You may then:
+
+@example
+git push origin
+@end example
+
+@node Advanced git stuff
+@section Advanced git stuff
+
+@warning{This section is not necessary for normal contributors;
+these commands are presented for information for people interested
+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 to
+deal with both @code{lilypond/translation} and a stable branch,
+e.g. @code{stable/2.12}.
+
+Some Git commands are introduced first, then a workflow with several
+Git branches of LilyPond source code is presented.
+
+@menu
+* Introduction to Git concepts::
+* Git commands for managing several branches::
+* Working on LilyPond sources with several branches::
+* Git log::
+* Applying git patches::
+@end menu
+
+
@node Introduction to Git concepts
@subsection Introduction to Git concepts
methods or just understand how it works.
-@node Working with several Git branches
-@section Working with several Git branches
-
-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,
-e.g. @code{stable/2.12}.
-
-Some Git commands are introduced first, then a workflow with several
-Git branches of LilyPond source code is presented.
-
-@menu
-* Git commands for managing several branches::
-* Working on LilyPond sources with several branches::
-@end menu
-
@node Git commands for managing several branches
@subsection Git commands for managing several branches
repository.
-@node Sharing your changes
-@section Sharing your changes
-
-@menu
-* Producing a patch::
-* Committing directly::
-@end menu
-
-
-@node Producing a patch
-@subsection Producing a patch
-
-Once you have finished editing your files, checked that your changes
-meet the @ref{Code style}, and/or @ref{Documentation policy}, properly
-set up your name and email in @ref{Git user configuration}, and
-checked that the entire thing compiles, you may
-
-@example
-git commit -a
-git format-patch origin
-@end example
-
-Send an email to @email{lilypond-devel@@gnu.org} with the diff as
-an attachment.
-
-
-@node Committing directly
-@subsection Committing directly
-
-Most contributors do not have permission to commit directly. If you
-do, make sure you have set up your name and email in @ref{Git user
-configuration}, then edit @file{.git/config}: change the line
-
-@example
- url = git://git.sv.gnu.org/lilypond.git/
-@end example
-
-@noindent
-into
-@example
- url = ssh://@var{user}@@git.sv.gnu.org/srv/git/lilypond.git
-@end example
-
-@noindent
-where @var{user} is your login name on Savannah.
-
-If you have not already done so, you should generate and upload a SSH
-key: open @uref{https://savannah.gnu.org/my/} in your browser, then go to
-@q{Preferences} then to something like @q{Edit SSH Keys}, and follow
-the instructions on that page.
-
-You may then
-
-@example
-git push origin
-@end example
-
-
-@node Other interesting Git commands
-@section Other interesting Git commands
-
-@menu
-* Git log::
-* Applying git patches::
-@end menu
-
@node Git log
@subsection Git log
@subsection Installing git
Obtain Git from
-@uref{http://code.google.com/p/msysgit/downloads/list}.
-(Note, not msysGit, which is for Git developers) and
-install.
+@uref{http://code.google.com/p/msysgit/downloads/list}
+(note, not msysGit, which is for Git developers and not PortableGit,
+which is not a full git installation) and
+install it.
+
+Note that most users will not need to install SSH. That is not
+required until you have been granted direct push permissions to
+the master git repository.
Start Git by clicking on the desktop icon.
This will bring up a command line bash shell. This may be
call the folder to contain the repository [path]/Git.
You will need to have space for around 150Mbytes.
-In the git bash shell type
+Start the Git bash shell by clicking on the desk-top icon installed
+with Git and type
@example
cd [path]/Git
left-hand (Git Repository) panel. Leave everything
else unchanged and save it.
+Note that Windows users must leave the default setting for line
+endings unchanged. All files in a git repository must have lines
+terminated by just a LF, as this is required for Merge to work, but
+Windows files are terminated by CRLF by default. The git default
+setting causes the line endings of files in a Windows git repository
+to be flipped automatically between LF and CRLF as required. This
+enables files to be edited by any Windows editor without causing
+problems in the git repository.
+
@subsection Checking out a branch
At this stage you have two branches in your local repository,
projects / lilypond.git / blobdiff