Subversion Primer
15nov10 revised 14sep11 revised 5sep14

\begin{document}
\maketitle

\section{Late Update}
So, 2010, I bit the bullet and actually installed the
Tortoise Subversion client on a PC. (Mac come with subversion onboard.)
Although it took some time, it was pretty much idiotproof for people
used to clicking-dragging-dropping. Here is some very useful advice:
\begin{itemize}
\item Create a directory (a.k.a. folder) where and with what name you wish.
This will contain your current image of the repository. SVN does not
"know" or "remember" anything about this part of the installation.
\item From "inside" this directory, checkout the repository whose
files you want to work with here. But please remember where you put this
folder, you will need to reach it quickly. I suggest into your home directory
on your pc/mac. Please do not bury this folder deep into your filetree.
\item It is advisalbe (but not necessary) to name this folder "class198f14",
which is the name on the repository. But it's good you don't need to,
because then you can set it aside, calling it "old-class198"
for instance, and check out a current one afresh in a new folder called
"class198f14" or "repo" or whatever. Just make sure you can find your way to
this place \txtbf{instantly}, without clicking around too much.
\item This feature is useful if you've messed up. But inside the repo you have
to be more careful. Use Tortoise to do the work for you. It will keep you
from making too many errors.
\item For instance, if you create a new file (including a new folder) you must
"add it" with SVN. If you don't, this file will exist on your copy of the
repo, but not on the mother ship. Remember this: Every action that changes
anything inside, creation, modification, renaming, moving, destruction, must
be registered with SVN in the appropriate manner.  On the other hand, DO NOT
svn-add files that are either generated each time (like .pyc, .log, etc) you
run a Python code, or compile LaTeX.

\end{itemize}

\subsection{GUIs for Macs}
While the (Math Dept sysadmins) know that
Tortoise is the best GUI client for SVN they
are not that confident about any GUI clients for the Mac. Here is a
webpage,
Suburbia   that discusses this issue.

