Skip to main content

Branching and merging in Subversion

This is a guide about working with branches in the Apache® Subversion® version control system (also known as SVN). It aims to provide the reader with a good understanding of how to create, use and merge branches in Subversion. Importantly, it also warns you about common mistakes and describes best practices.

Using branches in Subversion​

Modern Subversion is well-suited for workflows that involve branching and merging.

Despite that, there is a misconception that Subversion is not suitable for working with branches. This misconception stems from the fact that early Subversion releases (particularly those before Subversion 1.5, released in 2008) lacked the functionality for the convenient merging of branches. It also stems from the fact that the branching and merging operations in Subversion are a bit different, compared to other popular version control systems, such as Git. Commands in Subversion provide a lot of flexibility, but this flexibility comes at a cost: Subversion commands can be misused.

Intended audience​

This guide assumes that you are already familiar with the very basics of Subversion: checking out a working copy, making changes in the working copy, updating the working copy, and committing.

If you are not yet familiar with that, please see Chapter 2: Basic Usage in the book Version Control with Subversion. At the bare minimum, you’ll need to be familiar with the sections titled Creating a Working Copy and Basic Work Cycle. Note that the Trunk-based development workflow described in this guide is essentially the same workflow as the Basic Work Cycle. It is included in this guide to allow for convenient comparison between the basic work cycle and the feature branch workflow.

This guide does not assume prior experience with using branches in Subversion.

How to use this guide​

The Basic concepts chapter provides some terminology and prerequisite knowledge that you may find helpful to fully grasp the rest of this guide.

In the Workflows chapter, the Feature branch workflow page describes the standard workflow for creating, using and merging branches. Where relevant in that workflow, the steps list and point you to the associated best practices.

The Best practices chapter contains just the best practices grouped into several categories. You can refer to that chapter directly, if you are already familiar with the standard workflows and just want to make sure that you avoid common mistakes.

Additionally, the pages in the Handling conflicts chapter (such as Resolving a text conflict) describe how you can resolve conflicts.

Examples used in this guide​

For demonstration purposes, this guide primarily uses the official command-line Subversion client called svn, which is available for most operating systems.

Additionally, the Best practices chapter explains how the same practices apply both on the command line and when using TortoiseSVN, a popular open-source GUI-based Subversion client available on Windows.

All examples of svn commands in this guide assume that these commands are run at the Windows Command Prompt (cmd.exe). Before each command, the prompt text (e.g. C:\Users\Alex\my_work_dir>) is included in the examples, to show the current directory in which the command is run.

The same svn commands should also work on other operating systems, such as on Unix-like operating systems like macOS or Linux. The input and output of svn commands on a Unix-like OS is identical to what is shown in this guide, with only minor exceptions. For example, a Unix-like command shell uses forward slashes (/) as separators not only in URLs, but also in local (e.g. working copy) paths.