Subversion

From HotDec

HOTDEC-SVN-HOWTO - Buck Golemon 3/1/2006

Contents 1 Overview 1.1 Clients 2 Small SVN project life-cycle 3 Larger SVN project life-cycle 4 How-to import an existing project

Overview

When working on a project from the SVN repository you will check out the the current, functional copy of the project. This is called the 'Trunk.' 'commit' saves your changes to the repository. 'update' brings any changes in the repository into your files. Whether you commit to the Trunk or to a Branch depends on the size of your current goal:

• Rule #1: "/Trunk" should compile and pass tests at all times.
• Rule #2: a single commit (changeset) must not be so large so as to discourage peer-review.
• Rule #3: if rules #1 and #2 come into conflict (i.e. it's impossible to make a series of small commits without disrupting the trunk), then the user should create a Branch and commit a series of smaller changesets there. This allows peer-review without disrupting the stability of '/Trunk'.

Clients

• Linux: The standard text-based client.
• Linux GUI: eSvn is a nice Linux graphical client.
• Windows: Tortoise SVN is an excellent user interface for subversion.
• Windows Command-line: Might be useful with MinGW

Small SVN project life-cycle

Suppose that your overall project is called 'truck' and you want to do several small coding tasks within the project. The SVN URL is 'svn://legend.me.uiuc.edu/.' Each of these changes should be fairly small, and the overall project should still compile and function between each change, so this falls under Rules #1/2 above. Here are the steps you should follow:

1. Create a working-directory for your project
2. Check-out the *entire* Trunk to this directory.
3. Update/Commit whenever the code is *functional*
4. Repeat Step 3.

Detailed instructions:

1. Create a working-directory for your project
   • We'll use '~/truck'

   
   

2. Check-out the *entire* Trunk to this directory.

   Windows:

   • right click your folder
   • select 'SVN Checkout'
   • URL = "svn://legend.me.uiuc.edu/truck/Trunk" (for the truck project)
   • OK

   Linux:

   • 'mkdir ~/truck'
   • 'svn co svn://legend.me.uiuc.edu/truck/Trunk ~/truck'

     (note that capitalization is important on Linux)

     (co is short for "checkout")

   
   

3. Update/Commit whenever the code is *functional*

   It's key that your code work before you commit it to the Trunk.

   If this isn't feasible, you should use Branches (see "larger SVN projects")

   
   

   Windows:

   • right click the working-copy folder
   • select "SVN Update"
   • You may need to resolve conflicts if the Trunk has changed.
   • select "SVN Commit"

     **enter a descriptive log message**

   • OK

   Linux

   • 'svn up ~/trunkwc/'

     ('up' is short for 'update')

   • You may need to resolve conflicts if the Trunk has changed
   • 'svn ci ~/wc/ -m "<log-message>"'

     ('ci' is short for 'commit')

   
   

4. Repeat Step 3.

Larger SVN project life-cycle

Suppose that your overall project is called 'truck' and you want to modify these files to support computer-vision. We'll call this sub-project 'vision'. The SVN URL is 'svn://legend.me.uiuc.edu/.' This goal is fairly large, so it falls under Rule #3 above. Here are the steps you should follow:

1. Make a new folder for your project
2. Checkout the *entire* Trunk into this folder
3. Make your working directory point to a new Branch.
4. Edit your working copy, committing whenever progress is made
5. When your work is finished, it is time to merge your Branch into the Trunk
6. Done!

Detailed instructions:

1. Make a new folder for your project

   We'll use '~/wc'

   'wc' is short for "working-copy," or your local copy of the project files

2. Checkout the *entire* Trunk into this folder

   Windows:

   • right click your folder
   • select 'SVN Checkout'
   • URL = "svn://legend.me.uiuc.edu/truck/Trunk" (for the truck project)
   • OK

   Linux:

   • 'mkdir ~/wc'
   • 'svn co svn://legend.me.uiuc.edu/truck/Trunk ~/wc'

     (note that capitalization is important on Linux)

     (co is short for "checkout")

3. Make your working directory point to a new Branch.

   Windows:

   • right click your folder
   • select 'TortoiseSVN->Branch/Tag'
   • change the URL to point to the new Branch

     ('svn://legend.me.uiuc.edu/truck/Branches/vision' in this case)

   • check the 'Switch working copy to new Branch/tag' box
   • fill in the log message appropriatly

     "created Branch 'vision' from Trunk"

   • OK

   Linux:

   • svn cp wc svn://legend.me.uiuc.edu/truck/Branches/vision -m "created Branch 'vision' from Trunk"

     (cp is short for 'copy')

   • svn sw svn://legend.me.uiuc.edu/truck/Branches/vision wc

     (sw is short for 'switch')

     before this command, your working copy will still 'commit' to Trunk

4. Edit your working copy, committing whenever progress is made

   (if several people are working on vision, 'update' before each commit)

   Windows:

   • right click the working-copy folder
   • select "SVN Commit"

     **enter a descriptive log message**

   • OK

   Linux

   • svn ci ~/wc/ -m "<log-message>"

     (ci is short for 'commit')

5. When your work is finished, it is time to merge your Branch into the Trunk

   Windows:

   • Check-out the Trunk into a different working-copy folder
   • right click this working-copy folder
   • select "TortoiseSVN->Merge"
   • 'From:' should point at the Branch at the revision it was created

     use 'show log' to find this number

   • 'To:' should point at the Branch *now* (HEAD revision)
   • 'Merge'
   • debug and compile this working-copy untill it runs...
   • 'SVN Commit'

     **log which Branch (vision) and revisions range (35-59) was merged**

   Linux:

   • mkdir ~/trunkwc
   • svn co svn://legend.me.uiuc.edu/truck/Trunk ~/trunkwc

     (note the revision number (59))

   • svn log ~/wc

     (note the revision number when the Branch was created (35))

   • svn merge -r 35:59 svn://legend.me.uiuc.edu/truck/Branches/vision ~/trunkwc/
   • debug and compile this working-copy untill it runs...
   • svn ci ~/trunkwc/ -m "Branch 'vision' merged into Trunk: Rev #35-59"

6. Done!

How-to import an existing project

To import a new project:

• Create a root folder for the project (name not important)
• Create 3 folders inside that folder: Trunk, Branches, Tags
• Put *all* of the files/folders needed to compile the project into 'Trunk'
• Import the root folder to the repository:

  Windows:

  • right click the top folder
  • Select 'TortoiseSVN->Import'
  • Fill in the URL and log message

    (e.g. URL= 'svn://legend.me.uiuc.edu/newproj')

    (log message should summarize the project)

  • OK

  Linux:

  • svn import <root-path> svn://<repo-URL>/<project-name> -m "<log-message>"
  • e.g: svn import ~/newproj svn://legend.me.uiuc.edu/newproj -m "new project"

Simple SVN Primer