@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
To run the program from the command line, navigate to the
files. You should now be able to modify the source files using
your normal text editor.
+@knownissues
+
+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.
+
@subsubheading New local 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.
-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.
+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 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
@subsection Setting up
-FIXME: Remove this note if incorporating Windows instructions
+TODO: Remove this note if incorporating Windows instructions
throughout this section:
@warning{These instructions assume that you are using the
(@uref{http://git-scm.com/}) for downloadable binaries and
tarballs.
-FIXME: add Windows installation instructions (or @@ref@{Git on
+TODO: add Windows installation instructions (or @@ref@{Git on
Windows@}).
git config --global core.editor @var{nano}
@end example
-FIXME: Add instructions for changing the editor on Windows, which
+TODO: Add instructions for changing the editor on Windows, which
is a little different, I think. -mp
@subsubheading Technical details
patch, and this may create a conflict. If this happens, see
@ref{Resolving conflicts}.
-FIXME: I think the next paragraph is confusing. Perhaps prepare
+TODO: I think the next paragraph is confusing. Perhaps prepare
the reader for new terms `committish' and `head'? -mp
@warning{translators and documentation editors, if you have
documentation except committishes updates (possibly after having
rebased), then update the committishes and push them.}
-FIXME: when committishes automatic conditional update have been
+TODO: when committishes automatic conditional update have been
tested and documented, append the following to the warning above:
Note that using update-committishes make target generally touches
committishes.
@subsection Applying remote patches
-FIXME: Explain how to determine if a patch was created with
+TODO: Explain how to determine if a patch was created with
@code{git@tie{}format-patch}.
Well-formed git patches created with @code{git@tie{}format-patch}
@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
@c But it is probably best for windows users to have it all together
@c If necessary, clear this up later -td
-FIXME: Decide what to do with this... Pare it down? Move
+TODO: Decide what to do with this... Pare it down? Move
paragraphs next to analogous Unix instructions? -mp
@subsection Background to nomenclature