Subversion Instruction 2015 
Last edited 13sep15


\begin{document}
\maketitle


\section{Some History}
So, in 2010, I bit the bullet and actually installed the 
Tortoise Subversion client on a PC. (Macs come with Subversion (SVN) onboard,
and Linux has ways of easily installing it.) Although it took some time 
to get used to clicking mice, Tortoise was pretty much idiotproof for 
people used to clicking-dragging-dropping. The labmacs had to be used from
the command line for dealing with svn but otherwise things went smoothly.

Then CITES threw the proverbial monkey wrench into the customary machinery,
and this year it became more difficult again. The current procedure is 
known for Macs and presumably Linuxes, but have yet to be determined for
PCs. 

What follows are the provisional instructions for checking out and working
with SVN in the lab, on the labmacs. But I link some older, in part 
obsolete documents for the additional information contained in them.

\section{Checking Out  an Image on a Labmac}
The master copy of your files in a Subversion repository reside on an 
Math Dept server whose security is heavily guarded by elaborate, so 
called \textit{authentication} procedures. 

Here is the short form. Elaborations follow.

\begin{itemize}
\item On the labmac in front of you, open a command shell (cmdshell). 
\item Enter \texttt{kdestroy}. 
\item Enter \texttt{kinit ivanhoe@AD.UILLINOIS.EDU}. Except for "ivanhoe",
you use your netid. When prompted, use your AD password. 
\item Enter \texttt{svn checkout https://webapps.math.uiuc.edu/svn/groups/class198f14 }. Use your netid, and AD password if prompted to do so.
\end{itemize}

The cmdshell will be found by a sequence of button presses,  the first 
word of whose label are written in the recipe. Exception, the Finder is 
denoted by an idiotic expression on a square bottom left of the mac chrome.

Finder > Applications > Utilities > Terminal.app

Make it stick in the chrome by a right-click > Options > Keep in Dock.

Enter means type into window after the dollar sign and press the ender/return 
key. Henceforth I abbreviate a keyboard press by parentheses around the symbol
on the key (esc). Sequential keys would by (4)(2) for entering a 42. Simultaneous keys have a plus. For example (control)+(click) doubles for a right-click if
your mouse has not been properly configured.

\section{Working in the Image of your Repository}
Once you have checked out a copy (called an "image" in the jargon) you can 
work with it as you would with any folder in whatever way you are accustomed
do do so. But you must respect lower and upper case, and you must be careful
about removing, or renaming a file that has been added to the repository.

Here are the commandline entries, prefixed with a dollar sign, and their
effects, prefixed by two semicolons. You are learning Unix, the language
of computers, in particular of cmdshells.  

The phrase $\lt$ netid $\gt$ in a Unix command means that you enter your netid. 
$\lt$ filename $\gt$ would mean you enter a file name, etc. But because the
angle-brackets conflict with the HTML half of the Pudding I'm writing this
lesson in, I'll avoid this conention, using nonsense words, like "ivanho2"
and "foo", "bar", "foobar", etc. 

\$ cd class198f14 ;; cd stands for "change directory", class198f14 is 
the name of the folder that has an image of the repository in it. 

This is also the 
so-called root of the file-tree which is your current image of the 
repository. I prefer to refer to it unambiguously as the \textit{foyer}
of our repo. Everybody, students, mentors, and instructors in the class can 
read/write to it, except for some folders which are proprietary. For 
example, you cannot cd to admin/ (the slash is a shorthand way of writing
"the folder named admin"). And you should not even see the folders 
belonging to the other students, which are also proprietary.  

\$ ls ;; list what other files (and folders) there are in this folder.

\$ cd ivanho2 ;; but using your netid unless you are ivanho2   

\$ ls ;; and you'll find your dpgraph files in dpgraph/. 

\$ cd .. ;; is shorthand for changing to the previous directory (aka folder)

\$ ls ;; confirms what I just said.

\subsection{Commentary on Unix and file systems} 
A filesystem (fs) can be thought of as an (upside down) tree, with the 
root at the top. Think of descending into a subterranean space of branching
tunnels and levels. (The inventors of the paradigm played Dungeons and 
Dragons a lot.) The root of the entire file tree is denoted by just / in 
Unix. In DOS (the Microsoft version of Unix) uses \ because / already
meant something else. The full name of a file on your computer is very 
long. For example \$ pwd ;; /Users/gfrancis/repo/math198/subversion
for me just now. Translation, entering pwd (aka present working directory)   
told me that in root there is a folder Users, there is a folder gfrancis,
there is a folder named repo which .... etc. 

In the very first filesystems before Unix (and DOS) you had to always use
the socalled \textit{fully qualified path name} for your file. So there are
shortcuts. Indeed, Unix is full of shortcuts, and you can add further 
shortcuts to your personal copy of Unix ad libitum. When you open a 
cmdshell (on a mac, a linux, and yes, even a pc) you are "in your home".
In unix, wherever in that dungeon you happen to be at the time, you can
go home with a \$ cd ~ . The tilde is the name of your home. If another 
user is is logged in (or you have opened another shell with another 
username ... yes, you can do that!) then 
\$ ~/class198f14/ivanho2/public_html ;; gets you straight to the subfolder
which survive Aardvark Ivanhoe (aka ivanho2@illinois.edu) in the
web-annals of M198. If, that is,
you have permission to do so. An instructor does. You can only get to ~.


\section{Checking Out of an Image}

In contrast to checkout-ing an image, which is a corruption of the process
for which SVN uses the reserved word \texttt{checkout}, leaving your 
repository in a useful shape is more complicated. Remember, after having
worked for a while in your repo (in whichever image you did this) and 
before you leave it, you have three kinds of files (subfolders are also 
files in Unix.) 

\begin{enumerate}
\item  The files in your repo you haven't touched in this session. It 
does not list the files of type 1. above.
\item  Files you have changed (edited, modified). These are now 
different form the files by the same name in other images of your repo.
\item  Files that you have added, but not yet formally added to the
repo. They are marked with an M
\item  Files that you have added in this session, marked with an A.
\end{enumerate}

For example, suppose
you composed a whole subtree of files beginning with foo/,  which itself
contains bar1/, bar2, bar1/gaensefleisch, etc. We abbreviate this state
of affairs by just saying "suppose you created foo/, foo/bar1/, foo/bar2,
and foo/bar1/gaensefleisch (goosebumps, in English). Note that gaensefleisch
and bar2 are files that arent folders. Then they would all show up with 
a question mark when you enter 

\$ svn status ;; lists all files that have changed in this session

together with the symbol in front of them, indicating their status, duh. 

By the way, there are much more ominous symbols that can indicate 
conflicts and worse, and should never be told to small children, at 
least not until they do show up and spell trouble.

Then \$ svn add foo ;; will add each file in this new subtree to the 
repository. And yes, you can also remove files from the repository. 
But that's for an later lesson.

When, after some effort, \$ svn status ;; shows only an M or A for 
those files you want repositoried, and leaves a ? for those that are
your private files locally, and only then, you may 

\$ svn commit -m 'tell me a useful story' ;;

which synchronizes your current image with its mother in webapps, so
that when you go to another, older image on a different computer, you 
can 

\$ svn update ;; which now synchonizes this image with mother. You have
to put that -m which indicates what follows in quotes is a label you 
attach to this action on the repository. You may (but perhaps should not,
write just \$ svn commit -m '' . That leaves the action unlabelled.

\section{More?}
This ends the first lesson on subversion in 2015. There are  
older, partly obsolete in some detail, but nevertheless instructive
instructions.

\end{document}