When my younger brother was… younger, he once stuck a pussy willow bud up his nose. I mean, he didn’t just sorta stick the thing in his nose… he crammed it up deep somewhere in his nasal cavity. I’m surprised he didn’t loose the finger to the finger-biting monster that Shel Silverstein claims lives up there.

Inside everybody’s nose
There lives a sharp-toothed snail.
So if you stick your finger in,
He may bite off your nail.
Stick it farther up inside,
And he may bite your ring off.
Stick it all the way, and he
May bite the whole darn thing off.
(Shel Silverstein, Where the Sidewalk Ends)

Alas, no such biting happened. I do remember him screaming like the end was coming, however, when four adults held him down (one to each arm, one to his legs, and one to his head) while someone gingerly reached up and extracted the pussy willow with a pair of tweezers.

I figure he was around three years old. I would have been seven.

Good times, good times…

Of Pussy willows and Subversion

You see, this comes to mind because my students are using Subversion repositories for all of their coursework. They check things in, I check them out, and comment on their work. I then do a checkin, and they can read my comments right in their code. There’s no complex web-based system, no complex emailing of documents back-and-forth. It works reasonably well, I think.

Now, what should go in a repository? This is a reasonably tricky question.

1. Code. When you’re working on programs, the source code goes in the repository.
2. Documentation. Documentation (preferably written in plain text or LaTeX) should be in the repository. If you’re keen on using closed, proprietary tools, then Word Documents might end up in the repository.
3. Required blobs. A “blob” is a binary document. JPEG images are binary. PDFs are binary in nature. It is a “required” blob if something else needs it to be generated (like a LaTeX document that has an image in it; the PNG or JPEG should be included in the repos).

That’s about it. That still isn’t very specific, so I’ll itemize one or two things that might not go in the repository, and why.

1. PDFs. Generally, PDFs do not belong in the repository. That is, if you found an article that both you and your colleague are collaborating on, the repository is not where the PDF belongs. Why? Because the PDF is never going to change. You should just use a networked drive for this kind of “static” or “unchanging” data.
2. Executables. Programs that you need as part of the process of building or manipulating your software should not, generally speaking, be part of the repository. If you have an EXE that, say, processes one of your files… it should also be in a shared drive. While it might be necessary, it (like the PDFs) will never change. Therefore, you should put it on a shared drive, and let people copy it from there.
3. (By-)Products of a build process. Many programming environments generate many temporary files while building a piece of software. These temporary files that are generated in-between your source and executing on hardware should not be part of the repository. Only the source documents (the C files, and any project configuration files that are part of the IDE) should be in the repos. Temporary log files generated by the compiler should not be in the repos.

In short, only the files that you edit go in the repository. Any files that a program generates should not be in the repository.

Why?

Because your repository grows every time a file changes. If you store big, binary files (like executables produced by a compiler) in your repository, then every time you compile your program, the repos thinks a critical file has changed. In truth, we only want the source code to be tracked… not the output from the compiler. We especially don’t want the log files from the compiler checked in. We simply don’t care how those change from one commit to another, and our colleagues generally don’t care, either.

Now, like all things, there are times when these rules might be violated. For example, I asked my students to put a PDF of their report in the repository. This is because I didn’t want to deal with Microsoft Word documents. I’ll mark things directly into a copy of the PDFs. That is preferable, given the workflow that we’re dealing with, and the fact that some students are using Word, and some are using LaTeX. (I should just require TeX.) So, that “rule” about “no PDFs” was violated for a very specific reason. Likewise, I put PDFs in the class repository so they can easily read and print the documentation on whatever machine they are sitting at… not because it is the “right” thing to do.

So, what goes in your repository? Probably not pussy willow buds.