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}