Lesson on Subversion a.k.a. svn

For good and sound reasons I have decided to build this file as a stack, with the last in on top, rather than at the end. So, if you don’t understand something at some level, dig down rather than "look up".

This webpage is composed in a light-weight html "factory" named AsciiDoc. There will be a separate Advice lesson on AsciiDoc. This note is needed here because I still learning AsciiDoc and you may find some really odd notational errors, the least of which are mere inconsistencies of typographical style.

For instance, to get AsciiDoc to print this correctly

it had to be entered, between a pair of matched dashed lines, thus

otherwise it would have come out looking like this, without the dashes and without the excapes

for i in cat list; do svn add $i ; done

Unfortunately, I never did figure out how to get it to be another bullet. If I had used the bullet typography it would have come like this

This is a nice solution, but it took me 2 hours to discover it in the AsciiDoc documentation.

If you are working on boy, cauchy, markov, or gauss ignore the next step.

Otherwise:

On any pooter on which svn is available do the following once.

On any machine on which the repo ma198 has already been installed follow this hygiene. Do not begin a session without doing an update first.

To add any new files to your repository you need to

Since this become tedious with many files, you can do this. Or figure out something more "modern" in the manner you were trained in high school.

will save you a lot of typing.

When you are finished with the session, save it to the repository, not by "uploading it" (hey, I didn’t write subversion!), but thus

Note the regular single quotes (ticks), not back-ticks or quotes. The message is merely a way of identifying the last commitment.

On your own machine you’ll need an svn client to manage your repo from anywhere you’re on the net.

Otherwise, you can download Martin Ott’s commandline subversion package from

http://www.math.uiuc.edu/~gfrancis/illimath/mac/MartinOtt…;.

Either find yourself a gui svn client on the web, or on Jonathan Manton’s pages, or download a commandline subversion package

http://www.math.uiuc.edu/~gfrancis/illimath/windows/CollabNet …

which is a self-extracting win32 archiven that works like a charm (from the command line only).

-

Revision control repositories are quite old and very diverse up close, but broadly speaking, they all have the same purpose. Here we shall refer to a revision control repository as just a 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.

Recall that contemporary computer file systems have the structure of a directed tree graph. There is a metaphor of an underground warren, not unlike in Dungeons and Dragons, with a single starting node, called the root, descending into a branching structure with no looping paths. The edges between nodes have a direction, which the metaphor calls down. Each node has none or some daughters. These are the nodes directly below the node. Each node except the root has a unique mother directly above it. Nodes without daughters are called leaves. All nodes, including the root are files. But some files are called directories or folders. The root note is a directory. Files which are not directories necessarily are leaves in the tree, and are just called files.

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

The directory keeps track of certain attributes of its files, such as owner, last accessed, permission, etc. Revision control adds an entire subdirectory of each directory, which contains the additional information needed to serve the purpose. If you keep this much revision control "sociology" in mind, the laws and customs of this "nation" become more comprehensible.

The particular repo system 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! But here is some "first-aid" station for using our own repo.

Our repo consists of two physical object: - An svn client on your computer (see below) and - the svn server that manages the repo

The url of the repo is here

https://webapps.math.uiuc.edu/svn/groups/ma198

and copies of the repo are on one or more of your computers. Your copy is also named ma198.

All files in ma198, the root, can be read by all members of the class, except the subdirectories with your netid on them. These files only you can read and write into. This is where you keep your daily work for the course. I can read and write to all files, so don’t use your repository for private information. On the other hand, only items in your repo "count" as work done for the course.

The purpose of this arrangement is that I can help you learn things by looking over your shoulder, not unlike driver’s training. So, say you email me with a problem you can’t solve. I open our repo and know what you’re talking about. I will most like edit your repo, for example by leaving an answer to your question in your repo.

If you question has an answer that other students need to see, I will put the answer into the common space for all.

As the semester progresses, you will build your web page in the repo (I’ll have more to say about that later), even though it will be archived elsewhere. Your project will develop in your repo, where I can follow its progress. I hope to be kept busy working with you in your repo.

There are many svn clients you can down load from the web and install on your personal computer. The macs in the REU 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. Morover, both are command-line clients which you address in a shell. If you are unfamiliar with using a Unix or Windows command shell you should read another tutorial on this subject.

It is easier to explain and to use a shell than to direct elaborate menu and mouse maneuvers. Since "shellspeak" uses special symbols, and these sometimes conflict with textprocessors, I will use

A 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 "bash", the prompt is the ds, in the Windows command shell, a.k.a. "cmd", the prompt is the gt. In either case, when I start a line with a prompt symbol you should not type it again into the commandline. At the end of the line you should press the return key (rt), but I generally forget to remind you of that. The computer generally answers from the beginning of the next line. If its answer is pertinent I’ll write it on the next line. The discourse resumes after a blank line. In emails and text files just use the symbols. Here I will use sh for either ds or gt. When you see ds or gt you know I’m only talking about the one or the other shell, not both.

In emails or textfiles it is safe and better to just use the symbols.

I will also use the convention that angles brackets delimits a description of text you supply yourself. For example "print <name>", means you type "print" followed by your name followed by pressing the (Enter) key. We’ll shorten this to "means you enter print followed by your name."

On each computer you use this command only once, to create a local copy of the repo. Your shell opens in your home directory. You might want the repo on your desktop. In that case do "cd desktop (rt)" . On the command line, enter

sh svn checkout https://webapps.math.uiuc.edu/svn/groups/ma198

and when prompted, enter your Active Directory password (AD-passwd). After the initial download of the file tree, go look around in ma198. Note the difference in names, "math198" refers to our portal webpage, and "ma198" our common Subversion repo.

Whenever you begin working in ma198 you first enter

sh svn update

to synchronize the local file tree with the official repo. If you have worked on your repo elsewhere, and the revisions flash before your eyes.

Then you might edit existing files. Do so whichever way you’re familiar with. But if you create or move files new files into the repo, you also need to register them. You don’t have to do that until the end of your session, because deleting files is a pain in svn. So, lets next suppose you have finished an editing session and you prepare to leave. Check the status of your files with a

sh svn status

will list all the files in the present working directory (pwd) and prepend them with any one of a many different symbols. A letter, like M for "modified" is OK, a "? foobar" means the file has not been registered in svn and if you want it to be, then do

sh add foobar

But a letter like C for "conflicted" is bad news and requires surgery.

Assuming that your files are the way you want them preserved in the repo, you next

sh `commit -m twitter tweet twit `

where "twitter twee twit" is some descriptive phrase you want to attach to the upcoming committment that might help in the future to remind you what the changes were. Keep it short. Check things with one last with an

sh update

and proceed on your merry way.

The following topics need to be treated before you’re safe to use the repo.