Subversion

Subversion is the source code control system that the XINU project uses to maintain its code base. All repositories are hosted by the Marquette University Linux Users Group and are available for access by anyone who is part of the XINU team or upon special request. Below is an explanation of how to use subversion (svn) and the layout of the repository.

Common Commands

If you ever forget a command, there is a list posted in CU 310.

There are many subversion commands at your fingertips, but only 3-5 of them are used on a daily basis. In this section we cover the update, commit, checkout, add, remove, and status. All commands can be executed from any subversion checkout. In our example we will assume our working copy is located at ~/xinu and our repository is located at https://xinu.mscs.mu.edu/svn/mips/trunk.

checkout

This command is aliased with svn co.

Checkout will create a new working copy of a repository on your local machine. This is done through one of the following commands:

svn checkout https://xinu.mscs.mu.edu/svn/mips/trunk ~/xinu
svn checkout svn+ssh://svn@xinu.mscs.mu.edu/svn/mips/trunk ~/xinu

You may have to enter a username and password.

update

This command is aliased with svn up.

Update will synchronize a working copy with the most recent version stored in main repository. While updating, all files that have been changed will display a status flag:

• A -- A file was successfully added to the working copy.
• D -- A file was successfully deleted to the working copy.
• U -- A file was successfully updated in the working copy.
• C -- Subversion failed to update the working copy to the most recent version. This must be resolved.
• G -- Subversion successfully merged the working copy and the most recent version.

So, from our working copy we can type the command:

svn update

Once the update is complete you should be "at revision 1428."

commit

This command is aliased with svn ci.

Commit will send local changes on a working copy to the main repository. It is greatly recommended that you update prior to committing, otherwise it is possible that a failure will occur. To commit changes, use the command:

svn commit

Optionally you can provide a list of files to commit if you do not want all your changes sent to the main repository. Every commit has an associated log message which is written using your editor of choice after typing the command. If you have not set an $EDITOR variable for you shell, you must do that (for bash this is done by export EDITOR=vim where vim is your editor of choice).

propset

This command is aliased with svn pset and svn ps.

In mips/trunk/ all files should have the svn:keywords "Id" property set on them. This will automatically fill in the $Id$ tag. At some point there may be a pre-commit hook on the subversion repository to enforce this rule, but for the time being the following command can be used:

svn propset svn:keywords "Id" <list of files>

This will set the property on every file in the list of files. If you perform a svn status after this there should be a M in the second column of files you've set the property on.

status

This command is aliased to svn st.

Status will let you see what files you have changed in your working copy as compared to the most recent version from the main repository. The same flags are associated with the status command as with the update command. To view these changes, run the command:

svn status

add & remove

The remove command is aliased with svn delete, svn del, and svn rm.

After viewing a status you may face files with the flags ! or ?. These mean a file is missing (!) or subversion does not know about a file (?). Typically files with an ! imply that they have been removed from the working copy, but subversion has not been informed about this change. To do this, run:

svn remove path/to/file

And subversion will change the status to D. If you are removing a file using the subversion command will remove the file from the file system as well, if you remove a directory tree the tree will be removed after the commit.

Similarly, if a file has the ? flag associated with it, subversion does not know it has to add the file to the working copy. Like the remove command, this can be run by:

svn add path/to/file

If you add a directory tree, subversion will recursively add all files below the parent as well as the parent node.

Remember, none of these changes will be stored in the main repository until you commit!

Other Commands

If ever you want a detailed description of a command (or just a list of commands) you can use subversions help feature. svn help will provide a listing of the commands that are supported, while svn help <command> provides a detailed description of what that command does.

This should cover the majority of commands used in daily subversion usage. If you want to know more about subversion the online subversion book is an excellent resource.

Here a few (slightly less common) subversion commands

revert

Sometimes you'll make changes to a file and later decide it was a waste (or more likely you changed a file to get XINU running and don't want to commit that file). You could carefully undo every change you've made to the file, but that seems not elegant and downright tedious. Thus we have the revert command that will rollback the changes to the most recently checked out version. The command is simple:

svn revert path/to/file

Followed by text that will confirm the reverted files (you can revert multiple files with the same command).

copy

This command is aliased with svn cp.

Largely this command is used for creating branches or tags in the repository. Subversion does lightweight copies so this is typically a quick operation. This example will create a test branch under mips/branches that was copied from trunk at creation time.

svn copy https://xinu.mscs.mu.edu/mips/trunk https://xinu.mscs.mu.edu/mips/branches/test

After which you will be prompted for a log message. You could also append a -m "- created branch for testing purposes" which will use that text as the log message.

Repository Layout

Note that not everyone will have full (read and write) access to the entire repository, however read access is granted to the majority of folders. A grammar that describes the repository follows:

          URI ::= svn+ssh://svn@xinu.mscs.mu.edu/<repo>
                | http[s]://xinu.mscs.mu.edu/svn/<repo>

       <repo> ::= mips/<svn-dir>
                | intel/<svn-dir>
                | ppc/<svn-dir>
                | debugger/<svn-dir>
                | tools/<tool-dir>
                | projects/<project-dir>
                | <math>\epsilon</math>

   <tool-dir> ::= console/<console-dir>
                | debugger/<svn-dir>
                | firmware/
                | uboot-img
                | <math>\epsilon</math>

<console-dir> ::= unix/<svn-dir>
                | windows/<svn-dir>

    <svn-dir> ::= trunk | branches | tags | <math>\epsilon</math>

   <proj-dir> ::= rebooter
                | windows-tools
                | cosc198-netaa
                | cosc198-netpj
                | cosc198-mempj
                | <math>\epsilon</math>

The <proj-dir> is the most unstable directory of XINU since various team projects come and go throughout the year.