As I’m beginning to talk to people about the SVK version control tool more, I’m noticing that the concept of mirroring isn’t as obvious to some people as it was to me when I started messing around with it (or maybe I just choose not to remember how unobvious it was), so I thought I would take some time to try to explain some of the concepts at an extremely high (and hopefully easier to understand) level.
Sometimes the best way to explain a concept is with a picture, so I threw together this small data flow diagram that shows the flow of data through the SVK system and what commands cause this data transfer to happen.
The basic high level workflow of an SVK session looks like this:
- Create A Mirror
You mirror the repository using the svk mirror command. For me, I find it easiest to create my mirrors at the topmost level (for example, a mirror of the bieberlabs trunk might be at //bieberlabs/trunk).
- Synchronize Your Mirror
This brings down the revisions that you do not have yet in your main (and remote) repository to your newly established mirrored path.
- Create a Local Branch To Do Your Work
Many times I see that people default to checking out from the actual mirror (in the above example, //bieberlabs/trunk). This will work, but you lose the whole beneifit of SVK. If you check out of a mirror, every commit you make will be synchronized back to the main repository. This is not desired behavior most of the time. So, create a local branch first. I like to create a top level directory in the repository called //local that I put my local branches in, just so I know where to find them.
- Periodically synchronize your mirror and merge those changes into your local branch
This is where all of the power is. You now have a local branch that you can keep completely up to date with the repository that others are doing work in. Using the svk smerge command, you can merge changes from //bieberlabs//trunk to //local/mychange as you synchronize your mirror. This allows you to always be working on the current code. You can commit your work and not effect anyone else working in the repository until you are ready to merge into the mirror.
- Once you have merged changes to your local branch, update your workarea
A common misunderstanding when you smerge into your local branch is that the changes appear magically in your workarea. This is not the case. Remember, when you are smerging you are working in the repository. You still have to update your workarea (and possibly resolve conflicts) from the repository in order to reflect your changes.
- Merge your branch back into the mirror
Once you have finished your change, tested and committed (probably multiple times), you can now smerge your branch back into the mirror. When you perform this merge, the changes will be moved to the source repository and subsequently synced to your mirror (the line in the diagram is red to signify this). Once this happens, all of your changes are visible to everyone else, in one commit.
Here’s the nice thing about working like this. When merging back and forth, you are not searching for ranges of revision numbers to merge. SVK remembers each merge done, so you can use your local branch forever, because you can constantly keep it up to date. This gets rid of the “make a branch, change the branch, merge the branch , delete the branch” cycle and allows you to have one place to work all of the time.
I hope that this really high level view gives a better understanding of the workflow surrounding using SVK and illustrates very simply the advantages of the tool.
For a step by step walk through the tool, you can go through the SVK tutorials.
What about svk push and svk pull? These commands seem to be easier to run than svk smerge all the time.
Yes they are. I have only recently started playing around with these commands. I usually spend time learning the more complex things first. Then I explore the easier commands and comment on how hard things used to be … 😉
Pingback: Somewhere out there! »
Pingback: SVK Tutorials
Are you sure your diagram is correct about how local changes are merged back to the repository? From what I understand of it they are not sent to your mirror first and then sent to the remote repository but sent from the local branch to the remote repository and then synced back the the mirror. So all changes to the mirror come from the original repository.
You are correct – and it is stated that way in the third part of the SVK tutorial. I guess I mucked up the diagram as I was explaining it.
I’ll take some time to reflect this in the diagram soon.
Thanks for the heads up on the mistake!
Finally updated the image to reflect Sams input.
Hi Ron, just wanted to say I’ve recently found your pages on SVK and they are great documentation. I see that you changed the diagram to reflect Sam’s input about how the local changes are merged back into the repo, but does your text relating to also need to change? It still states: “When you perform this merge, the changes will be moved to the mirror and automagically committed to the source repository of the mirror (the line in the diagram is red to signify this).” The diagram now seems to reflect what Sam mentioned, in which the local changes are merged into the source repo first, and then the mirror gets sync’d to that? I just want to make sure I’ve got all this correct in the way that I understand it, thanks!
Also, just to put useful information together in the same place, I found this pdf file that has a visual of the svk process in another fashion that helps support what is talked about here:
Yup, missed that one. Thanks. The change has been made.