Hints for Using SVN to collaborate on school projects

This is a "how to" document for using a graphical user interface with SVN. Graphical user interfaces include

• RabbitVCS for linux
• RapidSVN for Mac
• TortoiseSVN for Windows

Help improve this document by adding SVN command line commands for examples.

SVN Basics

Directory Structure

|-- Team_Repository_Account
  +--branches
  | +-- member-id1  <-- this is a team member's home within branches
  |   +-- Task1
  |   +-- Task2
  | +-- member-id2  <-- this is a team member's home within branches
  |   +-- Task1
  |   +-- Task2
  |   +-- Task3
  | +-- member-id3  <-- this is a team member's home within branches
  |   +-- Task1
  +--tags
  | +-- R0.1
  | +-- R0.11
  | +-- R0.2
  | +-- R0.21
  | +-- ...
  | +-- R0.5
  | +-- ...
  | +-- R1.0
  | +-- R1.1
  | +-- R1.2
  | +-- R1.21
  +--trunk

branches

• branches is the common directory for all team members' workspaces.
• Each team member should create their own home directory or workspace (member-id1, member-id2,...) for their own development tasks within branches.
• Each team member should divide their workspace into several sub-directories (workspaces) during the development of the project. These workspaces(Task1, Task2, ...) are usually copies of the trunk to be worked on.

  These sub-directories(Task1, Task2,...) are called branches of trunk. When the word branch is used as a verb, it means copying the whole trunk into a sub-directory, either in branches or tags.

tags

• tags is the directory that holds copies of successful stages of trunk throughout development. (Also called as Milestones)
• tags are never modified or edited. You may branch a directory of tag into branches under a workspace and then modify the branch and apply the changes back to trunk, but you should never change the contents of a tag
• The action of branching the trunk into tags is often referred to as a release.
• We use the tags directory to submit the work for marking. Your instructor will specify the requirements of a release.
  • A release is usually tagged by a version number like: R0.1, Prj0.2, As1_1.0
  • When a release is due, your instructor will always mark the latest version of that release.

    If R0.3 is due, and R0.3, R0.31, R0.32 are present in tags, then your instructor will mark R0.32

trunk

• trunk is the directory that holds the project in its current stage, complied and run-able
• trunk should never hold non-compiled code. Usually trunk is an exact copy (or better than) the latest version in tags.
• If only one project is within the repository, then trunk has no project level sub-directory and is the root of the project. If more than one project is within the repository, trunk is divided into several aub-directories for each project to be version-controlled.

  In this case tags should also be divided into exactly the same project sub-directories as trunk

Basic Actions

A few important facts and terminology to help clarify the basic actions:

• One responsibility of a code repository is to keep track of all of the modifications done to a project by its team members.

  In other words, in a project that is handled by a code repository (version-controlled or in short versioned), you can track any changes during the project's development life; such as, who modified/added/deleted what and when. You can undo work or rollback the work to any stage of the development and much more.

• SVN is a client/server repository;

  The code is kept on a server and those members who have access can copy the whole or parts of the project to their local machines, work on the whole or parts and then apply their changes back to the server. Because of this, one member may be unaware of the changes made by another member, unless the other has applied the changes to the server.

• Merging the modifications of different members into the repository is another responsibility.
• A Version-controlled or versioned file is a file that is handled and tracked by a repository

checkout

To checkout is to copy the code from a repository server to a versioned directory on the client, so that you can start working on the code.

branch

To branch is to copy a directory (like trunk) into another directory on the repository server.

Note that branching the code copies it on the repository itself and not to the local (client) machine. To work on the branched (copied) code, you must checkout the directory to which you copied the branch.

add

To add is to flag a non-versioned file or directory to be added to the repository server at next commit

commit

To commit is to apply (that is, to copy) your modifications and additions to the repository server.

merge

To "merge" is to merge back a branched directory, back to the original directory; that is, to apply the modifications and additions to the branched directory.

merge is the opposite of branch.

export

To export is to copy the whole or part of a repository to a non-versioned directory on the client machine

You export when you want either to package the project, to make it ready for production, or to copy a piece of work from one repository to another repository.

import

To import is to copy a non-versioned work (directory) to a repository server.

note that in this case the imported code is on the server and is still NOT versioned on the client machine; to start working on an imported directory, you should first checkout the directory from the repository to the client machine.

Starting a Project On SVN

There are two ways to initiate a project on SVN:

1. To start the project from zero

   We do this when we create an empty project and start to write the code from scratch

2. To start the project by continuing existing work

   We do this when someone else has started the project (that is, the professor, other team-members, etc.) and we want to copy the work into our own repository and continue that work.

Start the Project from zero

To start from zero, create the initial code of your project in trunk, add the code, and commit it. These are the steps:

