Subversion Advice

Overview

Subversion offers a large number of possible commands and/or options for using its “change management (CM),” or version control, system. However, rather than explicitly displaying and describing all of these numerous features, the following guide simply describes the most important and commonly-used commands (w/ related concepts) regarding Subversion control. Once obtaining a decent understanding of this guide, you should be able to successfully contribute to a project in the Subversion repository. In the future, some actions may require additional knowledge or concepts not covered in this guide, but if that is the case, refer to the extensive guide found in this Subversion Guide.

Subversion Access

What To Check Out

KUSP Kernel

We now manage the KUSP kernel using GIT rather than Subversion. See
the GIT Advice Page for information on accessing the KUSP Kernel GIT Repository.

KUSP Kernel Configurations

Check out the set of example configuration files so that it is sibling to your kernel directory:

bash$ svn co https://subversion.ittc.ku.edu/svn/libertos/kernel/kurt/<kernel version>/configs

KUSP Userspace Source Trees

The SVN URL for the current stable KUSP Software tree is:

https://subversion.ittc.ku.edu/svn/libertos/kusp/trunk

and can be accessed via SVN using the following command:

bash$ svn co https://subversion.ittc.ku.edu/svn/libertos/kusp/trunk
  • Note that if you logged into the ITTC intranet, you will be required to type in your password to checkout.

Other Kernels

Subversion Control

Useful Commands

  • svn –help : Lists the different subversion commands (recommended to use if unsure of command syntax/ functionality)
  • svn help <command> : Help for the specific command entered
  • svn cat <filename> : Lists the contents of file ‘’filename’’ under Subversion control

Initial Checkout

To begin using a Subversion repository, you typically must run the following command to checkout your project. Checking out a repository essentially creates a “working copy” of it on your local machine (where it is checked out to). This working copy contains the latest revision (commonly referred to as the HEAD) of the Subversion repository. The specific project (repository) must be specified after the command:

  • svn checkout <current stable kernel url> : Checkout every

    file from the path and subdirectories specified. The URL following the checkout command can possess one of several formats, but the one provided in this guide corresponds to the current kernel being modified by clients. Note: in the future, the most recent repository URL may change.

Updating a Working Copy

This command is near the top of the list for a good reason. Before committing ANY modifications to the repository, make sure you run the following update command to ensure that you are working with the most up-to-date revision. Otherwise, undesired consequences may result.

  • svn update : Brings working (local) copy of files into sync with latest revision in repository. This command should always be run before committing any local changes to the repository in order to avoid overwriting changes made by another client to the same file(s). After running this command, it will be clear if any files have been modified since the last update and if any conflicts exist. See below for resolving merge conflicts.

Making Changes

The following commands are commonly used when modifying any file(s) within your working copy (of the repository), so it is important to fully understand the function and related consequences of each command before using any of them.

  • svn add <filename> : Add the specified file

    svn add <directory> : Add the entire directory and everything underneath it to subversion control.

    Note that the file (directory) will not be available in the repository until it is checked in (or committed) using the check-in or commit commands:

    svn ci <file or directory name>

    command described below. Also, if a directory is added, all of its contents are recursively added

  • svn delete <name> : Schedule file, directory, or symbolic link name to be deleted from the repository. If name is a file or symbolic link, it is immediately deleted from the working copy. However, if name is a directory, it is not immediately deleted. Subversion schedules it for deletion, so it will be removed from the working copy and the repository once modifications are committed (using svn commit, as seen below)

  • svn copy <orig> <next> : Copies the contents of orig to new

    item next and automatically schedules next for addition into the repository. Note: this command does not create intermediate directories. When next is committed to the repository, its copy history is also recorded with it.

  • svn move <orig> <next> : Moves the contents of orig to new

    item next and automatically schedules next for addition into the repository. The original item orig is scheduled for deletion from the repository. Note: this command also does not create intermediate directories.

  • svn mkdir <newdir> : Creates new directory named newdir and schedules the directory for addition into the repository

  • Note: as you may have noticed, the term “schedule” is used several times in the previous descriptions. The reason for using this term is to make a distinction between modifying the working (local) copy and modifying the actual repository. When something is “scheduled” for a particular action, this action will not actually take place until the changes are committed (checked-in) to the repository (via the svn commit command).

Evaluate/ Verify Changes

