Doc-de: update macros.itely and nitpicks

[lilypond.git] / Documentation / devel / git-starting.itexi

diff --git a/Documentation/devel/git-starting.itexi b/Documentation/devel/git-starting.itexi
index e975e4d22810169d95a61e638f8079c6580be6a5..c50ba18da478da12cae1897b78e84198b30fda0e 100644 (file)
--- a/Documentation/devel/git-starting.itexi
+++ b/Documentation/devel/git-starting.itexi
@@ -4,14 +4,14 @@
 
 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::    
-* Sharing your changes::        
-* Advanced git stuff::          
-* Git on Windows::              
+* Getting the source code::
+* Updating the source code::
+* Sharing your changes::
+* Advanced git stuff::
+* Git on Windows::
 @end menu
 
 
@@ -19,13 +19,13 @@ at @uref{http://git-scm.com/documentation},
 @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
@@ -92,7 +92,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:
@@ -145,9 +145,9 @@ git config --global user.email MYEMAIL@@EXAMPLE.NET
 @section Updating the source code
 
 @menu
-* Importance of updating::      
-* Update command::              
-* Resolving conflicts::         
+* Importance of updating::
+* Update command::
+* Resolving conflicts::
 @end menu
 
 
@@ -171,7 +171,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
 
 
@@ -193,8 +193,8 @@ resolve conflicts} in @command{git merge} man page.
 @section Sharing your changes
 
 @menu
-* Producing a patch::           
-* Committing directly::         
+* Producing a patch::
+* Committing directly::
 @end menu
 
 
@@ -207,10 +207,26 @@ 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 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:
 
@@ -224,7 +240,8 @@ git add FILENAME
 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 attachmented.
+these files attached, and a developer will review and apply the
+patches to the main repository.
 
 
 @node Committing directly
@@ -276,11 +293,11 @@ 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::        
+* Introduction to Git concepts::
+* Git commands for managing several branches::
+* Working on LilyPond sources with several branches::
+* Git log::
+* Applying git patches::
 @end menu
 
 
@@ -562,9 +579,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
@@ -579,7 +601,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
@@ -680,6 +703,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,