MPLAB X does not currently support Subversion v1.7. Please use Subversion v1.5. Version 1.7 support will be added in a future release of MPLAB X.
Table of Contents
Subversion TerminologyThe following is a list of commonly used terminology used when working with Subversion. Please refer the the Subversion Book (svn-book.pdf) for more terminology.
- Subversion Client
- Software run by a user to access a Subversion repository locally or on a Subversion server.
- Subversion Repository
- Location where project files are stored. Contains the most recent version as well as past versions of the project.
- Project Tree
- A single project tree contains folders for project management and version control. Typical folders are: trunk, branches, tags. These folders are used to keep the working copy, development copy, and code releases or snapshots.
- Contains of the main project source for team development. Consist of code that can compile, even if it contains stubs for undeveloped code.
- Split from the main trunk to allow for development. Branches allow development without disrupting the trunk. Branches can remain a separate development path or can be merged back to the trunk later in time.
- Snapshot of project at an important point of time. Typically a software release version.
- Stored change in a file's state. Revisions are incremented during the commit process where changes are saved.
- Latest revision of all project files in the project trunk, branch, or tag.
- Working Copy
- Local copy of a projects source code checked out from the repository.
- Creates a local working copy for development, testing, or release. Can be the project head, a specific revision, or a tag of the project.
- Merges any changes that have been made in the repository into the local working copy.
- Checking in or writing any project changes from the local copy to the repository.
- Process of changing a file back to a previous version of itself. Can be used to resolve conflicts.
- Process of combining the changes made in a working copy of a file in a project to the repository that contains a more recent revision of the same file than what was checked out before modifying it. Typically used in when multiple developers are working on the same file to avoid loosing other developers changes.
- Occurs when changes are made by different developers to the same file and the repository system is unable to reconcile the changes. Typically requires the files to be merged manually to resolve the conflict.
How to Install Subversion Client
The Subversion client contains the commands to interface with local and server repositories.
Subversion supports wide variety of operating systems. Be sure to download the installer for your operating system. We will reference the Collabnet client download for Windows.
Run the setup.exe file. For best results use the default selections for install options.
You may need to restart your computer after installation is completed.
How to Install Tortoise SVN
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.
TortoiseSVN only supports Windows OS.
Run the setup (*.msi) file. For best results use the default selections for install options.
You will need to restart your computer after installation is completed.
Creating a Repository
This process describes creating a local repository, not a subversion server repository
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.
Create a folder for your repository and name it. (Ex. C://svn_repository)
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.
Browse the repository by right clicking on the repository and select <TortoiseSVN/Repo-Browser>
* TortoiseSVN will remember the file path for future use.
- Now you can create new folders for projects, checkout revisions of files or projects, and manage your repository via TortoiseSVN.
Repository Folder StructureYou are free to choose any file structure you wish to use. The file structure below 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 (ex. 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.
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 will demonstrate how to create the typical folder structure in a repository for use with a single project.
Open the TortoiseSVN Repo-Browser by right clicking on the repository folder and selecting <TortoiseSVN / Repo-Browser>.
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 will auto populate the URL text box.
Create and name a new folder for the project in an appropriate directory by right clicking and selecting "Create Folder".
Continue creating and naming folders for the trunk, tags, and branches.
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.
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".
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.
- If the local project folder already has contents you will get a warning that the folder is not empty, if you wish to include the contents in your project, click OK. Otherwise you will need to move the contents of the folder to another location.
- You will 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.
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 managing and which files are being ignoring. 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.
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.
You will notice that the file now has a '+' icon overlay indicating that it has been added to version control but has not yet been committed. You will 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…>.
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.
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.
Right click on the local project folder and select "SVN Update…"
A new window will pop up indicating the progress and actions performed during the update process. It is recommended to review these notes.
Click "OK" to close the dialog box.
- Occasionally there are situations where you have made changes to a file that another developer has made a change to and committed to the server. Subversion has diff and merge tools built in that help with merging the two resources together. This will be discussed later in another topic.
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.
Right click on the local project folder and select <SVN Commit…>
If desired, add comments relating to the latest commit in the window that pops up.
Review the "Changes Made" section to make sure all necessary files are included in the commit. Click "OK"
Review the status window to make sure there were not any errors. Click "OK"
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.
Right click on the local folder that contains the project you wish to create a tag of and select <TortoiseSVN/Branch/Tag…>
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 the Tag, manually append the name of the tag folder to the URL.
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.
Creating a Branch
Occasionally you may want to work on a new feature or test a new concept but you don't want to disrupt the main project. To do this you can create a branch of the project or select files.
Right click on the local folder that contains the project you wish to create a branch of and select <TortoiseSVN/Branch/Tag…>
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 the Branch, manually append the name of the branch folder to the URL.
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 effect the trunk.
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.
Right click on the local folder or file that you want to revert back to the last committed state.
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.
Right click on the local folder or file that you want to switch to another version and click Switch.
Browse to the location of the folder of file that you want to switch to.
Select whether you want to switch to the HEAD revision or a specific version.
MPLAB X Subversion Features
MPLAB X integrates the ability to perform many essential Subversion tasks directly from the IDE. This allows developers to work with their version control system quickly and easily.