Hints for Using SVN to collaborate on school projects
Under construction
This text is a "how to" document to be used with a graphical user interface with SVN, like RabbitVCS for linux or RapidSVN for Mac or TortoiseSVN for Windows.
Help making this better by adding SVN command line commands for examples.
Contents
SVN Basics
Directory Structure
|-- Team_Repository_Account +--branches | +-- member-id1 <-- this is the student's home in branches | +-- Task1 | +-- Task2 | +-- member-id2 | +-- Task1 | +-- Task2 | +-- Task3 | +-- member-id3 | +-- Task1 +--tags | +-- R0.1 | +-- R0.11 | +-- R0.2 | +-- R0.21 | +-- ... | +-- R0.5 | +-- ... | +-- R1.0 | +-- R1.1 | +-- R1.2 | +-- R1.21 +--trunk
Branches
- Branches is a common place for all team members' workspaces.
- Each team member should create a home directory or workspace (member-id1, member-id2,...) for his own development tasks in branches.
- The team-member's workspace is then divided in several directories (workspaces) during the development of the project. These workspaces(Task1, Task2, ...) are usually copies of the trunk to be worked on.
- These directories(Task1, Task2,...) are called branches of trunk. Also Note that when the word branch is used as a verb, it means copying the whole trunk into a subdirectory, either in Branches or tags.
Tags
- tags directory holds copies of successful stages of trunk during development. (Also called as Milestones)
- tags are never modified or edited. You may branch the a directory of tag into branches under a workspace and then modify it and apply the changes back to trunk, but the contents of a tag should never change
- The action of branching the trunk into tags is often referred to as a release.
- Most importantly, we use the tags directory to submit the work to the professor to be marked. Your professor will specify what are the requirements of a release.
- A release is usual tagged by a version like: R0.1, Prj0.2, As1_1.0
- When a release is due, always the latest version of that realease will be marked.
- If R0.3 is due, and in tags R0.3, R0.31, R0.32 are present, then R0.32 will be marked
Trunk
- trunk IS the project at current staged, complied and run-able
- trunk should never be at a non-complied stage. (usually trunk should be the exact copy as (or better than) the last version in tags).
- If only one project is done within this repository, then trunk has no project level subdirectory and is the root of the project, otherwise, trunk is divided into several directories for each project to be version-controlled.
- In this case Tags should also be divided to the exact same project directories as trunk
Basic Actions
To explain basic actions we have to clear few facts and terminology:
- Responsibility of a code repository is to keep track of all the modifications done to a project by different members.
- In other words, when a project handled by a code repository (version-controlled or in short versioned) you can track any changes done through the development life of the project; like who modified/added/deleted what and when. You can undo any work or rollback the work to any stage of the development and much more.
- SVN a client/server based repository;
- Which means the code is kept on a server and those with access can copy the whole, or pieces of the project to their local machines and work on them and then apply the changes back to the server. Note that because if this fact, one member could be unaware of the changes make by another member, unless the first one applies the changes to the server.
- Merging all the modifications by different members into the repository is another responsibility of SVN.
- a Version-controlled or versioned file, is a file that is handled and tracked by a repository
import
import is to copy 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 fist checkout the directory from the repository to the client machine.
export
export is to copy the whole or part of a repository into a non-versioned directory on the client machine
- This is usually done when you want to either package the project and make it ready for production or when you and to copy a piece of work form one repository to another repository.
checkout
checkout is to copy the code form repository server to a versioned directory on the client, so you can start working on it.
add
add is to flag a non-versioned file or directory to be added to the repository server at next commit
commit
commit is to apply (or copy) your modifications and additions to the repository server.
branch
branch is to copy a directory (like trunk) into another directory on the repository server.
- Note that after braching the code is copied on the repository and not the local(client) machine. To actually work on the branched (copied) code you must checkout the directory after branching.
merge
merge is the opposite of branch.
- "merge" merges back a branched directory, back to the original directory to apply the modifications and additions to the branched direcotry.
Starting the Project On SVN
There are two possibilities to initiate a project:
- Start the project from zero
- This is when you create a project and start the code yourself
- Start the project by continuing an existing work
- This is when you have the project started by someone else (i.e. Professor, other team-members, etc.) and you want to copy the work into your own repository and continue the work.
Start the Project from zero
For this you should create the basic framework of your project in trunk, and Add and Commit it. This is how you do this:
- checkout the project repository in a new directory on your computer;
- Create a new directory on your computer, right click on it and then click on SVN Checkout
- In URL of repository type your repository path (svn://zenit.senecac.on.ca/....)
- click on ok
- If the basic directories (trunk, tags, branches) don't exist create them and then add them by right clicking on them and selecting ...SVN/Add.
- In trunk, create your basic project framework, compile and run it. (this could be as simple as few empty files or a Hello world application).
- Right click on the trunk and select ....SVN/Add again and select all the needed file to be added to the repository.
- Add only those files that should be tracked for modification; "Those need to be version-controlled". Binary and Executable files are usually not added to the repository; Only add them if you know what you are doing.
- Right click on trunk and select SVN Commit to commit your work to repository server.
Start the project by continuing an existing work
For this you should have a non-versioned copy of the basic framework for the project to initiate it. Then you should copy the framework into the trunk, add and commitit. This is how it is done:
- Copy the basic framework into trunk of your repository
- If the basic framework in provided in another repository (namely RepA) , you should copy it by exporting it into trunk of your repository (namely RepB)
- update RepA to make sure it is in sync with the server.
- Right click on direcotry with the basic framework is provided in RepA and select "...SVN/export".
- Select the trunk of RepB and click OK
- This will create a "non-version-controlled" copy of the basic framework in RepB/trunk
- If the basic framework in provided in another repository (namely RepA) , you should copy it by exporting it into trunk of your repository (namely RepB)
- Do any modification needed to make the framework ready for work
- Right click on RepB/trunk and select Add and choose the files needed to be "versioned"
- Commit The trunk to copy the files to the server.
Preparing Branches/workspace for development
For this you should create a home direcotry for your development in branches using your seneca-id. Then your should branch the trunk into the proper workspace in your home directory in branches. Finally you should update, so the new workspace is added to your copy of the repository on your machine. Here is how:
- Create a directory with your seneca-id in branches and add it to the repository and then commit branches to update the repository server.
- Right click on the trunk and select ...SVN/"Branch/Tag" to create a branch for your next task
- By doing this you will create your first workspace to start implementation in the project. Fore next step, choose a relevant name for the task assigned to you, for example if your project is writing a text editor an your next task is to implement "Copy And Past" feature, then the proper name would something like: "CopyPaste"
- In "To URL" type or select your home dir in the branches dir, then 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 proper message for others to know what you have done
- Click on OK
- This copies the trunk into a branch so you can start your implementation, but note that this action is done on server and your local copy of repository still remains the same.
- Right click on branches and click SVN update, this will bring the new branch to your machine.
working on your branch/workspace
- You can now start implementing your assigned tasks.
- Unlike trunk, since this is YOUR workspace you can leave it an any stage you like. don't forget to comment every and each of your commits so later you know which commit belongs to what and also helps your professor to mark your.
- If you do not comment a COMMIT, it means it is minor and does not need to be marked
- You can work form home, commit your work( make sure you add comment to your commit) and them come to school checkout your code work and commit and continue later.
- Make sure if you are working on a public computer, you delete the your work from local computer, after you 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 and 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 you work back to trunk
After you have done your work in your workspace and your work is compiling and ready to go, to merge you work back to trunk:
- Right click on trunk or trunk/prj, depending on what you branched into branches
- Select "...SVN/Merge" and select "reintegrate a branch" and click on next.
- Make sure "From URL" is the branch you want to merge and click on next.
- click on "test merge" to see if merge is done successfully.
- click on "merge" to merge the branch back to trunk
- now update the trunk to have the possible changes applied.
- if there is any conflict click on "...SVN/edit conflicts" and fix the conflict, save and click on conflict resolved"
- check the trunk status in your team page on wiki
- If the trunk status is "committed" then change it to "being commited by your_name"
- If the trunk status is "being committed by member_name", wait for the commit to complete and to to previous step.
Q&A
Notes on SVN for GAM666/DPS901
==================
Assumptions:
------------
1 - the name of the local directory for your repository is repository
2 - this local directory has three sub-directories
- branches (your workspace)
- tags (your milestones)
- trunk (your successful releases)
3 - SVN has been integrated with Visual Studio 2010
Questions and Answers:
----------------------
How do I create a Visual Studio 2010 Solution named prg1 in the repository?
- Note: Always create the solution in ..\repository\branches (not in trunk)
- Open VS
- New Project
- Location: ...\repository\branches
- Name: prg1
- Check the Add to Subversion checkbox
- Click OK
- Would you like to mark prg1 as added to subversion
- Click Yes
- Create your project files
- Compile and run your project
- Close the solution
- Go to repository/branches/
- Open prg1
- Right click on prg1 sub-directory
- Tortoise SVN > Add
- Uncheck prg1/Debug
- Uncheck prg1/*.user
- Click OK
- Click OK
- Go up one directory
- Right click on branches/prg1
- Click OK
- Click OK
Which Visual Studio files shouldn't I add to the repository?
- Note: files that are not included in the repository are 'unversioned'
- Ignore the following files when adding a Visual Studio Solution 2010:
*.sdf
*.suo
*.user
*.ncb
*.sbr
.*log
Debug/*
Release/*
ipch/*
obj/*
bin/*
How do I move ..\branches\prg1 into ..\branches\jdoe\prg1 ?
- Note: a move involves a copy plus a delete
- Right click on prg1
- Tortoise SVN > Branch/Tag
- Edit To URL manually (change /branches/prg1 to /branches/jdoe/prg1)
- Add descriptive message
- Click OK
- Go up one directory to ..\branches
- Right click on jdoe
- SVN Update
- Click OK
- Right click on ..\branches\jdoe
- Tortoise SVN > delete
- Click Yes
- Right click on ..\branches\jdoe
- SVN Commit
- Click OK
How do I copy a Visual Studio 2010 Solution named prg1 into the repository?
- Make a copy of the prg1 solution directory
- Paste the copy into ..\repository\branches
- Right-click on prg1
- Tortoise SVN > add
- Uncheck the files that don't need to be added
- Click OK
- Click OK
- Right-click on prg1
- SVN Commit
- Add a descriptive message
- Click OK
- Click OK
How do I copy my completed work in branches into trunk?
- Right click on the directory in ..\repository\branches to be copied
- Tortoise SVN > Branch/Tag ...
- Edit the To URL path manually (replace 'branches' with 'trunk')
- Add a descriptive message to the text box
- Click OK
- on success 'Completed ... ' will appear is the notice box
- Click OK
- Go up to ..\repository
- Right click on trunk
- SVN Update
