See also: History of WeBWorK version control
WeBWorK uses the Subversion version control system. To use it, you have to download the official command line Subversion client. Most Linux distributions will have this available in their package repositories, and many install it by default. For example,
- to install Subversion in Ubuntu do
sudo apt-get install subversion
- to install Subversion in Fedora become root and do
yum install subversion
Subversion's command-line interface is similar to CVS. This is a basic and partial guide of the most useful commands. For a complete guide, use the book Version Control with Subversion. If you have a write access to the server, it's strongly recommended that you read it and know about the advanced features of Subversion, because you might use them sooner or later.
There are two main WeBWorK repositories, all hosted at http://wwrk.maa.org/svn/. The two repositories are
These two repositories contain all of the necessary WeBWorK software and the National Problem Library. There may be a few other problem library repositories (such as rochester), but those will soon be folded into the NPL.
Each repository uses a more or less standard hierarchy:
Pre-production work is made in the trunk tree. Since many WeBWorK servers run the code in this tree for production usage, patches made in this tree must not break the code. You should also avoid rewriting extensive portions of the trunk as well. WeBWorK itself is in the webwork2 subdirectory of the trunk, and the PG code is in the pg subdirectory of the trunk. The trunk of the system repository has many other subdirectories, but these contain special sub-projects used for development and testing.
branches is used for major coding work, testing huge patches, and testing unstable patches. Some developers may have their own branch of the code here. It is also used to prepare new stable releases (through the well-known beta → release candidate → security & maintenance fix cycle). Each major stable series gets its own directory as rel-<major_version>-<minor_version> or rel-<major_version>-<minor_version>-patches. For example, the current stable release of the WeBWorK code is rel-2-4-patches.
tags is a special hierarchy used to save the state of the software at a given point in the time. You should NEVER make any change to it as this is only useful when releasing new versions. That task is handled solely by the WeBWorK release managers.
The WeBWorK repositories are configured so that anonymous users may perform any read operation (such as checkout, update, etc.) Developers who have commit access should see the section below on Developer use for basic information on how to commit changes to the WeBWorK repositories.
First, you have to check out the WeBWorK code. To do so use the following syntax:
svn checkout http://wwrk.maa.org/svn/folders_to_download some_target_directory
- The trunk is the main development branch.
- The branches are used for stable versions of the core WeBWorK and PG code; and for the development of complex features.
- The tags are used to track the released versions.
The URL structure is:
- /svn/system or /svn/npl/ (or /svn/rochester/)
- /trunk, or /branches/rel-2-4-patches, or /tags/rel-2-4-7
- /webwork2 or /pg
Unlike the old CVS, the URL is used to specify the branch or the tag.
To check out the WeBWorK 2 development trunk into the folder "webwork":
svn co http://svn.webwork.maa.org/system/trunk/webwork2 webwork
To check out the PG development trunk into the folder "webwork":
svn co http://svn.webwork.maa.org/system/trunk/pg webwork
To check out the National Problem Library development trunk into the folder "webwork/libraries":
svn co http://svn.webwork.maa.org/npl/trunk/NationalProblemLibrary webwork/libraries
To check out the latest bits in some particular release branch:
svn co http://svn.webwork.maa.org/system/trunk/webwork2 some_target_directory svn co http://svn.webwork.maa.org/system/trunk/pg some_target_directory
To check out a specific version of the software:
svn checkout http://wwrk.maa.org/svn/tags/rel-2-4-7/webwork2 some_target_directory svn checkout http://wwrk.maa.org/svn/tags/rel-2-4-7/pg some_target_directory
Each time a commit is made to a repository, Subversion increments the revision number of the repository. To check out a specific revision of the webwork2 code, say revision 6000, do
svn checkout http://wwrk.maa.org/svn/system/trunk/webwork2@6000 some_target_directory or svn checkout -r 6000 http://wwrk.maa.org/svn/system/trunk/webwork2@6000 some_target_directory
or, if you want to switch to that revision, use the update command:
svn update -r <number>
Don't leave off the "trunk" or branch part! If you leave that off you check out every revision of every file in the repo, which is pretty silly and takes a long time.
Updating the working copy
To update your working copy and get the latest files, use the following command:
svn update (or just: "svn up")
Note that SVN, unlike CVS, doesn't need to be told to prune removed files or create new directories. This is automagic.
For a simple way to keep abreast of changes, one could use e.g.,
cp RELEASE-NOTES /tmp && svn up && diff /tmp RELEASE-NOTES
- What happens if I change some file, then do "svn up" and it was changed upstream too?
- Don't worry. You will see
Conflict discovered in 'lib/WeBWorK/WeBWorK.pm'. Select: (p) postpone, (df) diff-full, (e) edit, (h) help for more options:
Making a diff
Diffs, or patches, are text files which include all the changes done in the working copy. If you suggest a new feature in Bugzilla and would like to suggest a change which fixes it, upload a patch.
To create a diff from the current repository, use the following command:
Normally, unlike CVS, you don't have to tell SVN which files you changed; however, you may like to diff only a part of the repository. To do that, specify the files to diff:
svn diff webwork2/lib/WeBWorK/MyAwesomeWorK.pm
Note that SVN defaults to the "unified" diff format, so the "-u" option doesn't have to be passed.
Applying a diff
Subversion does not contain a built in command to apply diffs to the current working copy (for example, to review or commit diffs published in Bugzilla); instead, you can use the regular patch unix utility:
patch -p0 < patch_file
Changing file structure
You can add files or folders to the working copy, to be included in the next diff or commit, using the command:
svn add file.name
If you add a folder, it will add all the files included in the folder, except for files in the ignored list.
You can delete files or folders from the working copy, to be deleted in the next commit or marked as such in the next diff, using the command (which will automatically delete the files from the working copy, but won't delete folders in such way):
svn delete file.name
Make sure the file or folder do not have local modifications, else they won't be deleted unless you force the deletion.
Reverting your changes
If your changes in the working copy are not useful in your opinion, you can revert them using the following command:
You must use parameters for this command. To revert all your changes in the working copy, use:
svn revert -R .
To revert the changes in a specific file, use:
svn revert file.name
Reverting can also remove added files (they won't be deleted, just removed and considered "unknown files", just like you didn't use
svn add at first), and restore deleted files (both deleted by hand and deleted by
Checking the status of the working copy
You can check the status of your working copy using the following command:
These are several important letters in the first column of the item, which show the status:
- M = the item was modified by you
- A = the item was added by you (using
- D = the item was deleted by you (using
- ? = the item is not under the version control, but exists
- ! = the item is missing (under the version control, but does not exist - probably deleted without using
svn delete) or incomplete
See Subversion/auto-props for how to enable automatic line-ending conversion for files you add. Every developer should use it.
Commits, or check ins, are the action of applying your changes from the working copy to the web repository. Assuming you have commit access with username <user_name> and password <password>, then you may use either of the following commands to do that:
svn commit --username <user_name> --password <password> --message="This is the log comment." svn commit --username <user_name> --password <password> --file=file_with_log_comment
You may also abbreviate commit as ci.
Please note that Subversion requires you to enter a log message for every commit. Also note that in your log message, if you refer to variables using Perl's '$' notation, remember to escape them from the shell.
Converting a CVS checkout to SVN
Assuming you don't want to keep any local changes to files in the repository, it's easy to just overwrite everything with a fresh checkout. This will keep your local files, such as global.conf.
svn co http://wwrk.maa.org/svn/system/trunk/webwork2 temp-checkout rsync -a temp-checkout/ /path/to/webwork2 directory/ rm -rf temp-checkout
Repeat this for the pg and NationalProblemLibrary directories and you will have converted your WeBWorK CVS installation to a Subversion installation. You may now update your installation using Subversion as described above.
Also, if you want to get rid of the old CVS dirs:
find . -type d -name CVS -print0 | xargs -0r rm -rf
This should be done from the top level directory containing your WeBWorK installation (typically /opt/webwork). Be careful with that one because if that command is executed from any higher directory, it may delete CVS directories from other projects which you did not intend. ;)