Howto create private branches

The /sandbox in subversion is no longer available for private branches. You can still create private branches on your workstation using svk, git, or mercurial. This page explains the basic of local private branches and will concentrate on svk as it will be the most familiar to subversion users.

SVK and local private branches

SVK is a distributed version control system which uses subversion as the backend version control system. SVK for Windows can be downloaded here. Distributed version control systems maintain a copy of the "trunk" on each developer's machine and branches are created and stored on the developer's machine. A branch can be published or pushed to other machines in order to make the branch public. Opticks continues to use a centralized version control system, but a distributed version control system can be used to create private sandbox branches from the centralized subversion repository.

Since SVK is based on and is a super set of subversion its learning curve is relatively shallow for experienced subversion users. In fact, existing subversion tools such as TortoiseSVN can be used to interact with a local sandbox branch once the branch has been created.

Creating a local mirror

The first step required to create local sandbox branches is to establish an SVK mirror or a subversion repository. This step only needs to occur once.

1. Initialize the local SVK repository which is called a depot. The first command initializes the default depot in %HOME%. If you would rather store the default depot elsewhere, use the second set of commands.

   svk depotmap --init

   svk depotmap --init
   svk depotmap --detach //
   svk depotmap --init // c:\.svk\local

2. Establish a mirror. There commands snapshot the latest trunk revision. If you would like to mirror the entire history of the trunk, omit the --skipto HEAD option.

   svk mirror https://opticks.ballforge.net/svn/opticks/trunk/future //mirrors/opticks/future
   svk sync --skipto HEAD //mirrors/opticks/future

Updating the mirror

You'll need to manually update the trunk mirror to grab the latest changes. You can easily grab the updates for all mirrored repositories with the following command.

Creating a local sandbox branch

The commands to create a local branch are similar to the subversion command to create a branch.

Working with a local branch

You can use the svk command line client to interact with the local branch in much the same way you would use the subversion command line client.

SVK uses subversion for storage of local branches, you can use TortoiseSVN and other subversion tools to work with a local branch. SVK stores special merge tracking information in subversion properties so you should always interact with mirrors using the SVK command line client. This includes updating mirrors, creating local branches, and merging between branches and mirrors. Checkout, update, and commit to local branches as well as log history and repository browsing can happen with any subversion client.

1. Find the location of the SVK depot using svk depotmap -l
2. Point your subversion tool at the path returned. You will need to append the top level repository path to the location. The branch made above can be accessed using file:///C:/.svk/local/sandbox/opticks/future/MyBranchName. You will need to use a subversion client version which is compatible with the subversion libraries used by SVK. This information can be found by running svk -v and is 1.5.0 as of the writing of this document.

Merging in changes from the trunk

When a trunk update occurs, you can push the changes to your local branches using the SVK star merge command.

Generating a patch with changes from the local branch

If you want to submit a patch for changes made to a local branch, you use SVK to merge the changes back into the trunk but set the target as a patch file.

There are many more things you can do with local branches including automatically pushing changes from a local branch to a newly created "official" subversion branch. These techniques are beyond the scope of the document. If there is enough desire, advanced howtos can be created.

Git

Alternately, you can create local branches using the distributed version control system git. This section will describe some of the common tasks needed when working with Opticks local branches. Alternately, we've setup a git mirror on github. You can find out more information at the Github source code mirrors page. Further information on git is available in many places including:

• Everyday git commands
• The git-svn command
• The git crash course for subversion users
• git-svn in 30 minutes

Creating a local mirror

The first step required to create local sandbox branches is to establish a bi-directional mirror or a subversion repository in git. Git does not differentiate between repositories and working copies. Initializing a mirror in git is called cloning.

1. Initialize a git repository. The first command mirrors the entire repository. This can take a long time but provides you with a local copy of the repository history. If you would like to quickly clone the head of the repository only, find out the head revision number and use the second command replacing 1234 with the head revision.

   git svn clone https://opticks.ballforge.net/svn/opticks --prefix svn/ -T trunk/future -b branches/future/*

   git svn clone -r 1234:HEAD https://opticks.ballforge.net/svn/opticks --prefix svn/ -T trunk/future -b branches/future/*

2. List the subversion branches which are available.

   git branch -r

You will usually want to maintain the list of ignored files stored in the svn:ignore property. You can copy this list to git with the following command.

Updating the mirror

You'll need to manually update the trunk mirror to grab the latest changes. You can easily grab the updates for all mirrored repositories with the following command in the git repository.

If there are merge problems, run the following command to manually merge a file. Then continue the merge.

You can skip the change that caused the conflict.

You can cancel the merge.

Creating a local sandbox branch

You can work directly on the main branch. When you commit changes, they are only stored in the local repository until you push them up to subversion. If you want to create a separate local branch. The same command switches to an existing branch.

If you have uncommitted changes which you would like to keep but do not want to commit even to the local repository, you can stash them and reapply them at a later time.

Working with a local branch

Many of the commands for working with branches are similar to subversion. More information is available in the links above.

Pushing changes back to subversion

You can push changes from a local repository to subversion using the dcommit command. Currently, you must push changes to a subversion branch and not directly to the subversion trunk do to Opticks development policy so make sure you have applied your changes to a remote branch. The following commands will push the changes to a subversion branch including the command to switch to the branch.

Generating a patch with changes from the local branch

You can generate patches in a variety of formats. A standard git patch can be generated with this command and applied to another git repository or branch.

If you need a standard unified diff, use this command. The generated patch can be applied with the standard patch command.

Switching to a different development line

If your git repository has been mirroring one development line (future for example) and you would like to switch to a different line (4.3.X for example), you can do the following (where GITHOME is the top of the git repository). This is not a common procedure and it is often recommended to create a new git repository for the new development line.

Mercurial

Mercurial is another distributed version control systems which can be used to create local sandbox branches. This document does not describe how to use mercurial but there are tutorials available on the web. Search for information on mirroring subversion using mercurial if you would like more information.