X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fdevel%2Fgit-starting.itexi;h=6d6d55e86c358c9155a7a7076dd6326e8bed44f2;hb=1423508c355989fa26a8cfe5985b0d6e1ab0a538;hp=165122f52f60b966aadd7f0ba4479e27bfb2f889;hpb=38d7d319eabc906e82fb42002678c6d42a23b6f7;p=lilypond.git

diff --git a/Documentation/devel/git-starting.itexi b/Documentation/devel/git-starting.itexi
index 165122f52f..6d6d55e86c 100644
--- a/Documentation/devel/git-starting.itexi
+++ b/Documentation/devel/git-starting.itexi
@@ -4,15 +4,15 @@
 
 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::  
+* Advanced git stuff::          
 * Git on Windows::              
+* Development inside VirtualBox (compiling on Windows)::  
 @end menu
 
 
@@ -93,7 +93,7 @@ you wish to do so, you will need more familiarity with git.
 
 @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:
@@ -149,7 +149,6 @@ git config --global user.email MYEMAIL@@EXAMPLE.NET
 * Importance of updating::      
 * Update command::              
 * Resolving conflicts::         
-* Introduction to Git concepts::  
 @end menu
 
 
@@ -173,7 +172,7 @@ local copy of the repository with the changes made by others on
 the remote @code{git.sv.gnu.org} repository:
 
 @example
-git pull origin
+git pull -r
 @end example
 
 
@@ -191,6 +190,134 @@ see paragraphs @emph{How conflicts are presented} and @emph{How to
 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,
+go to @q{Account Configuration}, then to something like
+@q{Edit SSH Keys}, and follow the instructions on that page.
+
+You may then:
+
+@example
+git push origin
+@end example
+
+Note that recent versions of Git (Git 1.6.3 or later) will issue a
+big warning if the above command is used.  The simplest solution
+is to add a new section to @file{.git/config} that looks like
+this:
+
+@example
+[push]
+        default = matching
+@end example
+
+@noindent
+Then @code{git push origin} will work as before.  For more
+details, consult the @code{git push} man page.
+
+
+@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::        
+* Reverting all local changes::  
+@end menu
+
+
 @node Introduction to Git concepts
 @subsection Introduction to Git concepts
 
@@ -266,22 +393,6 @@ will find in this manual in case you want to discover alternate
 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
 
@@ -417,73 +528,6 @@ order to apply pushed changes in the working tree of the main
 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
 
@@ -501,22 +545,45 @@ gitk        # shows history graphically
 @warning{The @code{gitk} command may require a separate @code{gitk} package,
 available in the appropriate distribution's repositories.}
 
+
 @node Applying git patches
 @subsection Applying git patches
 
-Well-formed git patches should be committed with
+Well-formed git patches created with @code{git format-patch}
+should be committed with the following command:
 
 @example
-git am
+git am @var{patch}
 @end example
 
-Patches created without @code{git format-patch} should be
-committed with
+Patches created without @code{git format-patch} can be applied in
+two steps.  The first step is to apply the patch to the working
+tree:
 
 @example
-git apply
+git apply @var{patch}
 @end example
 
+@noindent
+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
+git commit -a --author="First Last <user@@example.net>"
+@end example
+
+
+@node Reverting all local changes
+@subsection Reverting all local changes
+
+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:
+
+@example
+git reset --hard origin/master
+@end example
 
 
 @node Git on Windows
@@ -551,9 +618,14 @@ just the differences from master).
 @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
@@ -568,7 +640,8 @@ creating the folders in Windows as necessary.  Here we
 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
@@ -669,6 +742,15 @@ and enter your name and email address in the
 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,
@@ -859,3 +941,11 @@ supplement these include
 
 Once familiarity with using git on Windows has been gained the
 standard git manuals can be used to learn about these.
+
+
+@node Development inside VirtualBox (compiling on Windows)
+@section Development inside VirtualBox (compiling on Windows)
+
+
+
+