Using Subversion Version Control

Using Subversion Version Control

The Wireless Simulator has adapted Subversion, thanks to the helpful efforts of David Taylor-Fuller. Subversion is a file repository, which tracks changes to files over time.

Since the Wireless Simulator has been in development for four years, it has quite a history. This history has been tracked in Subversion. To learn to use Subversion, we will use the Wireless Simulator as an example project.

1.SVN Repositories & the SVNLOOK Command

First, lets look at the format of the repository concerning the wireless simulator. You will see different branches and versions using the ‘svnlook’ command:

$ svnlook tree /home/svnrepos/wiresim

You will see a trunk directory with all its files and two branch directories.

1.1) What are the branch directory names?

1.2) Does each branch directory appear to contain all the same files as the trunk directory?

1.3) What are the names of the versions in the ‘tags’ directory?

1.4) What else can we do with svnlook?

$ svnlook help

2.Looking Up SVN History

To find all the commands available within svn, enter:

$ svn --help

To see all the directories/files in the repository list, try the list command, abbreviated to ls:

$ svn listfile:///home/svnrepos/wiresim/trunk

$ svn ls file:///home/svnrepos/wiresim/branches/lincke

2.1) What printed for each of these?

A lot of directories? OK, we will need to look inside the directories.

$ svn ls -vfile:///home/svnrepos/wiresim/branches/lincke/src

To learn when the last changes were made, and who made them, use the log command. Let’s first try the help option, to see what it does:

$ svn help log

Now let’s look up history for a single file, the Network.java file:

$ svn log file:///home/svnrepos/wiresim/branches/lincke/src/wiresim/core/Network.java

$ svn log --verbose file:///home/svnrepos/wiresim/branches/lincke/src/wiresim/core/Network.java

Notice that there is a status line for each submission. The status line contains the most recent revision number, the author of the revision, the date and time of the revision, and the number of lines of code changed.

2.2) Who has worked on the file most recently? What is the most recent revision of the file? Are the revisions numbered sequentially or are some revisions skipped?

To compare two different versions of a file (versions 56 and 57), execute:

$ svn diff --revision 56:57 file:///home/svnrepos/wiresim/branches/lincke/src/wiresim/core/Network.java

Notice in the output that the lines starting with – indicate what was removed from revision 56 and + indicate what was added to revision 57.

2.3) Go back to the comment from the previous svn log command for revision 57. What does this change do?

3.Accessing Files via Checkout

We need to allocate a directory to store our working files in.

$ mkdir Lab

$ cd Lab

First we look to see what is in the repository:

$ svn ls -v file:///home/svnrepos/476lab

As opposed to checking out the entire wireless simulator, lets checkout only one directory with some documentation. You can use the command ‘checkout’ or the abbreviated form, ‘co’. This retrieves all files in the 476 lab directory:

$ svn co file:///home/svnrepos/476lab

The CSdept.txt file will be stored in the local 476lab subdirectory.

Edit the CSdept.txtfile and add information about yourself in alphabetical order.

To compare the modified file with the last committed version, execute:

$ svn diff

You should see your changes. Next, look at the status of the changes of all the files. Your change should be mentioned via this command too.

$ svn status

A subset of statuses include:

L – file locked

M – file modified locally

C – file has conflicts since modified locally and updated remotely.

A – new file has been added to the repositorysvn rm

If nothing prints, there is no difference between the current SVN version and your file(s).

3.1) What output did you get for the svn status command?

4.Committing Changes

After you edit the file CSdept.txt and you are ready to submit it into the repository, we need to see if others have made changes to the file before we commit. We want to update our working file with their changes. We can do that with an update command, which updates our working files automatically, as long as the changes can be correctly guessed.

$ svn update

You can interpret the output in this way:

G – updates have been merGed – repository and your edits successfully merged.

C – Conflicts exists: updates will need to be merged manually.

U – Updated from the repository – but you made no local changes.

The only time you need to worry is if the ‘C’ appears. Then four files will show up:

CSdept.txt – updated version with all possible merged code. Must be edited.

CSdept.txt.mine – your version

CSdept.txt.r1 – older revision that both take from

CSdept.txt.r2 – most up-to-date version in repository

If a C appears, two people modified the same exact file at the same time, and are now trying to update it in the repository. The CSdept.txt version of the file will have what SVN assumed was the right order of the changes. If two people modified code in two different places, the merge can happen automatically. If two people changed the same code, a manual merge (that means you) will need to occur.

