Purpose of this post:
To demonstrate how and why to branch a project under Subversion Source Control. The documentation provided with TortoiseSVN, while extensive, is confusing and vague. Many of the actions described both in the documentation and in the TortoiseSVN GUI are not clear whether they are acting on the local drive or on the server. The terminology is inconsistent. This post makes it clear.
Programmers new or somewhat new to Subversion Version Control System.
Target Platform and Tools:
This will be on a Windows client platform (server platform is not relevant to this discussion) using the TortoiseSVN Windows Shell extension (It adds a right-click menu to folders in Windows Explorer).
Expectations of the reader:
It’s assumed that the reader:
- has already downloaded and installed TortoiseSVN.
- has access to a Subversion server.
- Can perform basic operations on Subversion with TortoiseSVN.
- understands the basic concepts of version or source control (repository, check in (commit), check out (update), etc…)
- is a programmer or system administrator.
- is reading this post to learn how to perform a branch operation on a Windows client with TortoiseSVN to a Subversion server.
- has a folder somewhere on their hard drive with source files in it that are already being controlled by Subversion.
What this post does NOT do:
- Teach you about the basics of version control (or source control).
- Teach you how to install any components of any software.
- anything other than provide what you need to know to perform a branch operation.
- talk about any particular programming language.
- try to convince you that Subversion is better or worse than any other version control system.
What is “Branching”?
Branching is when you have a project in a version control system and you want to split off (or clone) a copy of it and work with that copy, making changes (commits) to it over time. At some later point, you may (or may not) decide to merge those changes back into the main (trunk or head) project.
Part of the “Best Practices” of Subversion usage is to always create a branch when you start working on a new feature or version of a product. When you’re done, you then merge your branched copy back into the main copy, then delete your branch.
How to branch:
- Make sure your server project has a trunk folder and a branches folder.
- Starting with your local copy, commit (takes your local changes and uploads them to the server) all of your changes now (It’s important that your local copy and your server copy are both up to date). This local copy should be linked to your trunk folder (or whatever server folder you want to branch from).
- Now, do an “update” (which gets the latest version from the server).
- Right-click your local folder, choose “TortoiseSVN”, then “Branch/Tag”
- In the “To URL” text box, you should see the current server folder that your local folder is linked to. Change it to the new (yet to exist) branch folder you want your branched copy to exist in on the server. In other words, in that text box, delete the work “trunk” and type the word “branches/” then the name of the branched copy. This will cause a new folder to be created in the server repository under the “branches” folder.
- In the lower left, check the box “Switch working copy to new branch/tag”. This will cause your local folder that you’re working from to be unlinked from the trunk folder from the server and then linked to the new branched copy on the server. All future commits will go to the branched copy on the server and all updates to that local copy will come from the branched folder on the server.
- Click “OK”.
You will now have a new subfolder on the server repository under your branches folder on the server. Your local copy is no longer linked to your server’s trunk folder. It’s now linked to your newly created subfolder in the repository under the branches folder on the server.
If you now make changes to your local copy, then commit, your changes will be submitted to your branched copy on the server. The trunk folder on the server will not receive your commits. Further, any updates (downloading from the server) will come from your newly created folder on the server under the server’s branches folder.
Related articles (articles that aren’t links have not yet been written):
- Subversion Merge: Merging your working branch back into the trunk.
- Subversion: Linking a local folder to a Subversion folder on the server.
- Subversion: Unlinking a local folder from a Subversion folder on the server.
- Subversion: Checking out.
- Subversion: Checking in.