1. checkout the project repository in a new directory on your computer;

   1. Create a new directory on your local computer, right click on the directory, and then click on SVN Checkout
   2. In URL of the repository type your repository path (svn://zenit.senecac.on.ca/....)
   3. click on ok

2. If the basic directories (trunk, tags, branches) don't exist, create them and add them by right clicking on them and selecting ...SVN/add.
3. In trunk, create your project, compile it, and run it. (This could be as simple as few empty files or a Hello world application).
4. Right click on the trunk, select ....SVN/add, and select all of the files to be added to the repository.

   Add only those files that you want to track for modification. "Only the source and project files need to be version-controlled". Binary and executable files are usually not added to the repository. Add them only if you have a reason for doing so.

5. Right click on trunk and select SVN Commit to commit your work to the repository server.

Start the project by continuing an existing work

To continue an existing work, you should have a non-versioned copy of the initial code for your project. You should copy this code into the trunk, add and commitit. These are the steps:

1. Copy the initial code into the trunk of your repository

   If the code is available in another repository (say RepoSrc), export from RepoSrc into trunk of your repository (say RepoDest)

   1. update RepoSrc to make sure that it is in sync with the server.
   2. Right click on the directory with the initial code in RepoSrc and select "...SVN/export".
   3. Select the trunk of RepoDest and click OK

      This will create a "non-version-controlled" copy of the initial code in RepoDest/trunk

2. Do any modification needed to make the initial code ready for work
3. Right click on RepoDest/trunk and select Add. Then choose the files that you want to be "versioned"
4. Finally, Commit the trunk to copy the files to the SVN server.

Preparing Your Own Workspace for Development

Create a home directory in branches for your development and name that directory with your seneca-id. Then branch the trunk into the proper workspace in your home directory under branches. Finally update your workspace, so that the code is added to your copy of the repository on your machine. These are the detailed steps:

1. Create a directory in branches and name it with your seneca-id
2. add the directory to the repository and commit branches to update the repository server.
3. Right click on trunk and select ...SVN/"Branch/Tag" to create a branch for your next task

   • This will create your first workspace. Choose a relevant name for your assigned task. For example if your project is writing a text editor and your next task is to implement "Copy And Paste" feature, then a suitable name would be: "CopyPaste"
   • In "To URL" type or select your home sub-directory in the branches directory and add "/CopyPaste" to it: (svn://RepoUrlAndPath/branches/yourSenecaid/CopyPaste")
   • Select HEAD revision or a specific revision if necessary (mostly head revision applies in our case)
   • Add a descriptive message to inform others about what you have done
   • Click on OK

   This copies the trunk into a branch so you can start your own implementation. This action is done on server and your local copy of the repository remains unchanged.

4. Right click on branches and click SVN update. This will download the new branch to your local machine.

Working within your own Workspace

You can now start to implement your assigned tasks.

• Unlike trunk, you can leave YOUR workspace in any state you like. Comment each and every commits so that later you know which commit belongs to what and your professor knows what to mark.
• If you do not comment a COMMIT, it means that it was minor and does not need to be marked
• You can work form home, commit your work, come to school, checkout your committed code, and continue later.
• If you are working on a public computer, make sure to delete your work, after you have committed it to the repository.

  It is your responsibility to keep your code safe

• If you have any problem with your code, and need help, contact your professor, send the path of your workspace. If needed, he can checkout your code see what is wrong with it, leave comments on it, and commit it. Afterwards, all you need to do is update your repo and read the comments and corrected code.

Merging your work back to trunk

After you have completed your work within your own workspace and your code compiles and is ready to go, you can merge your work back to trunk. These are the detailed steps:

1. Right click on trunk or trunk/prj, depending on what you branched into branches
2. Select "...SVN/Merge", select "reintegrate a branch", and click on next.
3. Make sure "From URL" is the branch you want to merge and click on next.
4. Click on "test merge" to see if the merge is successful.
5. Click on "merge" to merge the branch back to trunk
6. Now update the trunk to apply the changes.
7. If there are any conflicts, click on "...SVN/edit conflicts" and fix each conflict, save and click on conflict resolved"
8. Check the trunk status in your team page on the wiki

   • If the trunk status is "committed" then change it to "being committed by your_name"
   • If the trunk status is "being committed by member_name", wait for them to complete their commit and go to previous step.

9. Commit the trunk and when done, update the truck status to "committed by your_name"
10. If this commit was worth recording, branch it in the tags directory under a new release.

If you receive a "branch/project must be ancestrally related to trunk/project" error, try going into your trunk and right click > merge one file at a time. Make sure to click the "show log" button in the merge wizard to get the latest revision for the merge added for you.

Resources

• SVN