The reason for this is simple. Subversion is mostly used by professionals,
most of whom over 30 still prefer the commandline method of communicating
with a computer. It is both faster, and there is a record of what you've
done. This computer maintained "journal" of your recent actions is useful for
\begin{itemize}
\item Copying this history into a help-file you edit and consult later.
\item In case of disaster, you can check back to where you made a mistake.
\item Finally, if you want help by email, you send them the journal of your
efforts instead of trying to write up a mousy travelogue. (Ask on the Forum if
you didn't catch what I meant.)
\end{itemize}
And the commandline SVN clients available for all three platforms are
very easy to learn, provided you can type. As information on the Mac
GUI clients accumulates, I will update this page.

The commandline  client on mac and pc is a golden opportunity for you to
learn and practice command line control of your computer. Even though, I
am over 30, I use both window/gui and shell/commandline, whichever works
faster for me at the moment.

\section{Introduction}
If only it were as easy as the curious pictures illustrating this document. Here is
my try at teaching you how to use our version control system called
\textit{Subversion} or SVN for short.
In MA198/CS199, SVN serves these purposes. [TBI] means "to be implemented"
someday.

\begin{itemize}
\item  All your work in the course is in one place.\\
\item   It is available to you and [TBI] others on any computer.\\
\item  You can work on any of the copies of your repo
and keep them in synchrony by updating and  re-committing your changes.\\
\item  All of the revisions going back to the beginning can be reconstructed.\\
\item  The mother ship server is thoroughly backed up by the Math Department.\\
\item  The instructors (me and [TBI]) can help you directly by editing and
commenting on your work. Like a copilot or driving instructor.
\item  You can [TBI] share files with your fellow students inside the repo.\\
\item  You can [TBI] read work from previous students in the course.\\
\item  Your website can be built gradually on the repo where only classmates
can see and comment on it. \\
\item  I can assess your progress at a glance to forestall major disasters.\\
\end{itemize}
But, there is a cost for such a versatile and efficient tool. You have to
learn how to use it. This introduction should be a lot longer, but the
rest of the backstory is below.

\section{Subversion Clients}
Subversion is an application which uses the \\textit{client-server model}. That
means that most of the work is done on a remote server of the application, and the
local client merely enables your computer to communicate with the server.

\subsection{Certificates of Authenticity}

Since the stuff you store on the Subverison repository is pretty private, everthing
about SVN is guarded by many "mother-may-I's". For instance, the
computer where the client resides has to have a so called \texttt{certificate}.
Depending how paranoid your computer system is, you'll have a more or less scary
session getting this certificate. Your operating system (should) stores the
certificate, at least until the server decides it no longer
trusts your computer.  Then you have to get another certificate.

\subsection{Which clients can (should?) you use?}
There are many svn clients you can down load from the web and install
on your personal computer. The macs in the Lab have one already
installed. I
will not attempt to be democratic here and discuss only two, one for
Windows and one for the Macintosh, both of which work the same way and
so require only one explanation. Moreover, both are
\texttt{ commandline clients}
which you address in a \texttt{ command shell}.
If you are unfamiliar with using a Unix sheel or the Windows
\texit{cmd shell} you should read another tutorial on this subject.
Alternatively, your GUI client should have labels on buttons you
can press which have the same names as described below. And, of course,
GUIs have help sessions. Tortoise SVN is pretty good here.

WAIT: we're looking for newer commandline clients.

For the mac, download, unzip and install:

MartinOtt-svn.zip  and for the PC, download, and click on
this self-extracting archive:

CollabNetSubversion-client-1.6.3-3.win32.exe.

\subsection{Shell Speak}
It's easier to explain orally how to talk to a command shell than to write about.
Perhaps that is the phenomanal success of GUIs (short for the misnomer
\textit{Graphical User Interfaces}) and their e-rodent inhabitants (mice).
Here the keyname comes inside parentheses. Thus (Ctl)(Alt)(Del) means you
press three familiar keys together. So, when these two letter words
appear at the beginning of the line, don't type them. It just means
to enter what follows to the end of the line.

In the Unix and Mac Bourne Shell, called \texttt{the bash}, the prompt is
the dollar sign, usually preceded by useful information. In the
Windows command shell, abbreviated ot \texttt{ cmd-shell} (in older
literature, also called \texttt{DOS-shell}) the prompt is the
greater-than symbol, which focuses your attention, like an arrow.
The Windows cmd-shell bears some resemblance to the Unix shells, but to
lend it some necessary functionality, it is wise to use some extension of
the cmd-shell language, as might be found in many such products, most of them
free. Our own \textit{Winaid} package and, the \texttt{win_shell.bat} of
\textit{Aszgard} include such features.

In any case, I will use "Enter:" to mean to type the following after the
appropriate prompt and press the (Enter) a.k.a. (Return) key.
The computer generally answers from the beginning of the next line.
I will also use the convention that angles brackets delimits a description
of text you supply yourself. For example \texttt{ print $\lt$name$\gt$}
means you type "print" followed by your name followed by pressing the
(Enter) key. (Never mind the stray closing bracket that shows up in documents
written in the Pudding.)

\section{Activation Your Subversion Repository}

You need to activate, \textbf{only once}, your SVN repository on each machine you use.

\subsection{On the macs in the REULab}
\textbf{This section is unreliable as of 2011. It may not work on the minis
anymore due to system rust and decay. Also, this section of the lesson has not
been carefully checked for updates and corrections. Tread lightly!}

\subsubsection{Working on an uprepared machine.}

If you are working on \texttt{riemann, gauss, boy, yau, markov, or cauchy},
the "RGBmachines",  ignore this paragraph and go directly to the next one.

Now test whether your mac is behaving today. Try Step (1) in the
next paragraph:

\begin{itemize}
\item (-1) Enter: \texttt{svn}
\item ... if you get no response, SVN isn't installed on this mac. \\
\item (0) Enter: \texttt{ svn checkout https://webapps.math.uiuc.edu/svn/groups/ma198 }  \\
\item ... if that fails, Enter: \texttt{ kdestroy } and try (0) again.
\item ... if that also fails then proceed here.
\end{itemize}

Otherwise, you will log into one of the RGBmachines remotely (your choice),
and then install an image of your repository there.

\begin{itemize}
\item (1) Open a shell window on your mac [click on the "Terminal" button]. \\
\item (2) Enter: \texttt{ ssh  $\lt$remote mac$\gt$ -l $\lt$your netid$\gt$    \\
\item Recall that the angle brackets here mean that you replace the whole
phrase with something described by it, for example .... \\
\item  ....  \texttt{ssh boy.math.uiuc.edu -l ivanhoe42 }
\item (3) In the remote shell, enter:  \texttt{ pwd }  or \texttt{ ls }  \\
\item  This just reassures you that your shell is "in" your remote home directory. \\
\item    Continue in the remote shell:  \\
\end{itemize}

\subsubsection{Working on a computer with a commandline SVN client.}

\begin{itemize}
\item (0) In the a command shell on the computer you are installing an SVN image, do this.\\
\item (1) Enter: \texttt{ svn checkout https://webapps.math.uiuc.edu/svn/groups/ma198 }  \\
\item (2) To authenticate yourself you may have to make three entries as requested.  \\
\begin{itemize}
\item The first is your password to your current machine, which is your ADpassword.  \\
\item The second name is your name on the repository, which is your netid. \\
\item The third is your  password to the official repository, which is your ADpassord again. \\
\end{itemize}
\item But on your home machine, the two passwords may not be the same, and SVN doesn't make that clear. So we do. \\
\item At this point an image of the entire ma198 repository is downloaded to your proximate computer. \\
\end{itemize}

\section{First and Last for each Subversion Session.}
\subsection{Starting each worksession, do this.}
\begin{itemize}
\item Enter: \texttt{ svn update } \\
\item ... which makes sure your image is synchronized with mother webapps. \\
\item Enter: \texttt{ls } to show you the subdirectories in the \textit{ foyer }.  \\
\item Recall that the top directory in a filetree is always called its \texttt{root}.
But we'll call the root of ma198, its foyer. \\
\item You can read and copy files from every directory in the foyer, but you can add files
only to your own directory. \\
\item Enter: \texttt{cd $\lt$ your directory $\gt$ } and work normally. \\
\item Be very careful NEVER to use any punctuation into names you create in svn, except the underscore and hypen.\\
\item Never have filenames that differ only in the case of a letter. (This accident derailed ma198 several times.)
\end{itemize}

\subsection{Ending each SVN session do not fail to do this !}
\begin{itemize}
\item (1) Enter:  \texttt{svn status}, to see new or changed files, or also the dreaded \textbf{conflicts}. \\
\item The most important prefixes are:
\begin{itemize}
\item \texttt{ ? foobar } = foobar is not (yet) in the repository \\
\item \texttt{ M abel } =  abel  has been modified in this session \\
\item \texttt{ C baker } = baker is conflicted, call an ambulance, quickly \\
\item \texttt{ ! charlie } = charlie deep doodoo, and if you don't fix it NOW, all of ma198 might stop working.\\
\end{itemize}
\item Files after a question mark may, but do not need to be added to the repository. If you never plan to
work with this file on a different computer, than leave it be. Else ... \\
\item (2) Enter: \texttt{ svn add $\lt$ file to be added $\gt$  } \\
\item Modified files, like abel is OK, unless you didn't mean to change the file.
\item Conflicted files, like baker and especially charlie have to be taken care of promptly.
\item See below how to treat files in various conditions before quitting the session. \\
\item (3) Before quitting your session, do \texttt{svn update} just in case, and
\item (4) Enter: \texttt{svn commit -m "fiddle faddle"} \\
\item ... where "fiddle faddle" is some phrase you may someday want to remember today's actions by. \\
\end{itemize}

\section{Adding Filetrees to your Repository}
Ordinarily you add only a few files at a time. But initially, you're very
likely to put an entire file tree, with a root directory "foobar" containing
many subdirectorie, into the repository all at once. You need to know the
pathname to foobar, of course. Suppose it is a subdirectory of your home directory
on your current computer. Then, open a shell in our home directory in the image
of your ma198 repository, and proceed thus:

\begin{itemize}
\item (1) Enter:  \texttt{cp -rp ~/foobar .  }   \\
\item This copies foobar to the repository.  \\
\item You can \texttt{svn status} to reassure yourself you've not added it yet.\\
\item (2) Enter: \texttt{svn add foobar} \\
\item ...which will add everything in foobar recursively.\\
\item You can \texttt{svn status} again for reassurance. \\
\end{itemize}

\subsection{Adding a set of files to SVN}
Next suppose that a directory, which is already in the repository, contains
a bunch of files you want to enter.

\begin{itemize}
\item (1) Enter: \texttt{ svn status > addlist} \\
\item ... which lists all the files with their symbols.
\item (2) edit the list, we named "addlist" here
(use VIM, or Wordpad if you must) to leave only the files you want to add.
Be sure you remove the question marks too. \\
\item (3 Enter: \texttt{for i in cat addlist ; do svn add \\$i ; done } \\
\item ... which is shell-speak for adding all the files named in the list.\\
\end{itemize}

\subsection{Adding an entire tree of files to SVN}

There is an svn command which makes the previous step easier, but harder
to remember how to do it. Suppose you you are Pi Mao and want to
at the file foobar and all of its subfiles to our repository in ma198. Then

Enter: \texttt{ svn import foobar
https://webapps.math.uiuc.edu/svn/groups/ma198/pi_mao -m 'first time' }

\section{The Backstory}

\textit{Revision control repositories} are quite old and very
diverse when you look at them  up close, but
broadly speaking, they all have the same purpose and work more or less
similarly. Here we shall refer to
a revision control repository as just a \textit{repo}.  Repos preserve all
changes to an initial file tree on a remote, secure, and frequently
backed up computer. Copies may be downloaded to a computer, modified, and
uploaded again. This way multiple copies of the repo can be kept in synchrony.

Although a repo can be very useful to a single user who must work on
multiple computers, they are designed to be used by multiple users working
on a common project. This latter fact makes their control syntax complicated.

Before we continue, a word about file trees.

\subsection{File tree structure}

Have you ever wondered just what happens when you click on those funny pictures
on your computer screen?  All contemporary \textit{computer file systems}
have the structure of a \textit{directed tree graph}. There is
a metaphor of an underground warren, not unlike in
\textit{Dungeons and Dragons},
with a single starting node, called the \textit{root},
descending into a branching
structure with no looping paths. The edges between nodes have a direction,
which the metaphor calls \textit{down}.
Each node has none or some \textit{daughters}. These
are the nodes directly \textit{below} the node.
Each node except the root has a
unique \textit{mother} directly above it. Nodes without daughters are called
\textit{leaves}.  All nodes, including the root are files. But some files are
called \textit{directories} or \textit{folders}.
The root node is a directory. Files which are not directories necessarily
are leaves in the tree, and are just called \textit{files}.

We think of the directories as \textit{containers} and
we also speak of files and directories being either in a directory (their
mothers) or in the a \textit{directory tree} named for the common
root or \textit{ ancestor.}
Thus every directory itself is the root of its own descendants, which
is a \textit{subtree} of the whole tree.

The directory keeps track of certain \textit{attributes} of its files, such as
owner, last accessed, permission, etc. Revision control adds an entire
subdirectory  each directory called \texttt{ .svn }
which contains the additional information
needed to serve the purposes of the repository. You can see that a particular
directory is under SVN-revision control (i.e. belongs to the repo) if you
enter: \texttt{ ls -latr }, and look for the telltale hidden file.

\subsection{Catching and cleaning an SVN fish}
One thing you must be careful when copying a file tree which is under
revision control somewhere else. For instance, if you want your own copy
of a directory, call it  \texttt{ ma198/ivanhoe/public/foobar/ }, located
outside of your own repo, call it \texttt{ ma198/xerxes/borrowed-stuff/foobar},
assuming you are Xerxes.
You can do this the following. Warning, you'll need to use paths properly.

Since I don't know where the repo \texttt{ ma198} is located on your
computer, whenever you see the word "~ma198" in the below I mean the
path to your image of the repo. For obvious reasons, I suggest you
keep repositories in a subdirectory of your home directory \texttt{ ~/ },
for instance \texttt{ ~/repo/ma198}. In which case the syntactally
invalid phrase \texttt{ ~ma198} refers to this directory.

\begin{itemize}
\item (1) \texttt{ cd ~ma198/xerxes/borrowed-stuff }  \\
\item .... being where you want to keep your copy of \texttt{foobar} \\
\item (2) \texttt{ cp -rp ~ma198/ivanhoe/public/foobar . }  \\
\item (optional) \texttt{ mv foobar myfoobar } \\
\item .... renames the borrowed directory to keep this recipe readable.\\
\item .... which copies ivanhoe's foobar verbatim to your place \\
\item BUT \texttt{ myfoobar} has all those, now incorrect .svn's in it! \\
\item (3) \texttt{ cd myfoobar } \\
\item (4) \texttt{ find . -name .svn -print | xargs /bin/rm -rf } \\
\item .... which removes all of the references in your copy of foobar \\
\item (5) \texttt{cd .. } \\
\item ... to get back into the parent directory of myfoobar. \\
\item Now inspect your copy of foobar and make sure it's clean and all there .\\
\item (6)  \texttt{ svn status } \\
\item .... to check that you have not created any conflicts, and that myfoobar has a ? in front of it.
\item Now you should work with your foobar. Edit out stuff you don't want,
and add your experiments with Ivanhoe's intellectual property.
\item Finally, from the parent directory of myfoobar/, namely your
borrowed-stuff/ do \\
\item (8) \texttt{ svn add foobar } \\
\end{itemize}

If you keep this much revision control
"sociology" in mind, then the laws and customs of this "weird nation"
become more comprehensible.

\subsection{Subversion or SVN}

The particular repo we use is called 'Subversion' or 'svn' for short.
At your convenience you should consult Wikipedia about Subversion, and
repos is general. It is quite a story! All we did here is to give you
some "first-aid" for using our own repo.

\subsection{Where the mother ship is located Fall 2011 }

\url{https://webapps.math.uiuc.edu/svn/groups/class198f11}

\section{Topics to be Added Later.}

\begin{itemize}
\item Resolving conflicts.
\item Effective use of a repository.
\item Stuff to watch out for.
\item Curing serious problems.
\item Just how \\textit{DOES} Subversion really work?
\end{itemize}

\end{document}