Difference between revisions of "SVN for School Projects"

From CDOT Wiki
Jump to: navigation, search
(→‎branches)
(→‎Svn basic commands)
 
(71 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
''Work in progress, please help make this page more useful for students''
 
=What is svn?=
 
=What is svn?=
−
[http://svnbook.red-bean.com/ svn (Subversion)] is a source code repository. It is a program capable of storing the source code of a project and keep track of all the changes made (contributions) by its developers.
+
[http://svnbook.red-bean.com/ svn (Subversion)] is a source code repository. It can keep track of all the changes made (contributions) to a project by its developers. We use it to keep track of changes to our source code.
 
===What svn can do for you?===
 
===What svn can do for you?===
−
* Stores your work (source code) safely on a remote server so you will never lose your work.
+
svn can
−
* Lets several students work on the same project at the same time.
+
* Store your work (source code) safely on a remote server so you will never lose that work.
−
* Keeps track of all the work done with history (who have done what, and when), this means you can:
+
* Let several students work on the same project at the same time.
−
*: undo your work to any of the past stages of the work.
+
* Track the history of all the work done (who did what and when). This means that you can:
−
*: look at different stages of the work and see all the changes.
+
*: undo your work to any past stage.
−
*: check other team members' work, their progress and contribution.
+
*: look at different stages of the work and compare the changes.
−
*: ask for help from others to help you with your work and help others with their work.
+
*: check other team members' work, their progress, and their contribution.
−
* to be continued...
+
*: ask others for help with your work and help others with their work.
 +
* Submit a paper-less assignment.
 +
*: Once you have tagged your work, your professor can
 +
*:# checkout and evaluate your work
 +
*:# mark your assignment fairly seeing each student's contribution.
 +
*:# help you with your assignment by commenting and correcting your work remotely.
  
 
=Common actions for school projects=
 
=Common actions for school projects=
 
==Kick-start a project (project initiation)==
 
==Kick-start a project (project initiation)==
−
==start working on a project==  
+
# Create a directory to hold all of your team's work
−
==Start a task==
+
# Checkout the entire repository into that directory
−
==Continue working on a task on a new computer==
+
#: Look and make sure that you have the 3 directories (branches, tags, trunk)
−
==Continue working on a task (everyday work)==
+
# Open the branches directory and create a sub-directory using your login name
 +
#: this becomes the root of your own (each students') workspace
 +
#: ''' note: do not use the operating system's file management to copy, move, etc any of the '''''versioned''''' files
 +
# Update the whole repo to see all of the changes from all team members
 +
# Branch the trunk into a sub-dir of your workspace (name this sub-dir with your assigned task)
 +
#: the verb branch means copy (in the repository)
 +
You are good to go - you can start working on your task
 +
 
 +
==Start working on a project (start a new task)==
 +
# If you have not already branched trunk:
 +
#: branch/tag trunk into a sub-directory under your workspace. Use your task name/description so you can refer to it easily later.
 +
# do your work within your branch/task directory and commit anytime you have something worth committing. Make sure that you comment each commit.
 +
#: '''Note that in your branch you can commit your work even if it is incomplete. In fact, commit your work anytime you are leaving your computer and comment it like: "going for lunch". But again you should only do this when you are working in '''''YOUR OWN BRANCH'''''
 +
# When your task is complete
 +
## Update the repository to apply all of the changes to your local copy
 +
## Merge your changes back to trunk
 +
#: Note that, the merging happens on the local copy and not the repository
 +
# Edit possible conflicts, save and mark them as resolved when done.
 +
# Compile the trunk, test and make sure that the changes are what you want
 +
# In trunk, apply more changes and do debugging if needed.
 +
#: note that this is the only time you should be doing any work in trunk
 +
# When everything is perfect prepare to commit the trunk:
 +
## Make sure that you are logged in to IRC.
 +
## Go to team page and set trunk's status to committing with following info: User ID, email, IRC Nick, time and date
 +
## If trunk's status is already committing by another user, communicate with them and find out when they are going to be done so you can do your commit.
 +
##: ''Never commit to trunk with out checking and setting the status of trunk in your team page''
 +
## Update the repository
 +
# Commit the trunk
 +
# Edit, save and resolve possible conflicts and go to previous step
 +
# When done, go to the team page and set trunk's status back to committed with the same info as before.
 +
 
 +
==Continue working on your current task on a new computer (public computer)==
 +
# Checkout only your branch/task
 +
# Work on your task and keep committing the changes as you go.
 +
# When done, do final commit, noting that the work period is done
 +
# Delete the checked-out directory from the public computer.
 +
# '''''Reboot the computer'''''
 +
#: this will remove your userid and password if you chose to save them.
 +
#: Note that you are responsible to keep you work safe.  If someone gains access to your code and repository, YOU are responsible for it and its consequences.
 +
 
 +
==Continue working on your task (everyday work)==
 +
# Update the repository to get the most recent changes.
 +
# (optional and only if needed:) If trunk is updated by someone else since the time you branched it, you can merge the '''updated''' trunk into your branch to get the latest additions and modifications of trunk in your branch.
 +
# Continue working on your task and keep committing often.
 +
# when done for the time being, commit your work and comment, noting the stage of your work.
 +
 
 +
==Release your completed task (submit an assignment or a release)==
 +
# Do this when a major task is finished and it is time to present it to your professor.
 +
#: This is not necessarily to hand in a new release. It could be at any time you feel you are one step closer to the end of the project.
 +
# Update and make sure the trunk has the latest modifications.
 +
# Do all possible changes and fixes to make this release final.
 +
# Tag (branch) the trunk into a sub-directory in '''tags'''.
 +
#: Name the tagged directory relative to its state (i.e. name it '''R0.4''' and comment it with task name '''Text Editor''')
 +
#: If this is a fix to a previously released trunk, add the release revision after the release number: (i.e R0.41 and comment it as '''Fixed backspace bug in Text Editor''') 
 +
# Your prof will later update the repo on their computer and get your Release.
 +
 
 
=Standard svn tree structure=
 
=Standard svn tree structure=
 
=== Directory Structure ===
 
=== Directory Structure ===
Line 48: Line 109:
 
==== branches ====
 
==== branches ====
 
* '''branches''' is the common directory for all team members' workspaces.  
 
* '''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 create within '''branches''' their own home directory or '''workspace''' (member-id1, member-id2,...) for their own tasks.  
−
* 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.
+
* 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'''.
+
*: ''These sub-directories (Task1, Task2,...) are called branches of trunk. The word '''branch''' used as a verb means copying the whole '''trunk''' into a sub-directory, within '''branches'''.
  
 
==== tags ====
 
==== tags ====
−
* '''tags''' is the directory that holds '''copies''' of successful stages of '''trunk''' throughout development. (''Also called as '''Milestones''''')
+
* '''tags''' is the directory that holds '''copies''' of successful stages of '''trunk''' throughout the development of the project. (''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''
 
* '''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 '''branch'''ing the trunk into '''tags''' is often referred to as a '''release'''.
+
*: The verb '''tag''' means copy the whole trunk into a sub-directory, in '''tags'''.
−
* We use the '''tags''' directory to submit the work for marking. ''Your instructor will specify the requirements of a release.
+
* The action of '''tag'''ing the trunk into '''tags''' is 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  
 
** 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.  
 
** When a release is due, your instructor will always mark the latest version of that release.  
Line 64: Line 126:
 
* '''trunk''' is the directory that holds the project in its current stage, '''complied and run-able'''
 
* '''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'''.
 
* '''trunk''' should never hold non-compiled code. Usually trunk is an exact copy (or better than) the latest version in '''tags'''.
−
* If the repository only contains one project, then trunk has no project level sub-directory and is the root of the project.  Ifthe repository holds  more than one project, trunk is divided into several sub-directories - one for each project.
+
* If the repository only contains one project, then trunk has no project level sub-directory and is the root of the project.  If the repository holds  more than one project, trunk is divided into several sub-directories - one for each project.
−
*: ''In this case, we divide '''tags''' into exactly the same project sub-directories as present in '''trunk'''''
+
*: ''In this case, we divide '''tags''' into exactly the same project sub-directories as in '''trunk'''''
 +
 
 +
=svn basic commands=
 +
A few important facts and terminology to clarify basic actions:
 +
* The purpose of a code repository is to track all of the modifications done to a project by its team members.
 +
**In a project tracked by a code repository (version-controlled, or in short, versioned), you can focus on any change 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 development stage.
 +
* SVN is a client/server repository;
 +
** Code resides on a server and members who have access can copy the whole or parts of the code to their local machines, work on the whole or parts and then apply their changes back to the server.
 +
** Because the code resides on a server, one member may be unaware of the changes made by another, unless the other has applied the changes to the server and the member has updated their local copy.
 +
** That is why timely and frequent communication amongst team members is vital to the project's success.  This is easily accomplished through the project wiki page (team page) and IRC
 +
* A code repository manages the merging of modifications of different members' code. When this fails, the repository will be in a conflict state.
 +
** Conflicts can be easily edited, saved, and resolved using the tools provided by SVN.
 +
* A '''version-controlled or versioned''' file is a file that is being tracked by a repository.
 +
<hr>
 +
* If the userid and password are not set to be saved in svn, then you need to add
 +
<big><pre>
 +
--username stdId --password stpassword
 +
</pre></big>
 +
: to the end if each svn command. (userid and password '''are''' set to be saved by default. Make sure to reboot your lab computer for the userid and password to be erased)
 +
 
 +
 
 +
 
 +
== checkout ==
 +
To '''checkout''' is to download the code from a repository server as a whole or partially to a versioned directory on the client, so that you can start working on the code.
 +
*GUI:
 +
# Create a directory on your local machine
 +
# Right click on the directory and select '''SVN Checkout'''
 +
# Enter the path of the repository or a sub-directory inside the repository and click OK
 +
# Enter userid and password if needed
 +
*Command Line:
 +
<big><pre>
 +
svn co svn://zenit.senecac.on.ca/repoid local_directory --username stdId --password stpassword
 +
OR
 +
svn checkout svn://zenit.senecac.on.ca/repoid local_directory --username stdId --password stpassword
 +
</pre></big>
 +
 
 +
== commit ==
 +
To '''commit''' is to submit the changes in the local files to the repository (on the server)
 +
* GUI
 +
# Right click on the directory or file that you wish to commit and click on '''SVN Commit''' 
 +
# In the Commit Dialog box enter a short description (a few words) explaining what you have modified and are committing and then click on OK.
 +
* Command Line
 +
<big><pre>svn commit locdir\branches\stdId\SomeDirectory
 +
-m "Added comments to foo() in faa.cpp and fee() in boo.h"</pre></big>
 +
OR
 +
<big><pre>svn commit locdir\branches\stdId\SomeDirectory\somefile.cpp
 +
-m "Added comments to foo() is somefile.cpp"</pre></big>
 +
'''''IMPORTANT: committing as often as you can makes you visible and shows that you are actively working on your project. When working on your branch, commit as often as you save your work, and comment your commits as much as you can. A consistent and regular number of commits per week is the best demonstration of your commitment to your project.'''''
 +
 
 +
== update ==
 +
To '''update''' is to download and apply the modifications made by others to the repository (on the server) to the local files on your own computer
 +
* GUI
 +
: Right click on the directory or file that you want to update and click on "SVN update"
 +
* Command Line
 +
: while in the local directory
 +
<big><pre>svn update</pre></big>
 +
: OR from anywhere
 +
<big><pre>svn update LocalDirectoryPath</pre></big>
 +
: OR for a single file
 +
<big><pre>svn update LocalDirectoryPath/somefile.whatever</pre></big>
 +
 
 +
== branch/tag ==
 +
To '''branch''' or to '''tag''' is to copy one directory into another on the server. The purpose of the copying dictates calling this action either a '''branch''' or a '''tag'''.
 +
*To '''branch''' is to '''copy''' into the '''branches''' directory or one of its sub-directories for further development
 +
*To '''tag''' is to '''copy''' into the '''tag''' directory as a release of the next stage of your project (also called a milestone)
 +
*GUI, Branching
 +
# Right click on '''trunk''' in your local repository files and under the "TortoiseSVN" sub-menu click on "Branch/tag"
 +
# Click on the button at right side of '''To URL''' to browse and find your '''workspace''' under '''branches''' directory (e.g. ''svn://zenit.senecac.on.ca/oop344_113repXX/branches/stdId'') and select that '''workspace'''.
 +
# Add the task name to the end of the selected path: ''svn://zenit.senecac.on.ca/oop344_113repXX/branches/stdId/'''nameOfTask'''''
 +
# In '''Log message''' type ''"Branching to do nameOfTask"''
 +
# Leave the rest of the options as they are and click on OK.
 +
#: This will make a copy of trunk within '''workspace/nameOfTask''' on the server.
 +
*GUI, Tagging
 +
# Right click on '''trunk''' in your local repository files and under the "TortoiseSVN" sub-menu click on "Branch/tag"
 +
# Click on the button at right side of '''To URL''' to browse and find your the '''tags''' directory (e.g. ''svn://zenit.senecac.on.ca/oop344_113repXX/tags'') and select that '''workspace'''.
 +
# Add the tag name (usually a release id like R0.6) to the end of the selected path: ''svn://zenit.senecac.on.ca/oop344_113repXX/tags/'''R0.X'''''
 +
# In '''Log message''' type ''"Tagging release whatever"''
 +
# Leave the rest of the options as they are and click on OK.
 +
#: This will make a copy of trunk within '''tags/R0.X''' on the server.
 +
* Command Line, Branching
 +
<big><pre>svn copy svn://zenit.senecac.on.ca/oop344_113repXX/trunk
 +
              svn://zenit.senecac.on.ca/oop344_113repXX/branches/stdId/nameOfTask
 +
              -m "Branching to work on nameOfTask"</pre></big>
 +
: This type of branching is called a [http://svnbook.red-bean.com/en/1.5/svn-book.html#svn.branchmerge.commonpatterns.feature Feature Branch]
 +
* Command Line, Tagging
 +
<big><pre>svn copy svn://zenit.senecac.on.ca/oop344_113repXX/trunk
 +
              svn://zenit.senecac.on.ca/oop344_113repXX/tags/R0.6
 +
              -m "R0.6 is released"</pre></big>
 +
'''''Note that branching or tagging occurs on the server.  Therefore to have this action applied to your local copy, you need to update your repository (for this see [[#update|Update]])
 +
 
 +
== merge ==
 +
To '''merge''' is to integrate the changes made in a branch in the '''branches''' directory back in the '''trunk''' directory.
 +
*GUI
 +
# First [[#update|Update]] the whole repository.
 +
# Right click on '''trunk''' and then in '''TortoiseSVN''' sub-menu click on '''merge'''
 +
# In merge options, select the second one that is '''Reintegrate a branch''' and click on next
 +
# In '''From Url''' browse and find the sub-directory under '''branches''' with your completed task and then click on Next. (e.g. svn://zenit.senecac.on.ca/oop344_113repXX/branches/stdId/nameOfTask)
 +
#: If browsing is not available you can use the '''repo browser''' to find the path to the sub-directory and copy and paste it.
 +
# Before merging you can click on test merge to run a simulation and see if the merge succeeds
 +
# Click on merge to merge the branch back into trunk.
 +
#: note that merging occurs on your local copy of the code and not in the repository on the server
 +
# Edit and resolve possible conflicts
 +
# Compile and test the merged trunk
 +
# Communicate with other team members to make sure that no one else is committing to trunk.
 +
# '''[[#commit|Commit]]''' your changes to trunk
 +
# Notify other team members that you have finished your commit!
 +
*Command line
 +
#Follow all the precautionary steps stated above and then:
 +
<big><pre>
 +
cd locdir
 +
svn update
 +
cd trunk
 +
svn merge --reintegrate
 +
    svn://zenit.senecac.on.ca/oop344_113repXX/branches/stdId/nameOfTask
 +
    -m "merging back nameOfTask to trunk"
 +
</pre></big>
 +
# Compile and test the trunk
 +
<big><pre>
 +
svn commit -m "committing work done on nameOfTask"
 +
</pre></big>
  
−
=Svn basic commands=
+
=Resources=
 +
== Demo ==
 +
* Here is a [http://www.youtube.com/watch?v=ANFTtpGSOgM video demonstration] for using svn, thanks to [[User:Tvirutthasalam|Thevakaran Virutthasalam]]
 +
== Links ==
 +
* [http://subversion.tigris.org/ Subversion (SVN)]
 +
* [http://subversion.apache.org/packages.html Subversion (SVN) Binary Packages]
 +
* [http://tortoisesvn.net/downloads Download Page of TortoiseSVN]
 +
* [http://tortoisesvn.net/docs/release/TortoiseSVN_en/index.html TortoiseSVN Documentation]
 +
* [http://svnbook.red-bean.com/ SVN book at red-bean.com] or download [https://cs.senecac.on.ca/~fardad.soleimanloo/oop344/notes/svn-book.pdf the PDF from here].
 +
* [http://www.rapidsvn.org/download/release/0.12/RapidSVN-0.12.0-8051.dmg RapidSVN] a SVN Client for Mac
 +
* [http://ankhsvn.open.collab.net/ AnkhSVN - Free Visual Studio SVN Integration Alternative To VisualSVN]

Latest revision as of 17:24, 15 February 2012

Work in progress, please help make this page more useful for students

What is svn?

svn (Subversion) is a source code repository. It can keep track of all the changes made (contributions) to a project by its developers. We use it to keep track of changes to our source code.

What svn can do for you?

svn can

  • Store your work (source code) safely on a remote server so you will never lose that work.
  • Let several students work on the same project at the same time.
  • Track the history of all the work done (who did what and when). This means that you can:
    undo your work to any past stage.
    look at different stages of the work and compare the changes.
    check other team members' work, their progress, and their contribution.
    ask others for help with your work and help others with their work.
  • Submit a paper-less assignment.
    Once you have tagged your work, your professor can
    1. checkout and evaluate your work
    2. mark your assignment fairly seeing each student's contribution.
    3. help you with your assignment by commenting and correcting your work remotely.

Common actions for school projects

Kick-start a project (project initiation)

  1. Create a directory to hold all of your team's work
  2. Checkout the entire repository into that directory
    Look and make sure that you have the 3 directories (branches, tags, trunk)
  3. Open the branches directory and create a sub-directory using your login name
    this becomes the root of your own (each students') workspace
    note: do not use the operating system's file management to copy, move, etc any of the versioned files
  4. Update the whole repo to see all of the changes from all team members
  5. Branch the trunk into a sub-dir of your workspace (name this sub-dir with your assigned task)
    the verb branch means copy (in the repository)

You are good to go - you can start working on your task

Start working on a project (start a new task)

  1. If you have not already branched trunk:
    branch/tag trunk into a sub-directory under your workspace. Use your task name/description so you can refer to it easily later.
  2. do your work within your branch/task directory and commit anytime you have something worth committing. Make sure that you comment each commit.
    Note that in your branch you can commit your work even if it is incomplete. In fact, commit your work anytime you are leaving your computer and comment it like: "going for lunch". But again you should only do this when you are working in YOUR OWN BRANCH
  3. When your task is complete
    1. Update the repository to apply all of the changes to your local copy
    2. Merge your changes back to trunk
    Note that, the merging happens on the local copy and not the repository
  4. Edit possible conflicts, save and mark them as resolved when done.
  5. Compile the trunk, test and make sure that the changes are what you want
  6. In trunk, apply more changes and do debugging if needed.
    note that this is the only time you should be doing any work in trunk
  7. When everything is perfect prepare to commit the trunk:
    1. Make sure that you are logged in to IRC.
    2. Go to team page and set trunk's status to committing with following info: User ID, email, IRC Nick, time and date
    3. If trunk's status is already committing by another user, communicate with them and find out when they are going to be done so you can do your commit.
      Never commit to trunk with out checking and setting the status of trunk in your team page
    4. Update the repository
  8. Commit the trunk
  9. Edit, save and resolve possible conflicts and go to previous step
  10. When done, go to the team page and set trunk's status back to committed with the same info as before.

Continue working on your current task on a new computer (public computer)

  1. Checkout only your branch/task
  2. Work on your task and keep committing the changes as you go.
  3. When done, do final commit, noting that the work period is done
  4. Delete the checked-out directory from the public computer.
  5. Reboot the computer
    this will remove your userid and password if you chose to save them.
    Note that you are responsible to keep you work safe. If someone gains access to your code and repository, YOU are responsible for it and its consequences.

Continue working on your task (everyday work)

  1. Update the repository to get the most recent changes.
  2. (optional and only if needed:) If trunk is updated by someone else since the time you branched it, you can merge the updated trunk into your branch to get the latest additions and modifications of trunk in your branch.
  3. Continue working on your task and keep committing often.
  4. when done for the time being, commit your work and comment, noting the stage of your work.

Release your completed task (submit an assignment or a release)

  1. Do this when a major task is finished and it is time to present it to your professor.
    This is not necessarily to hand in a new release. It could be at any time you feel you are one step closer to the end of the project.
  2. Update and make sure the trunk has the latest modifications.
  3. Do all possible changes and fixes to make this release final.
  4. Tag (branch) the trunk into a sub-directory in tags.
    Name the tagged directory relative to its state (i.e. name it R0.4 and comment it with task name Text Editor)
    If this is a fix to a previously released trunk, add the release revision after the release number: (i.e R0.41 and comment it as Fixed backspace bug in Text Editor)
  5. Your prof will later update the repo on their computer and get your Release.

Standard svn tree structure

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 within branches their own home directory or workspace (member-id1, member-id2,...) for their own tasks.
  • 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. The word branch used as a verb means copying the whole trunk into a sub-directory, within branches.

tags

  • tags is the directory that holds copies of successful stages of trunk throughout the development of the project. (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 verb tag means copy the whole trunk into a sub-directory, in tags.
  • The action of taging the trunk into tags is 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 the repository only contains one project, then trunk has no project level sub-directory and is the root of the project. If the repository holds more than one project, trunk is divided into several sub-directories - one for each project.
    In this case, we divide tags into exactly the same project sub-directories as in trunk

svn basic commands

A few important facts and terminology to clarify basic actions:

  • The purpose of a code repository is to track all of the modifications done to a project by its team members.
    • In a project tracked by a code repository (version-controlled, or in short, versioned), you can focus on any change 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 development stage.
  • SVN is a client/server repository;
    • Code resides on a server and members who have access can copy the whole or parts of the code to their local machines, work on the whole or parts and then apply their changes back to the server.
    • Because the code resides on a server, one member may be unaware of the changes made by another, unless the other has applied the changes to the server and the member has updated their local copy.
    • That is why timely and frequent communication amongst team members is vital to the project's success. This is easily accomplished through the project wiki page (team page) and IRC
  • A code repository manages the merging of modifications of different members' code. When this fails, the repository will be in a conflict state.
    • Conflicts can be easily edited, saved, and resolved using the tools provided by SVN.
  • A version-controlled or versioned file is a file that is being tracked by a repository.
  • If the userid and password are not set to be saved in svn, then you need to add
 --username stdId --password stpassword
to the end if each svn command. (userid and password are set to be saved by default. Make sure to reboot your lab computer for the userid and password to be erased)


checkout

To checkout is to download the code from a repository server as a whole or partially to a versioned directory on the client, so that you can start working on the code.

  • GUI:
  1. Create a directory on your local machine
  2. Right click on the directory and select SVN Checkout
  3. Enter the path of the repository or a sub-directory inside the repository and click OK
  4. Enter userid and password if needed
  • Command Line:
svn co svn://zenit.senecac.on.ca/repoid local_directory --username stdId --password stpassword
OR
svn checkout svn://zenit.senecac.on.ca/repoid local_directory --username stdId --password stpassword

commit

To commit is to submit the changes in the local files to the repository (on the server)

  • GUI
  1. Right click on the directory or file that you wish to commit and click on SVN Commit
  2. In the Commit Dialog box enter a short description (a few words) explaining what you have modified and are committing and then click on OK.
  • Command Line
svn commit locdir\branches\stdId\SomeDirectory 
 -m "Added comments to foo() in faa.cpp and fee() in boo.h"

OR 

svn commit locdir\branches\stdId\SomeDirectory\somefile.cpp
 -m "Added comments to foo() is somefile.cpp"

IMPORTANT: committing as often as you can makes you visible and shows that you are actively working on your project. When working on your branch, commit as often as you save your work, and comment your commits as much as you can. A consistent and regular number of commits per week is the best demonstration of your commitment to your project.

update

To update is to download and apply the modifications made by others to the repository (on the server) to the local files on your own computer

  • GUI
Right click on the directory or file that you want to update and click on "SVN update"
  • Command Line
while in the local directory 
svn update
OR from anywhere
svn update LocalDirectoryPath
OR for a single file
svn update LocalDirectoryPath/somefile.whatever

branch/tag

To branch or to tag is to copy one directory into another on the server. The purpose of the copying dictates calling this action either a branch or a tag.

  • To branch is to copy into the branches directory or one of its sub-directories for further development
  • To tag is to copy into the tag directory as a release of the next stage of your project (also called a milestone)
  • GUI, Branching
  1. Right click on trunk in your local repository files and under the "TortoiseSVN" sub-menu click on "Branch/tag"
  2. Click on the button at right side of To URL to browse and find your workspace under branches directory (e.g. svn://zenit.senecac.on.ca/oop344_113repXX/branches/stdId) and select that workspace.
  3. Add the task name to the end of the selected path: svn://zenit.senecac.on.ca/oop344_113repXX/branches/stdId/nameOfTask
  4. In Log message type "Branching to do nameOfTask"
  5. Leave the rest of the options as they are and click on OK.
    This will make a copy of trunk within workspace/nameOfTask on the server.
  • GUI, Tagging
  1. Right click on trunk in your local repository files and under the "TortoiseSVN" sub-menu click on "Branch/tag"
  2. Click on the button at right side of To URL to browse and find your the tags directory (e.g. svn://zenit.senecac.on.ca/oop344_113repXX/tags) and select that workspace.
  3. Add the tag name (usually a release id like R0.6) to the end of the selected path: svn://zenit.senecac.on.ca/oop344_113repXX/tags/R0.X
  4. In Log message type "Tagging release whatever"
  5. Leave the rest of the options as they are and click on OK.
    This will make a copy of trunk within tags/R0.X on the server.
  • Command Line, Branching
svn copy svn://zenit.senecac.on.ca/oop344_113repXX/trunk 
              svn://zenit.senecac.on.ca/oop344_113repXX/branches/stdId/nameOfTask 
              -m "Branching to work on nameOfTask"
This type of branching is called a Feature Branch
  • Command Line, Tagging
svn copy svn://zenit.senecac.on.ca/oop344_113repXX/trunk 
              svn://zenit.senecac.on.ca/oop344_113repXX/tags/R0.6 
              -m "R0.6 is released"

Note that branching or tagging occurs on the server. Therefore to have this action applied to your local copy, you need to update your repository (for this see Update)

merge

To merge is to integrate the changes made in a branch in the branches directory back in the trunk directory.

  • GUI
  1. First Update the whole repository.
  2. Right click on trunk and then in TortoiseSVN sub-menu click on merge
  3. In merge options, select the second one that is Reintegrate a branch and click on next
  4. In From Url browse and find the sub-directory under branches with your completed task and then click on Next. (e.g. svn://zenit.senecac.on.ca/oop344_113repXX/branches/stdId/nameOfTask)
    If browsing is not available you can use the repo browser to find the path to the sub-directory and copy and paste it.
  5. Before merging you can click on test merge to run a simulation and see if the merge succeeds
  6. Click on merge to merge the branch back into trunk.
    note that merging occurs on your local copy of the code and not in the repository on the server
  7. Edit and resolve possible conflicts
  8. Compile and test the merged trunk
  9. Communicate with other team members to make sure that no one else is committing to trunk.
  10. Commit your changes to trunk
  11. Notify other team members that you have finished your commit!
  • Command line
  1. Follow all the precautionary steps stated above and then:
cd locdir
svn update 
cd trunk
svn merge --reintegrate 
    svn://zenit.senecac.on.ca/oop344_113repXX/branches/stdId/nameOfTask 
    -m "merging back nameOfTask to trunk"
  1. Compile and test the trunk
svn commit -m "committing work done on nameOfTask"

Resources

Demo

Links

Retrieved from "https://wiki.cdot.senecapolytechnic.ca/w/index.php?title=SVN_for_School_Projects&oldid=81524"