Edit CSdept.txt until you are satisfied that the edited file has everyone’s interests in alphabetical order. When you are done, you can remove the other 3 file versions with other extensions (.mine, .r?...) This signals subversion that the manual edits are complete. Alternatively, you can use the svn resolve <filename> to indicate that you are finished manually editing the file, and it is ready for a commit.

If this gets to be too messy – and it could be when a whole class attempts to do this at once – yell for the instructor, who will play traffic cop. We want you to experience the merging process, but not get frustrated with it!!!

Now do a commit:

$ svn commit

Or

$ svn commit CSdept.txt

Opens a text file to allow you to enter a message to describe the changes you made. The top line tells you how to exit the text editor (okay, it actually tells you how to access help, which tells you how to exit): Ctrl-K H.

Prepare a clear description as to why the changes are important. Alternatively you can use the commands:

$ svn commit --message “Adding personal information about myself into a perpetual repository – I hope I never change my mind…”.

$ svn commit -- file log.txt

The last command reads comments from a file: log.txt.

If you look in your directory, the CSdept.txt file is still there for your use, but is no longer checked out.

Now let’s try the two commands again:

$ svn diff CSdept.txt

$ svn status

You can delete the CSdept.txt file and then you can retrieve it from the repository by using:

$ svn revert <filename.java>

Once the file is reverted, we can check that it is reverted:

$ svn diff CSdept.txt

$ svn status

Be careful only to do the revert when you want to change your mind about the changes you have done. If you do an svn revert when you have changed files in your directory, you will lose your changes!!!

As part of your update and commit, you may have written new code files that are not yet in the repository. Thus, you will need to add them – or perhaps you want to delete some files that are archaic and no longer useful (be careful about this though). Commands exist: svn add <file> and svn delete <file> which will add and delete such files. (Don’t do this as part of lab!) Files to be added should exist in the directory where you want the file to go in the repository.

5.Tags & Branches

DO NOT DO COMMANDS IN THIS SECTION. THEY ARE FOR DISPLAY PURPOSES ONLY.

Trunk is the released, debugged version.

Branches are useful if different but similar products are being worked on simultaneously. Branches are a working version that may be modified, updated, fixed, or enhanced. Often a branch is created for each change request. Within the CS476 course, often a branch exists for each developer in the group.

Tags are named versions or a ‘snapshot’ copy of a version at a particular point in time. It is a good way of creating a ‘baseline’.

To check out the trunk or a particular branch, use:

svn co file:///home/svnrepos/wiresim/branches/lincke

svn co file:///home/svnrepos/wiresim/trunk

This will bring in the whole tree structure of files for the link specified.

To name a version, it is possible to copy the current version to a tagged version as follows: (DO NOT DO):

$ svn copy <directory>/trunk <directory>/tags/release-1.0

You create branches in the same way as tags:

$ svn copy <directory>/trunk branches/ChangeReq-1024

To check out files, refer to the branch name:

$ svn cofile:///home/svnrepos/476lab/branches/ChangeReq-1024

The merge command is used to merge the branch into the mainline.

6.Creating a Repository

The import command creates a set of files into the repository. Below, the directory structure in dbdirectory is copied into the repository, within the Countryside directory.

$ svn import dbdirectory file:///home/svnrepos/Countryside

Before doing an import, you should be sure to create a directory structure that includes three subdirectories:

<projname>/trunk

<projname>/branches

<projname>/tags

Where under trunk you may have subdirectories: src, lib, documentation, … which actually contain your source code, etc. The branches and tags directories can be empty.

Each group should create a repository of your work in the appropriate directory, if one does not already exist. Directory names include:

/home/svnrepos/{Countryside,ModelGraphics,Assessment,K12Donation}

7.SVN Tortoise

We needed Putty .60 & TortiseSVN installed on the windows machine.

(Both should be in Moln L130) (D129 was not updated...)

Then create a new folder to use for your local copy of the files.

Right click on this new folder. Select SVN checkout.

URL of repository is:

Format: svn+ssh:///home/svnrepos/ProjectName/

Actual: svn+ssh:///home/svnrepos/476lab/

This URL goes into the top line – no changes to the rest of the screen. Enter your password three times (or so) when prompted.

After you make changes, right click the icon for the file you edited (and are ready to commit.) If you select SVN Update any changes other people have made will be updated in your file automatically (unless there are merge problems.) It is a good idea to do the SVN Update. If you do have merge problems, additional files will show up in your new directory to help you to manually merge the file.

Now you can do an SVN Commit, by right-clicking the file icon. You will be prompted for a note on the reason for your changes. Do enter appropriate notes.

This semester’s ProjectNames:

Countryside

HomelessShelter

RacineSchedule