The following commands allow you to re-examine the changes you have made (to any files) and to make sure that you still desire to commit the specific changes to the repository. If nothing else, several are useful for determining which files you have actually modified in your working copy, a task that may otherwise be difficult to do if many files (locations) were changed since the last commit.

  • ‘svn status: Detects and displays an overview of all the file

    and tree changes you have made to your working copy. The default output of this command, as seen below, provides very useful information regarding the status of the files you have changed since the last update (svn update):

    • A item - the file, directory, or symbolic link item has been scheduled for addition into the repository.
    • C item - the file item is in a state of conflict. In other words, changes received from server during an update overlap with local changes that you’ve made in your working copy. This conflict must be resolved before committing the changes to the repository.
    • D item - the file, directory, or symbolic link item has been scheduled for deletion from the repository.
    • M item - the contents of the file item have been modified (reflects a file that has been changed in your working copy).
  • svn status <PATH> : A path can be specified as a parameter in

    order to receive the status of only the item pointed to by <PATH> (rather than seeing the status of all files that have been modified in your working copy)

  • svn status -v : The verbose (–verbose or -v) option displays the status of every file in the working copy, even files that have not been modified

  • svn diff : Another way to examine the changes you have made to your working copy that allows you to see precisely where and how you modified the involved files. This information is output in a pre-specified format that can be altered (if desired). The information is output in unified diff format, where any lines (i.e. lines of source code) removed from a particular file are prefaced with “-” and any lines that were added to a file are prefaced with “+”. In addition, filenames (corresponding offset information) are printed to the console.

  • svn revert <item> : Restores the file <item> to the state it was in before any modifications were made to it in your working copy. If you make any changes to a file that you wish to “undo,” this command allows you to erase the changes you made. Also, it can undo any scheduled operations (i.e. svn add <item>) and restore a file that you mistakingly schedule to be deleted from the repository.

    • Note: Modifications to files are determined by comparing the files in your working copy to the files in the cached copy in the .svn (administrative) area, which is checked out every time something is checked out from the repository. The .svn area should never be modified, for it keeps a cached copy of the files as they were before any modifications were made in your working copy. This allows (limited) examination of differences (i.e. via svn diff) without requiring connection to the online repository.

Resolving (Merge) Conflicts

Conflicts can occur if the changes made to a given file (in a client’s working copy) conflict with changes made to the same file(s), particularly the same section of the file(s), by another client. That is, any overlapping of changes made to the repository with modifications you have made in your working copy will result in conflict(s) that must be resolved. Any files that possess conflict(s) cannot be committed to the repository (from your working copy) until the conflicts are fully resolved. Instructions for accomplishing this are the following:

When a conflict occurs, three things typically occur to assist you in resolving the given conflict:

  • To indicate the conflict, a C is displayed on the left

    side of the file where the conflict occurred (after running svn update)

  • If the file is considered to be mergeable, Subversion places

    conflict markers, or specific strings of text which delimit the beginning and end of the section of conflict, into the file to visibly indicate the overlapping section(s).

  • For every file in which a conflict occurs, Subversion temporarily generates three related files:

    • filename.mine - this is the conflicted file as it exists in

      your working copy (without conflict markers) and has only the latest changes you made to the working version

    • filename.rOLDREV - this is the BASE revision of the

      conflicted file, before you updated your working copy; in other words, it is the file that was initially checked out from the repository before any modifications were made. OLDREV is actually the revision number of the file in the .svn directory mentioned earlier

    • filename.rNEWREV - this is the conflicted file that was

      received from the server when your working copy was updated; it is the latest revision of the file in the repository, and NEWREV is the corresponding revision number

Once these files are generated, Subversion will not allow you to commit any changes to the repository until all three temporary files are successfully and correctly removed. This can be accomplished by completing one of the following tasks necessary in resolving a conflict:

  • Examine the files in which the conflict(s) occurred, and merge the

    conflicts manually. As mentioned earlier, conflicts residing in a particular file are marked by special strings that indicate what section(s) is/are in conflict. Be sure to merge the conflicting sections appropriately as well as remove the corresponding conflict markers

  • As long as it does not produce undesired results, you can copy one

    of the temporary files (see above) onto your working copy of the conflicting file

  • Use the svn revert <filename>‘ command to undo all changes

    made to the working (local) copy of <filename>

Finally, once the involved conflict(s) are completely resolved, use the following command to notify Subversion that the conflict has been resolved, thus removing the three temporary files (mentioned above) and allowing you to commit the desired changes to the repository:

  • svn resolved <filename> : where <filename> is the specific file in which the conflicts were resolved

Committing Changes

This essentially is the final and potentially most dangerous command under Subversion. Before running the following command, make sure to update your working copy to the latest revision (from the repository), resolve any and all conflicts, and examine any changes made to verify that you still desire to commit these changes into Subversion control:

  • svn commit -m “<log message> : When committing any changes, it

    is necessary to provide an accompanying log message describing the change(s) you made. If the [log message] is short enough, it can be explicitly stated using the -m (–message) option