* Updating the source code::
* Sharing your changes::
* Other interesting Git commands::
-* Applying git patches::
* Git on Windows::
@end menu
@node Getting the source code
@section Getting the source code
-The source code is kept in a git respository.
-
-@warning{These instructions assume that you are using the
-command-line version of git 1.5 or higher.}
-
-
@menu
+* Git introduction::
* Main source code::
* Website source code::
* Documentation translations source code::
* Git user configuration::
@end menu
+@node Git introduction
+@subsection Git introduction
+
+The source code is kept in a git respository. This allows us to
+track changes to files, and for multiple people to work on the
+same set of files (generally) without any problems.
+
+@warning{These instructions assume that you are using the
+command-line version of git 1.5 or higher. Windows users should
+skip to @ref{Git on Windows}.}
+
+
@node Main source code
@subsection Main source code
To get the website (including translations),
+FIXME: test this!!!
+
@example
-mkdir lilyweb ; cd lilyweb
+mkdir lilypod-web ; cd lilypond-web
git init-db
git remote add -f -t web -m web origin git://git.sv.gnu.org/lilypond.git/
git checkout -b web origin/web
To translate the documentation (@emph{not} the website),
-FIXME: change
+FIXME: change!!!
@example
-mkdir lilytranslate ; cd lilytranslate
+mkdir lilypond-translate; cd lilypond-translate
git init-db
git remote add -f -t web -m web origin git://git.sv.gnu.org/lilypond.git/
git checkout -b web origin/web
@item @code{gub}:
This stores the Grand Unified Binary, our cross-platform building
-tool.
+tool. For more info, see @uref{http://lilypond.org/gub}. The git
+location is:
@example
-FIXME: insert new gub addy
+http://github.com/janneke/gub
@end example
@item @code{dev/XYZ}:
* Technical notes::
@end menu
+
@node Importance of updating
@subsection Importance of updating
However, serious problems can arise if you do not pull before
attempting commit.
+
@node Update command
@subsection Updating command
git pull origin
@end example
+
@node Resolving conflicts
@subsection Resolving conflicts
@node Technical notes
@subsection Technical notes
-Let's explain a bit of Git vocabulary. The @code{git pull
-origin} command is just a shortcut for this command:
+TODO: I'm not going to bother with this section. -gp
+
+Let's explain a bit of Git vocabulary. The @code{git pull origin}
+command is just a shortcut for this command:
@example
git pull git://git.sv.gnu.org/lilypond.git/ MY-BRANCH:origin/MY-BRANCH
@end example
-A commit is a set of changes made to the sources; it also includes the
-committish of the parent commit, the name and e-mail of the author
-(the person who wrote the changes), the name and e-mail of the
-committer (the person who brings these changes into the git
+A commit is a set of changes made to the sources; it also includes
+the committish of the parent commit, the name and e-mail of the
+author (the person who wrote the changes), the name and e-mail of
+the committer (the person who brings these changes into the git
repository), and a commit message.
A committish is the SHA1 checksum of a commit, a number made of 40
-hexadecimal digits, which acts as the internal unique identifier for
-this commit. To refer to a particular revision, don't use vague
-references like the (approximative) date, simply copy'n'paste the
-committish.
-
-A branch is a tree (in the mathematical or computer science sense) of
-commits, and the topmost commit of this branch is called a head.
-
-The "git fetch" command above has created a branch called origin/web
-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 `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 'git
-pull' or 'git fetch' with this branch reference as argument, e.g.
-by using .git/remotes/web remote file when running 'git fetch web'.
+hexadecimal digits, which acts as the internal unique identifier
+for this commit. To refer to a particular revision, don't use
+vague references like the (approximative) date, simply
+copy'n'paste the committish.
+
+A branch is a tree (in the mathematical or computer science sense)
+of commits, and the topmost commit of this branch is called a
+head.
+
+The "git fetch" command above has created a branch called
+@code{origin/web} 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 `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 'git pull' or 'git fetch' with this branch
+reference as argument, e.g. by using .git/remotes/web remote file
+when running 'git fetch web'.
The 'git checkout' command above has created a branch named 'web'. At
the beginning, this branch is identical to 'origin/web', but it will
-
@node Sharing your changes
@section Sharing your changes
-
@menu
* Producing a patch::
* Committing directly::
@end menu
+
@node Producing a patch
@subsection Producing a patch
you do, edit @file{.git/config} to contain
@example
-FIXME?
+FIXME? Is anything needed, or did the previous commands set it
+up?
@end example
You may then @code{git push}.
@node Other interesting Git commands
@section Other interesting Git commands
+@menu
+* Git log::
+* Applying git patches::
+@end menu
+
+
+@node Git log
+@subsection Git log
+
The commands above don't only bring you the latest version of the
sources, but also the full history of revisions (revisons, also
called commits, are changes made to the sources), stored in the
@node Applying git patches
-@section Applying git patches
+@subsection Applying git patches
Well-formed git patches should be committed with
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.
+several, but these instructions assume you are using just one. The
+files visible 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
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
+install.
+
+Start Git by clicking on the desktop icon.
+This will bring up a command line bash shell. This may be
+unfamiliar to Windows users. If so, follow these
instructions carefully. Commands are entered at a $ prompt
and are terminated by keying a newline.
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.
+name, here we call it @q{lily-local} - you may wish to make up
+your own.
+
Then, finally, type
@example
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
+Return to Windows Explorer and look in your Git repository. You
+should see lots of folders. For example, the LilyPond documentation
can be found in Git/Documentation/user.
-Terminate the Git bash shell with the exit command.
+Terminate the Git bash shell by typing @code{exit}.
@subsection Git GUI
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
+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.
+be empty as you have not yet made any changes to any file.
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.
+in one of the panels on the left and the last version committed.
+
+The final panel at bottom right is used to enter a descriptive
+message about the change before committing it.
The Git GUI is terminated by entering CNTL-Q while it is the
active window or by clicking on the usual Windows close-window
Branch -> Checkout
@end example
-You should have one local branch called lily-local and one
-tracking branch called origin/master.
+You should have one local branch called @w{lily-local} and one
+tracking branch called @w{origin/master}. The latter is your
+local copy of the @w{remote/origin/master} branch in the master
+LilyPond repository. The @w{lily-local} branch is where you
+will make your local changes.
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.
+state of the files on that branch.
-@subsection Updating files from master
+@subsection Updating files from @w{remote/origin/master}
-Before starting the editing of a file ensure you have the
-latest copy from master by first clicking
+Before starting the editing of a file, ensure your local branches
+contain the latest version in @w{remote/origin/master} by first
+clicking
@example
Remote -> Fetch from -> origin
@end example
+@noindent
in the Git GUI.
-This will place details of all the changes made by others
+This will place the latest version of every file, including 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.
+out this branch. This will not affect any files you have
+modified in your local branch.
-To merge the changed files into your local branch click on
+You then need to merge these fetched files into your local
+branch by clicking on
@example
Merge -> Local Merge
@end example
+@noindent
and if necessary select the local branch into which the merge
is to be made.
+Note that a merge cannot be completed if there are any local
+uncommitted changes on the lily-local branch.
+
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
+current state of the @w{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.
+First ensure your lily-local branch is checked out, then
+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 UTF-8 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.
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
+your lily-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 wish to amend your changes after a commit has been
+made, the original version and the changes you made in that
+commit may be recovered by selecting
+
+@example
+Commit -> Amend Last Commit
+@end example
+
+@noindent
+or by checking the Amend Last Commit radio button at bottom left.
+This will return the changes to the Staged state, so further
+editing made be carried out within that commit. This must only be
+done @emph{before} the changes have been Pushed or sent to your
+mentor for Pushing - after that it is too late and corrections
+have to be made as a separate commit.
-If you do not have write access to master you will
+
+@subsection Sending changes to remote/origin/master
+
+If you do not have write access to @w{remote/origin/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
@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
+patch file for all the locally committed files which differ
+from @w{origin/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
+As soon as you have committed a changed file your local
+branch has diverged from @w{origin/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
+in @w{remote/origin/master} and Fetched back into your
+@w{origin/master}. Similarly, if a new commit has been made
+to @w{remote/origin/master} by someone else and Fetched, your
+lily-local branch is divergent. You can detect a divergent
+branch by clicking on
@example
Repository -> Visualise all branch history
@end example
This opens up a very useful new window called @q{gitk}.
+Use this to browse all the commits made by others.
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
+does not show your branch's tag on the same node as
+the @w{remote/origins/master} tag your branch has diverged from
+@w{origin/master}. This is quite normal if files you have modified
+yourself have not yet been Pushed to @w{remote/origin/master} and
+Fetched, or if files modified and committed by others have been
+Fetched since you last Merged @w{origin/master} into your lily-local
+branch.
+
+If a file being merged from @w{origin/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
+This could happen if the person updating @w{remote/origin/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.
+committing your changes to @w{remote/origin/master}, or if someone
+else has changed the same file since you last
+fetched the file from @w{remote/origin/master}.
Open the file in your editor and look for sections which
-are delimited with
+are delimited with ...
[to be completed when I next have a merge conflict to be
sure I give the right instructions -td]
+@subsection Other actions
+
+The instructions above describe the simplest way of using
+git on Windows. Other git facilities which may usefully
+supplement these include
+
+@itemize
+
+@item Using multiple local branches (Create, Rename, Delete)
+@item Resetting branches
+@item Cherry-picking commits
+@item Pushing commits to @w{remote/origin/master}
+@item Using gitk to review history
+
+@end itemize
+
+Once familiarity with using git on Windows has been gained the
+standard git manuals can be used to learn about these.
projects / lilypond.git / blobdiff