From aa404c7fa82fb478b393424c8b907854d191e93c Mon Sep 17 00:00:00 2001 From: Trevor Daniels Date: Sun, 11 Jan 2009 15:49:22 +0000 Subject: [PATCH] Docs: CG 1.6 Git on Windows: First draft --- Documentation/devel/git-starting.itexi | 284 +++++++++++++++++++++++++ 1 file changed, 284 insertions(+) diff --git a/Documentation/devel/git-starting.itexi b/Documentation/devel/git-starting.itexi index 0b2e4e9214..f3949a12c2 100644 --- a/Documentation/devel/git-starting.itexi +++ b/Documentation/devel/git-starting.itexi @@ -302,5 +302,289 @@ git-apply @node Git on Windows @section Git on Windows +@c Some of this may duplicate stuff in other sections +@c Clear this up later -td + +@subsection Background to nomenclature + +Git is a system for tracking the changes made to source files by +a distributed set of editors. It is designed to work without a +master repository, but we have chosen to have a master respository +for LilyPond files. Editors hold local copies of the master +repository together with any changes they have made locally. Local +changes are held in a local @q{branch}, of which there may be +several. The files in the local repository always correspond to +those on the currently @q{checked out} local branch. + +Files are edited on a local branch, and in that state the +changes are said to be @q{unstaged}. When editing is complete, the +changes are moved to being @q{staged for commit}, and finally the +changes are @q{committed} to the local branch. Once +committed, the changes are given a unique reference number called the +@q{Committish} which identifies them to Git. Such committed changes +can be sent to the master repository by @q{pushing} them (if you +have write permission) or by sending them by email to someone who +has, either complete or as a @q{diff} or @q{patch} (which send +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. Start Git by clicking on the desktop icon. +This will bring up a command line bash shell. This will be +unfamiliar to most Windows users, so follow these +instructions carefully. Commands are entered at a $ prompt +and are terminated by keying a newline. + +@subsection Initialising Git + +Decide where you wish to place your local Git repository, +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 + +@example +cd [path]/Git +@end example + +to position the shell at your new Git repository. + +Note: if [path] contains folders with names containing +spaces use + +@example +cd "[path]/Git" +@end example + +Then type + +@example +git init +@end example + +to initialize your Git repository. + +Then type (all on one line; the shell will wrap automatically) + +@example +git remote add -f -t master origin git://git.sv.gnu.org/lilypond.git +@end example + +to download the lilypond master files. + +@warning{Be patient! Even on a broadband connection this can take +10 minutes or more. Wait for lots of [new tag] messages +and the $ prompt.} + +We now need to generate a local copy of the downloaded files +in a new local branch. Your local branch needs to have a +name, here we call it @q{lily-local} - make up your own. +Then, finally, type + +@example +git checkout -b lily-local origin/master +@end example + +to create the lily-local branch containing the local copies of the +master files. You will be advised your local branch has been set +up to track the remote branch. + +Return to Windows and look in your Git repository. You +should see lots of folders. The LilyPond documentation +can be found in Git/Documentation/user. + +Terminate the Git bash shell with the exit command. + +@subsection Git GUI + +Almost all subsequent work will use the Git Graphical User +Interface, which avoids having to type command line +commands. To start Git GUI first start the Git bash shell by +clicking on the desktop icon, and type + +@example +cd [path]/Git +git gui +@end example + +The Git GUI will open in a new window. It contains four panels +and 7 pull-down menus. At this stage do not use any of the +commands under Branch, Commit, Merge or Remote. These will +be explained later. + +The two panels on the left contain the names of files which +you are in the process of editing (Unstaged Changes),and +files you have finished editing and have staged ready for +committing (Staged Changes). At this stage these panels will +be empty as your local branch is the same as the master branch. +After a file has been edited and saved the top panel on the right +will display the differences between the edited file selected +from one of the left panels and the one on master. The +final panel at bottom right is used to enter a descriptive +message about the change before committing a file. + +The Git GUI is terminated by entering CNTL-Q while it is the +active window or by clicking on the usual Windows close-window +widget. + +@subsection Personalising your local git repository + +Open the Git GUI, click on + +@example +Edit -> Options +@end example + +and enter your name and email address in the +left-hand (Git Repository) panel. Leave everything +else unchanged and save it. + +@subsection Checking out a branch + +At this stage you have two branches in your local repository, +both identical. To see them click on + +@example +Branch -> Checkout +@end example + +You should have one local branch called lily-local and one +tracking branch called origin/master. + +When a particular branch is selected, i.e., checked out, the +files visible in your repository are changed to reflect the +changes made on that branch. + +@subsection Updating files from master + +Before starting the editing of a file ensure you have the +latest copy from master by first clicking + +@example +Remote -> Fetch from -> origin +@end example + +in the Git GUI. + +This will place details of all the changes made by others +into the @q{origin/master} branch of the tracking branches +in your git repository. You can see these files by checking +out this branch. This will not affect any files +you have modified in any of your local branches. + +To merge the changed files into your local branch click on + +@example +Merge -> Local Merge +@end example + +and if necessary select the local branch into which the merge +is to be made. + +This will update all the files in that branch to reflect the +currect state of the origin/master branch. If any of the changes +conflict with changes you have made yourself recently +you will be notified of the conflict (see below). + +@subsection Editing files + +Simply edit the files in your local Git repository with +your favourite editor and save them back there. If any file contains +non-ASCII characters ensure you save it in UTF8 format. Git will +detect any changes whenever you restart Git GUI +and the file names will then be listed in the Unstaged Changes panel. +Or you can click the Rescan button to refresh the panel +contents at any time. You may break off and resume at +editing any time. + +The changes you have made may be displayed in diff form +in the top right-hand panel by clicking on the name in +Git GUI. + +When your editing is complete, move the files from being +Unstaged to Staged by clicking the document symbol to +the left of each name. If you change your mind it can +be moved back by clicking on the ticked box to the +left of the name. + +If you wish to cancel your changes the original version +may be recovered at any time before a commit is made +by selecting Commit -> Revert changes. This will even +recover a deleted file. + +Finally the changes you have made may be committed to +your local branch by entering a brief message in +the Commit Message box and clicking the Commit button. + +@sebsection Sending changes to origin/master + +If you do not have write access to master you will +need to send your changes by email to someone who does. + +First you need to create a diff or patch file containing +your changes. To create this, the file must first be +committed. Then terminate the Git GUI. In the +git bash shell first cd to your Git repository with + +@example +cd [path]/Git +@end example + +if necessary, then produce the patch with + +@example +git-format-patch -n +@end example + +where n an integer, normally 1. This will create a +patch file for all the locally committed files which +differ from master. The patch file can be found in +[path]/Git and will have a name formed from n and the +commit message. + +@subsection Resolving merge conflicts + +As soon as you have committed a changed file your +local branch has diverged from master, and will +remain diverged until your changes have been committed +in master. Similarly, if a new commit has been made +to master by someone else, your branch is divergent. +You can detect a divergent branch my clicking on + +@example +Repository -> Visualise all branch history +@end example + +This opens up a very useful new window called @q{gitk}. + +If the diagram at top left of the resulting window +does not show your branch on a single node at the +top your branch has diverged from master. This is +quite normal if files you have modified yourself +have not yet been committed to master, or if files +have been modified and committed by others since +your last merge. + +If a file being merged from master differs from +one you have modified in a way that cannot be resolved +automatically by git, Merge will report a Conflict +which you must resolve by editing the file to create the +version you wish to keep. + +This could happen if the person updating master +for you has added some changes of his own before +committing your changes to master, or if someone +else has updated the same parent file as you at +the same time. + +Open the file in your editor and look for sections which +are delimited with + +[to be completed when I next have a merge conflict to be +sure I give the right instructions -td] -- 2.39.2