@node Working with source code
@chapter Working with source code
+New contributors should only read @ref{Using lily-git}. Please
+ignore the rest of this chapter.
+
+Advanced contributors will find the rest of this material quite
+useful, particularly if they are working on major new features.
@menu
* Using lily-git::
@node Using lily-git
@section Using lily-git
+@subsubheading Install and Configuration
+
+@enumerate
+@item
+If you haven't already, download and install Git.
+
+@itemize
+
+@item Windows users: download the @code{.exe} file labeled
+@qq{Full installer for official Git} from:
+
+@example
+@uref{http://code.google.com/p/msysgit/downloads/list}
+@end example
+
+@item Other operating systems: either install @command{git} with
+your package manager, or download it from the @qq{Binaries}
+section of:
+
+@example
+@uref{http://git-scm.com/download}
+@end example
+
+@end itemize
-If you haven't already, download and install Git. Go to
-@uref{http://git-scm.com/download}, and in the @qq{Binaries}
-section, select the appropriate package for your operating system.
-Windows users should visit
-@uref{http://code.google.com/p/msysgit/downloads/list} and
-download the @file{.exe} file labeled @qq{Full installer for
-official Git}.
+@item
Download the lily-git script from:
@c don't change the cgit link below to gitweb; gitweb uses
@c long filenames like "scripts_auxiliar_lily-git.tcl"
@example
-@uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}.
+@uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
@end example
+@item
To run the program from the command line, navigate to the
directory containing @file{lily-git.tcl} and enter:
wish lily-git.tcl
@end example
+@end enumerate
+
-@subsubheading Get source / Update source
+@subsubheading 1. Get source / Update source
When you click the @qq{Get source} button, @command{lily-git} will
create a directory called @file{lilypond-git/} within your home
-directory, and will download the complete source code into that
+directory, and will download the source code into that
directory (around 55Mb). When the process is finished, the
@qq{Command output} window will display @qq{Done}, and the button
label will change to say @qq{Update source}.
files. You should now be able to modify the source files using
your normal text editor.
+@quotation
+Advanced note: The @qq{Get source} button does not fetch the
+entire history of the git repository, so utilities like
+@command{gitk} will only be able to display the most recent
+additions. As you continue to work with @command{lily-git}, the
+@qq{Update source} button will take any new additions and add it
+to whatever is currently in your repository's history.
+@end quotation
-@subsubheading New local commit
+
+@subsubheading 2a. New local commit
A single commit typically represents one logical set of related
changes (such as a bug-fix), and may incorporate changes to
commit.
-@subsubheading Amend previous commit
+@subsubheading 2b. Amend previous commit
You can go back and make changes to the most recent commit with
the @qq{Amend previous commit} button. This is useful if a
-mistake is found after you've clicked the @qq{New local commit}
-button. To amend the most recent commit, edit the source files as
-needed and click the button. The earlier version of the commit is
-not saved, but is replaced by the new one.
+mistake is found after you have clicked the @qq{New local commit}
+button.
+
+To amend the most recent commit, re-edit the source files as
+needed and then click the @qq{Amend previous commit} button. The
+earlier version of the commit is not saved, but is replaced by the
+new one.
-Note that this does not update patch files; if you have a patch
-file from an earlier version of the commit, you will need to make
-another patch set when using this feature. The old patch file is
-not saved, but is replaced by the new one.
+Note that this does not update the patch @strong{files}; if you
+have a patch file from an earlier version of the commit, you will
+need to make another patch set when using this feature. The old
+patch file will not be saved, but will be replaced by the new one
+after you click on @qq{Make patch set}.
-@subsubheading Make patch set
+@subsubheading 3. Make patch set
Before making a patch set from any commits, you should click the
@qq{Update source} button to make sure the commits are based on
@end example
@end itemize
+@knownissues
+Encryption protocols, including ssh, generally do not permit packet
+fragmentation to avoid introducing a point of insecurity. This
+means that the maximum packet size must not exceed the smallest
+MTU (Maximum Transmission Unit) set in the routers along the path.
+This smallest MTU is determined by a procedure during call set-up
+which relies on the transmission over the path of ICMP packets.
+If any of the routers in the path block ICMP packets this mechanism
+fails, resulting in the possibility of packets being transmitted
+which exceed the MTU of one of the routers. If this happens the
+packet is discarded, causing the ssh session to hang, timeout or
+terminate with the error message
+
+@example
+ssh: connect to host <host ip addr> port 22: Bad file number
+fatal: The remote end hung up unexpectedly
+@end example
+
+depending on precisely when in the proceedings the first large
+packet is transmitted. Most routers on the internet have MTU
+set to 1500, but routers installed in homes to connect via
+broadband may use a slightly smaller MTU for efficient transmission
+over ATM. If this problem is encountered a possible work-around is
+to set the MTU in the local router to 1500.
+
@node Git on Windows
@section Git on Windows
projects / lilypond.git / blobdiff