SVN Commit Access
The purpose of this article is to give an overview of the most commonly used Subversion (SVN) commands a WeBWorK developer will need to use. It is largely adapted from Chapter 2 of Subversion book. Readers are strongly encouraged to look there for more comprehensive instructions for using Subversion. The article Subversion is an introduction to Subversion, an overview of the structure of the WeBWorK subversion repositories, and basic information on how to check out and update the WeBWorK code using SVN. All readers should start there; it is information developers must also know, and contains all of the information about Subversion needed for installing and maintaining WeBWorK. The links below may also be of interest.
These instructions assume that you have checked out a working copy of the WeBWorK code as explained in the article Subversion. (Also, although none of these instructions require it, we'll go ahead and assume that you've also set up a development server. After all, you are testing your work, right?)
Update your working copy
Use svn update (or svn up) to bring your working copy into sync with the latest revision in the repository. For example,
jason@goedel:~/webwork/webwork2$ svn up D clients/webwork_xmlrpc_inc.pl U clients/renderProblem.pl A htdocs/js/wz_tooltip.js U htdocs/js/ww_applet_support.js A lib/WebworkClient.pm Updated to revision 6295.
Here notice that the svn up command was executed from within the directory I wished to update. This command optionally takes a path as an argument. For example, from my home directory the command
$ svn up webwork/webwork2/
would have been equivalent. When executing the svn update command, one may also specify a revision number to synchronize a working copy with a particular revision, as in
$ svn up -r6000 [PATH...]
In any case, Subversion will repond with a list of any changed files and concluded by reporting the current revision number. In the example above, the letter codes D, U and A indicate how the particular files changed since my last update. For example, the file clients/webwork_xmlrpc.inc.pl was Deleted. The file clients/renderProblem.pl was Updated, and the file htdocs/js/wz_tooltip.js was Added. Other possibilities are Conflict, MerGed, and Existed, all discussed below. For additional help on this command try svn help update.
Finally, the Subversion client understands a number of revision keywords. These keywords can be used instead of integer arguments to the --revision (-r) option, and are resolved into specific revision numbers by Subversion:
The latest (or “youngest”) revision in the repository.
The revision number of an item in a working copy. If the item has been locally modified, this refers to the way the item appears without those local modifications.
The most recent revision prior to, or equal to, BASE, in which an item changed.
The revision immediately before the last revision in which an item changed. Technically, this boils down to COMMITTED−1.
Now you can get to work and make changes in your working copy. It's usually most convenient to decide on a discrete change (or set of changes) to make, such as writing a new feature, fixing a bug, and so on. The Subversion commands that you will use here are svn add, svn delete, svn copy, svn move, and svn mkdir. However, if you are merely editing files that are already in Subversion, you may not need to use any of these commands until you commit.
You can add files or folders to the working copy, to be included the next diff or commit, using the command:
svn add foo
This will schedule file, directory, or symbolic link foo to be added to the repository. When you next commit, foo will become a child of its parent directory. Note that if foo is a directory, everything underneath foo will be scheduled for addition. If you want only to add foo itself, pass the --depth empty option. If you add a folder, it will add all the files included in the folder, except for files in the ignored list. See svn help add for additional options.
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 foo
This command will schedule file, directory, or symbolic link foo to be deleted from the repository. If foo is a file or link, it is immediately deleted from your working copy. If foo is a directory, it is not deleted, but Subversion schedules it for deletion. When you commit your changes, foo will be entirely removed from your working copy and the repository. See svn help delete for more information.
Note: if file or folder you have scheduled for deletion local modifications, Subversion will not delete them unless you force the deletion.
Create a new item bar as a duplicate of foo and automatically schedule bar for addition. When bar is added to the repository on the next commit, its copy history is recorded (as having originally come from foo). svn copy does not create intermediate directories unless you pass the --parents option. See svn help copy.
This command is exactly the same as running svn copy foo bar; svn delete foo. That is, bar is scheduled for addition as a copy of foo, and foo is scheduled for removal. svn move does not create intermediate directories unless you pass the --parents option. See svn help move.
Examine your changes
Once you've finished making changes, you need to commit them to the repository, but before you do so, it's usually a good idea to take a look at exactly what you've changed. You can see an overview of the changes you've made by using svn status, and dig into the details of those changes by using svn diff.
You can check the status of your working copy files and directories using the following command:
You can also pass a path to a directory of filename in your working copy. The output of svn status will contain seven one-character columns of coded information about the status of the files and directories in your working copy. Typically the first column is the most important, and reports if the item was added, deleted, or otherwise changed. For example, the most commonly seen codes in the first column are:
- ' ' no modifications
- 'A' Added by you (using
- 'C' Conflicted - local changes conflict with most recently obtained repository version
- 'D' Deleted by you (using
- 'M' Modified by you (and there are no conflicts)
- 'R' Replaced by you
- '?' item is not under version control, but exists in working copy
- '!' item is missing (probably deleted without using
svn delete) or incomplete
The other column codes are of course important to become familiar with. See svn help status for more information.
By default, svn status will only report on locally modified items. This behavior can be modified by passing the -u [--show-updates] argument. Passing -q [--quite] will cause svn status to print only summary information. Again, see svn help status for more information.
Note for CVS users: You're probably used to using cvs update to see what changes you've made to your working copy. svn status will give you all the information you need regarding what has changed in your working copy—without accessing the repository or potentially incorporating new changes published by other users. In Subversion, svn update does just that—it updates your working copy with any changes committed to the repository since the last time you updated your working copy. You may have to break the habit of using the update command to see what local modifications you've made.
You can find out exactly how you've modified things by running svn diff with no arguments, which prints out file changes in unified diff format. Diffs, or patches, are text files which include all the changes done in the working copy. If you suggest work on a bug 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
Again the output of svn diff is displayed in unified diff format. That is, removed lines are prefaced with -, and added lines are prefaced with +. The svn diff also prints filename and offset information useful to the patch program, so you can generate “patches” by redirecting the diff output to a file:
$ svn diff > patchfile
You could, for example, email the patch file to another developer for review or testing prior to a commit.
Applying a diff
Subversion does not contain a built in command to apply patches to the current working copy (for example, to review or commit patches published in Bugzilla); instead, you can use the regular patch unix utility:
patch -p0 < patch_file
Possibly undo some 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
Resolve conflicts (merge others' changes)
- 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:
Commit your changes
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.
See Subversion/auto-props for how to enable automatic line-ending conversion for files you add. Every developer should use it.