Subversion, with the command line tool svn, is a revision control system, also known as a source code management system (scm) or a source code control system (sccs).
The subversion server maintains a repository, where files are stored in a hierarchy of folders, same as a traditional file system. Files can be checked out and modified. The changes can be copied back into the reposition, called committing the change, creating a new version of the file.
The versioning maintains the history of each file, as well as the history of the entire repository including the arrangement of folders, so that you can recover any version or revisit changes by looking at differences between versions.
There are three reasons we want to use a source code management system:
The basic work cycle of subversion is pull-modify-commit,
There are two sorts of pulls: checkout and update.
A repository has a revision number. Beginning with an empty repository with revision number 0, each commit increases the revision number by one. The revision number of a file or directory is the state of that file or directory in a given revision number.
A common notion of the "revision" of a file would be the successive changes in the file. This is incorrect for how subversion does things. In subversion, most "revisions" of a file or directory are the same, as they are carried forward unchanged to the next repository revision.
Commits are all or nothing. If even one file is out of date, the entire commit is cancelled. Updates bring the base up to date, but might trigger conflicts, where the committed revision in the repository cannot be reconciled with the working copy.
A simple strategy for conflicts is,
Tree changes
A tree change is a change to existence or names of files or folders. These are complicated as you would also like subversion to track these changes as well. For directories, their base is never changed by a commit, even if the directory has been modified. Updates before and after attempting a tree change are essential for the success of a tree change.
The subversion repository is an Internet service which is accessed by client software. It can be accessed in a variety of ways. Some IDE's integrate the an svn client.
Quick hint, for Ubuntu:
sudo apt-get udpate sudo apt-get install subversion
The Mac operating system has four components:
The easiest way to get software similar to the Linux distros is through the brew package management system. Install brew and then install subversion.
Install brew using the command on the first page of the brew website. On my Apple Silicon, the installation did not install the command path to my PATH environment variable so after installation I had to do this myself.
To see your path, type,
> echo $PATHOn Apple Silicon, the brew command's full path is /opt/homebrew/bin/brew. If you want to be able to simply type brew at the terminal, then echo should include the path /opt/homebrew/bin. If not, fix it. Your Milage May Vary.
Then,
> brew install subversion
A simple method to avoid retyping your password when required by svn, is to store your password in a file, at the root of your subversion repository and insert it into the command line using the unix back-tic (`) mechanism.
svn --password `cat passwd.secret` commit -m okThe shell first scans the command for back-tics, runs the program in the back tick, and inserts the output of that run in place. In this case, passwd.secret is a file that contains your password.
A second method is to force subversion to use its old password system. In the old system, subversion would store your password in a file the first time you typed it, and would read that file whenever the password was required. Subversion still look at said file for a password, but refuses to put the password in the file for you. So here is how you put the password in said file.
The file is,
~/.subversion/auth/svn.simple/verylongstringoflettersThere maybe more more than on file in that directory with these long names. You will figure out which you want to edit by looking at the value of the username key. This file contains key-value pairs that configure the connection. Edit it to contain - your milage may vary (ymmv)) -,
K 8 passtype V 6 simple K 15 svn:realmstring V 40 <svn://svn.cs.miami.edu:3690> department K 8 username V 10 __username__ K 8 password V 27 dog-eats-man-and-burps-A101 ENDThe number after V and K is the character count of the following line. In case you are totally lazy and want computers to do everything for you, first: welcome to world of programmers; and second: find the number of letters in the password using -
$ echo -n dog-eats-man-and-burps-A101 | wc
0 1 27
While there might be a subversion implementation native on Windows, I tend not to pay much attention to Windows. Instead, I get recommend getting a unix development environment on Windows, and doing development inside the environment.
Windows now has WSL, Windows Subsystem for Linux. Install that, then install a unix inside WSL. If Ubuntu is installed, then install subversion according to the linux/ubuntu procedure.
This article gives an example of installing WSL, the ubuntu operating system, and then the Jupyter notebook. It can be a useful guide.
Before WSL was available, developers used cygwin. That is still an option. It does not install unix, it installs DLL's that allow unix programs to run on windows. It is a port of unix to the Cygwin DLL environment, as far as I know.
It is a less complete solution than WSL, but it is light weight.
svn co --username pikachu --password svengali svn://svn.cs.miami.edu/classes/csc421.201 csc421.svn
Update
After the initial check out, pick up changes from the repository using update. If you modify something, update might ask for a conflict resolution or a merge. Use revert first to discard changes in your working copy, before the update. The parameters of check out are stored in the working copy, so the update command is simpler.cd csc421.svn svn update
Add
Subversion only tracks what you ask it to track. Start tracking with the subversion add command, applied to files or directories. For instance, when pikachu creates the proj0 directory in his folder, this does the trick,
cd csc421.svn/pikachu
mkdir proj0
svn add proj0
Status
The svn status command should be run to inform you the status of your files, and what will happen on the next update or commit.
The verbose option, svn status -v, will provide you a very concise vision of what is being tracked, what tracked files are modified and will be pushed on commit, and so forth. You will see the revision numbers as known without contacting the repository server.
The update option, svn status -u, goes further than the -v option by contacting the server to determine the commit revision of files.
The status subcommand queries files at and descending from the current directory. Run at the root of your working copy, you will see everything. Descend to say your project directory, you will only see what is important for the project.
cd csc421.svn/pikachu/proj0
svn status -v
Commit
The commit command does the work. It is best to change directory to focus the commit to just the files you intend to commit. If it succeeds, commit will give you the revision number of the commit. Treat this as a receipt for your commit. If you did not get a receipt, commit has cancelled the commit for some reason.
The -m option is required, and is a notation that is stored with the commit.
cd csc421.svn/pikachu/proj0
svn commit -m "final commit for grading"
Tree changes: mv and rm
You must not mv or rm files that are being tracked by subversion. You must use svn mv and svn rm.
The svn mv and snv rm commands will schedule a move or remove for files and directories. The status command will show that the move or remove have been noted, and the files will be moved or removed in the working copy.
If all goes well, on commit, the move and remove will be entered into the repository revision.
It is best to do an update first, and get all in order. And have an up to date base, before doing a move or remove.
Revert
The revert subcommand will restore the working copy back to the base revision. Or, if will cancel and add, as long as it has not been committed. It also cancels moves and deletes, as long as they have not been committed.
The command requires that you specifically name the file. If you have rm'ed a file, can can get the file back with an update, where the copy will come from the repository, or by a revert, where the copy will come from the base revision, that is stored locally on the client.
Resolve
Resolve conflicts by running svn update to pull the repository version into the working copy, integrating the changes in the repository file into the working copy. Svn update will integrate some changes automatically by merging the files. These are mergeable conflicts. If all conflicts are mergeable, the merged working copy is considered a modification of the current repository version, and can be committed.
If unmergeable conflicts remain after the update, the conflicts must be resolved by hand, and then svn resolve is run to mark the conflict as resolved, and clean up certain temporary files created by subversion.
Subversion will offer to resolve the unmergable conflicts interactively during svn update, to which you can postpone the resolution. If you postpone the resolution, subversion will mark the file as conflicted, and will leave three additional files in the directory, as well as possibly modifying your working version according to its "advice" on the unmergeable conflicts. You can then edit or copy or move these files. Once finished, the svn resolve command to clean up the temporary files and to remove the conflict marker. Then run svn commit again.
Svn resolve has the option --accept which takes several values. If you have edited your working version, and consider it definitive, use:
svn resolve --accept working
then commit. The other safe possibility is to revert your working file to the unmodified, then update to get the newer version, and then reapply your changes, and then commit.
The first source control system was SCCS, written in 1972 by Marc J. Rochkind at Bell Labs. It was ported to unix and is still part of Unix today. Its successor, RCS, was written for unix in 1982 by Walter Tichy. That was supplanted by CVS, written in 1986 by Dick Grune. CVS is used by many important open source projects such as FreeBSD. (The FreeBSD source repository switched from CVS to Subversion on May 31st, 2008.)
Subversion is a product of CollabNet, which was founded by Tim O'Reilly and Brian Behlendorf in 1999. CollabNet started the Subversion project in 2000, and version 1.0 was released February 23, 2004. Since 2010 subversion has also been known as Apache Subversion.
You maybe be wondering about the illustration that opens this page. You might ask: Why Barbar The Elephant? That's simple: Because an elephant never forgets. What other explanation for that choice could there be?
You can stop reading now, there is really nothing interesting following.
————
No, it's not because elephants don't forget. Please, don't you see?
Subversion is really the instrument of a vast digital illuminati only posing as a software control system. Once you understand this, it all becomes clear: subversion's useless error messages, its seemingly careless shortcomings, its completely aberrant command syntax — all a deliberate mask of mystery over oddly shaped concepts that you recognize as keys once you see the locks.
Why else would it be named Subversion?
Look the word up in the dictionary, if you don't believe me.
————
Update history:
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.