Subversion Installation and Operation with Windows® in the MPLAB® X IDE

How to Install TortoiseSVN

TortoiseSVN is a GUI interface that interacts with the subversion client and reduces the need for command line operation. TortoiseSVN also manipulates your icons for folders and files to show the file's state of control.

1. Download TortoiseSVN.

   ​TortoiseSVN only supports Windows^® OS.

2. Run the setup (*.msi) file. For best results use the default selections for install options.
    
3. Restart your computer after the installation is completed.

Back to top

Creating a Repository

This process describes creating a local repository, not a subversion server repository.

1. After you have successfully installed Subversion and Tortoise SVN, browse to the location you would like to keep your repository. This location can be on your local computer or a shared network drive that you have folder access to with read and write privileges.
2. Create a folder for your repository and name it (e.g., C://svn_repository).
3. Right-click on the folder you created and select '<TortoiseSVN/Create Repository Here>'.​

   This creates the file structure for use by SVN to track revisions, do not modify the file contents or folder structure unless you are familiar with how Subversion uses them.

4. Browse the repository by right-clicking on the repository and select '<TortoiseSVN/Repo-Browser>'. TortoiseSVN will remember the file path for future use.

​

Back to top

Repository Folder Structure

You are free to choose any file structure you wish to use. The file structure in the accompanying image is a commonly used structure that clearly differentiates the separate pieces of the development process of a project. The following image shows the standard file structure viewed using the TortoiseSVN Repo-Browser.

As you can see each project has its own set of folders for the branches, tags, and trunk. If your team performs many different types of development (e.g., CAD, hardware layout, firmware development, software development, white papers, application notes, etc.) you can create folders for each type of development that your projects reside in or you can create a completely separate repository for each development area.
Back to top

Using Subversion and TortoiseSVN

The following are common Subversion operations used while maintaining a project under version control. All examples assume you are using a local repository and the typical folder structure from above and will be demonstrated using TortoiseSVN. Refer to the Subversion manual for command line options or more advanced topics.

Creating the Folder Structure for a New Project

The following steps demonstrate how to create the typical folder structure in a repository for use with a single project.

1. Open the TortoiseSVN Repo-Browser by right-clicking on the repository folder and selecting '<TortoiseSVN / Repo-Browser>'.
2. Enter the URL for the repository in the URL text box.

   You can also navigate to the repository folder in Windows, right click on the repository folder, and select '<TortoiseSVN / Repo-Browser>', and it auto-populates the URL text box.

3. Create and name a new folder for the project in an appropriate directory by right-clicking and selecting 'Create Folder'.
4. Continue creating and naming folders for the trunk, tags, and branches.

Back to top

Checking Out a Project

Once you have a folder in the repository for your project you need to check it out to a local folder on your computer. This associates the local folder and the folder in the repository.

1. From the TortoiseSVN Repo-Browser, right click on the trunk/tag/branch folder inside of the project you wish to check out and select 'Check Out'.
2. In the checkout window that opens, browse for the location that you wish to check the project out to. You may need to create a new folder for the project. You also have options for checkout depth and if you want to check out the head or any previous revision.
3. Click OK.
   • If the local project folder already has contents, you get a warning that the folder is not empty. If you wish to include the contents in your project, click OK. Otherwise, you need to move the contents of the folder to another location.
   • You should now have a project folder to start a project in. You may notice a hidden folder called .svn. Do not delete or modify this folder, it contains information needed to work with the Subversion client.

Back to top

Adding Files to Subversion Control

Once you have files in your project you need to add them to version control. Initially, the Subversion client does not know which files are being managed and which files are being ignored. You do not need to add all files in a project to version control. Some files may contain local settings that all collaborators on a project may not need or there may be intermediary files that are not necessary to manage.

1. Locate a file or group of files you would like to add to version control, right click on the file(s),
   select '<TortoiseSVN/Add>'.
   This step tells the Subversion to manage the file but has not yet sent the file to the repository.
2. Notice that the file now has a '+' icon overlay indicating that it has been added to version control but has not yet been committed. Also notice that the project folder now has a red exclamation mark indicating that there has been a change inside of the folder that has not yet been committed to the server. You can either commit the entire project or the individual file by right-clicking on the file(s) or project folder and selecting '<SVN Commit…>'.
3. In the dialog box that pops up, you can add comments regarding the commit event.
   Click OK.
   The file(s) or project folder changes will be sent to the server and the repository revision will be incremented.

Back to top

Updating Changes to a Project

When other developers make changes to files and commit them to the server, they may contain changes that you need to work with. So you need to perform an update to pull in the changes.

1. Right click on the local project folder and select 'SVN Update…'.
2. A new window will pop up indicating the progress and actions performed during the update process. It is recommended to review these notes.
3. Click OK to close the dialog box.

Back to top

Committing Changes to a Project

After you have made changes to files or added files to your project you need to commit the changes to the server.

1. Right click on the local project folder and
   select '<SVN Commit…>'.
2. If desired, add comments relating to the latest commit in the window that pops up.
3. Review the 'Changes Made' section to make sure all necessary files are included in the commit.
   Click OK.
4. Review the status window to make sure there were not any errors.
   Click OK.

Back to top

Creating a Tag

Once your project is ready to create a test, alpha, beta, or release version, you may want to create a snapshot or tag of the project in its current state.

1. Right click on the local folder that contains the project you wish to create a tag of and select '<TortoiseSVN/Branch/Tag…>'.
2. Navigate the 'To URL' to a location in the repository, preferably in the Tags folder of the project directory.

   Do not manually create a folder for Tag, manually append the name of the tag folder to the URL.

3. Select the source used for the tag, HEAD version, specific version, or working copy. Enter a message describing the tag. You also have the option to switch your working folder contents to the tag you created. However, this is not typical in a tag operation.
4. Select OK.

Back to top

Creating a Branch

Occasionally, you may want to work on a new feature or test a new concept but don't want to disrupt the main project. To do this you can create a branch of the project or select files.

1. Right click on the local folder that contains the project you wish to create a branch of and select '<TortoiseSVN/Branch/Tag…>'
2. Navigate the 'To URL' to a location in the repository, preferably in the Branches folder of the project directory. Do not manually create a folder for Branch, manually append the name of the branch folder to the URL.
3. Select the source used for the branch, HEAD version, specific version, or working copy. Enter a message describing the branch. You also have the option to switch your working folder contents to the branch you created. This is done so that any changes you make will not affect the trunk.
4. Select OK

Back to top

Reverting File Changes

If you make a change to a file or a project and you have not committed the changes you can revert back to last committed version of the file.
Warning. Any changes made to the file since the last commit will be lost during the revert operation.

1. Right click on the local folder or file that you want to revert back to the last committed state.
2. Select 'Revert'.

Back to top

Switching Projects

When you are working on the trunk, tag, or branch of a project you may need to switch to a different form of the project. This is done through the switch command. Be sure to commit any changes you have made.

1. Right click on the local folder or file that you want to switch to another version and click 'Switch'.
2. Browse to the location of the folder of the file that you want to switch to.
3. Select whether you want to switch to the HEAD revision or a specific version.
4. Select OK.

Back to top