== Introduction to subversion (svn) ==

Subversion is a tool for managing software development that keeps track of who modified what and allows returning to a previous version if changes don't do what was expected.  All the code lives on hosted-projects, and users pull the most recent version to their local machines, use it, making modifications as needed, then may push their changes back to hosted projects.

'''Conceptual model'''

 * A svn server holds one or more code repositories
 * A repository consists of all versions of the program/document under development, plus info on who made changes, and when.
 * Each version has a separate linked directory tree
 * The repository referred to here contains the ROMS Sediment Transport model code: 
 {{{
     http://svn1.hosted-projects.com/cmgsoft/roms_sed
}}}

'''Important Terms'''

   * '''''Checkout''' = get a new project from the repository''
   * '''''Update''' = get the most recent version of a project from the server (only possible after intial checkout''
   * '''''Commit''' = send your changes to the project repository''

'''Access'''

 * Anyone should be able to view the contents of the repository, look at this wiki and view the tickets.
 * A username and password are required to put your changes back into the repository. 
 * To work with data from a repository, you "checkout" a version. 
 * You can check out the most recent version or a specific release, and either the entire repository, or just certain subdirectories. 
 * Checking a project out makes a copy of the most recent version on the client requesting checkout
 * Svn suggests only checking out into an empty directory

'''What you get'''

 * If you choose to checkout the project into my_roms_sed, you’ll find trunk, branches, and tags directories created in your local directory.
 * Trunk is the main area for development, and unless otherwise instructed, work with the code in trunk
 * Tags will contain stable versions if they exist
 * Branches will have offshoots implementing new functionality- develop in the branch, then merge back into the trunk
 
'''Work flow'''

 * Start each session with update: 
 * Modify and debug the code locally
 * When you’re done with changes, commit changes to the repository 
 * This will cause the version number to be updated at the repository
 * repeat

'''Conflict resolution'''

 * Svn uses copy, modify, merge as it’s operational model
 * It is possible for two people to change the same chunk of code at similar times, and when the commit happens, this will be detected, and the users will have to interact to resolve the conflicts
 * A process similar to diff finds the conflicts
 *  Right click !TortoiseSvn, and try merge and/or blame to deal with conflicts


'''Tortoise is a GUI svn (subversion) client for PC'''

 * Get from http://tortoisesvn.tigris.org
 * Install on PC
 * When right clicking you’ll find extra menu items particularly, !TortoiseSvn
 * Use the !TortoiseSvn options to interact with the code being developed
 * A directory containing code monitored by subversion will have a .svn directory in it
 * The menu items displayed depend on what was right clicked on

'''Notes'''

 * Everything happens at the folder level- Svn doesn’t operate on single files.
 * Use svn tools to copy files into or our of a svn directory so the change can be tracked- the change will propagate to the repository on the next commit
 * The .svn directory in each project main directory keeps track of where the repository is, so you don’t have to say where to put commits, it puts them where it got them.

'''Icon Notes'''

 * What appears when you right click is context sensitive- if you’re not in a svn directory all the options won’t be shown
 * A folder that’s up to date is indicated by a green check- one that has a red exclamation point indicates changes need to be committed
 * Files in a svn directory have similar icons to the folders to give “at-a-glance” status

'''How to check out'''

 * Make a new directory
 * Select it, right click, choose Svn checkout
 * In the window enter the repository name of the project you want to get, verify it’s going to be put where you want, and click OK. (you can also choose to checkout other versions in this window, but use the “head” version for starters)


'''Handy functions'''

 * Right click on the trunk directory and select !TortoiseSvn, show log to open a window displaying revision history.
 * Right click on the trunk directory and select !TortoiseSvn, cleanup to reset odds and ends. It’s pretty easy to get into a state where svn tells you to do this.
 * The info in !TortoiseSvn, help is for the command line, but it can be adapted for use with the GUI