Bazaar for Visual SourceSafe users

VSS <-> Bazaar Dictionary

VSS is rather different in terminology to most other version control systems. Commonly used terms in VSS often mean something else in other VCS, and vice-versa. Here we will concentrate on the meaning of terms in Bazaar, but many of these will also apply to other VCS.

VSS Bazaar Notes
Check Out N/A In VSS, this means ‘to apply a lock to the file so that I can work on it’. Bazaar does not implement centralized file locking for reasons discussed elsewhere.
Check In Commit VSS removes edit locks and makes a new revision for each file checked in. Bazaar commits all selected changes as a single tree revision.
Cloak N/A This feature allows implicit sparse management of trees in VSS. Bazaar does not yet implement a sparse tree management feature.
Share N/A VSS allows you to share a file between multiple folders. Each folder tracks the current state of the file, unless you (VSS) branch it, or Pin it. Bazaar versions whole trees and has no equivalent feature.
Pin N/A Holds a shared file in a given state ; used when your project isn’t ready to track the new state of the file.
Project Branch All folders in VSS must be a ‘project’. VSS works recursively on projects to create folder trees. In Bazaar, only the root folder of your working tree has any special status.
Label Tag VSS applies labels by creating a new label revision for each file included in the label. Bazaar just keeps a list of named revisions in a file.
Destroy N/A VSS allows you to destroy a file - including it’s version history. Bazaar does not allow you to do this without rewriting branch history.
Get Checkout ‘Checkout’ is commonly used in most other VCS to mean the initial fetch of a working tree for a pre-existing project, and also as a generic noun meaning a folder under version control.
Branch Branch While the word is used for similar reasons, the semantics of VSS and Bazaar branching are very different.
Merge Merge Again ; roughly the same idea, vastly different implementation.
Database Repository Where the revisions are kept. VSS has one database for each project ; Bazaar can keep a project in as many repositories as you like.

Core tasks

“How are common Visual SourceSafe tasks done in Bazaar?”

Getting Help

Bazaar has a help command with a comprehensive reference on the various commands together with various other topics.

In the Windows distribution, the documentation is also provided as a standard Compiled Help Module, available from the Start menu folder for Bazaar.

Shell vs GUI

While the Windows distribution of Bazaar does ship with a GUI tool, Bazaar has it’s origins on the command line, and power-users will find familiarizing themselves with CLI usage of Bazaar pays dividends. A combination of CLI and GUI commands from the QBzr plugin is a potent combination of raw power and attractive data presentation.

The next-generation Microsoft shell for Windows, Powershell, is greatly superior to the old command shell and is highly recommended.

Basic Work Cycle

VSS uses the “Lock-Modify-Unlock” style of work cycle, where each file is only permitted to be edited by one person at a time.

Bazaar uses the “Copy-Modify-Merge” work cycle, and has no support for file locking. Users work independently and any changes they make are merged together during one or more phases of the work cycle.

Create a new project

You can create a new project (or “branch”), or initialize an existing folder of sources, as simply as:

c:\stuff> bzr init

Or you can use the “Initialize” feature of Bazaar Explorer.

Adding Files

Put the files in your new branch and

c:\stuff> bzr add

When you’re ready to call it a fixed revision

c:\stuff> bzr commit -m "My helpful message"

Getting an existing project

With Bazaar you are allowed more than one location for each project tree, unlike VSS. You might want to investigate the documentation on shared repositories before you start going mad and grabbing multiple copies of the same sources though.

c:\stuff> bzr branch lp:bzr  # get the latest Bazaar sources
c:\stuff> bzr branch http://interesting.branches.com/cool-project/trunk

Bazaar Explorer will also pull and update branches.

There is a choice to make between branch and checkout. A branch exists as a separate entity ; a checkout is “bound” to another branch and revisions committed will by default also be pushed to the “bound” repository. Checkouts come in “heavyweight” and “lightweight” varieties - the lightweight type is the closes to the way VSS works, and is dependant on the repository for most operations. Heavyweight checkouts include a copy of the repository and enable a range of operations to occur offline.

Getting The Latest Changes

In a branch:

c:\stuff> bzr pull bzr://other.branch.com/branch
c:\stuff> bzr pull  # remembers default branch from first successful pull

In a checkout:

c:\stuff> bzr update

Dealing with Conflict

Unlike VSS, you must be prepared for the changes to conflict with the work you have done, as you don’t have exclusive locks on the files you are editing. In the event of conflict, an attractive list of conflicts can be had by:

c:\stuff> bzr qconflicts

It’s recommended that you install and configure a graphical 3-way merge tool like KDiff3, WinMerge, TortoiseMerge (from TortoiseSVN), etc.

Checking In Your Changes

A more common term in other VCS is “commit”. First you can review your changes to see what you’ve done:

c:\stuff> bzr diff
c:\stuff> bzr qdiff   # this diff is much friendlier

Then you can commit:

c:\stuff> bzr commit -m "My message"
c:\stuff> bzr qcommit    # again, friendly - review your changes here if you like!

Note that this doesn’t release locks on the files - because there aren’t any in Bazaar.

Network protocols

“How do network URLs differ?”

Visual SourceSafe uses UNC paths (aka ‘Windows Network Shares’). While there are third party products that provide other protocols for VSS, the native protocol is file access over SMB (Server Message Block, the Windows network file system).

Bazaar works well enough over SMB, although you might like to consider using heavyweight checkouts instead of lightweight, or using a local shared repository. One particular gotcha to look out for is that because Bazaar considers SMB folders to be no different than local folders, pushing revisions to a remote branch can take much longer than you expected if it has a working tree - it pushes once for the revisions, then individually updates all the files.

In addition to normal filesystem storage and SMB, Bazaar also supports several other network protocols, including HTTP. These can perform better than SMB, even over a LAN, but writing to the repository will require some server setup. It’s possible to run Bazaar servers for all the supported network protocols on Windows, although it can be a little more awkward to set up than a Linux server, which will work out of the box for bzr+ssh:// as long as you install Bazaar on the server.

Revisions

How do revision identifiers differ?

VSS tracks revisions of individual files separately. Bazaar tracks the revision of the entire tree of files.

VSS uses simple sequential integers for all file revisions. For tree revisions from the current branch, Bazaar also presents simple sequential integers to the user in the UI.

VSS is capable of adding a special revision to files called a “Label”. This revision doesn’t change the file, but does provide a marker of a known state. The equivalent in Bazaar is the “tag”. Bazaar does not add a special revision to create a tag, it just adds the revision identifier to a list with it’s tag name.

Bazaar has many other useful ways of identifying tree revisions both absolutely and relatively - for full details see the help page or:

c:\stuff> bzr help revisionspec

Other commands

“How are the more advanced tasks done in Bazaar?”

Branching

Branching in VSS only occurs after you have shared files. In Bazaar, branching happens all the time ; you create a branch just to start working with it!

Branching in VSS was usually only used for patching released versions of your source. Branching in Bazaar is a fundamental activity and should be regarded as a far more natural operation with less overhead. Examples of good times to make a new branch : To fix a bug, to work on a new feature, to experiment without annoying other developers.

Merging

Merging well is the magic that makes branching so much more natural and useful in a modern DVCS. Merging in VSS is a 2-way diff between two file revisions and is always required to be performed by a human being. Merging in Bazaar will very often require no human intervention (although it is good practice to review the changes caused by the automated merge before committing them).

To merge, make sure your branch has all the changes you want committed, then position yourself in a working tree that you wish to merge TO:

c:\stuff> cd myproject\trunk

Then execute the merge command:

c:\stuff\myproject\trunk> bzr merge ..\my-cool-feature-branch

If you are fortunate, you’ll have no conflicts. If not, see “Dealing with Conflict” above, and the relevant help sections. Your changes are waiting in the working tree - review them (perhaps using bzr qdiff) and commit the changes before you continue doing other work.

Notes

“What else is worth knowing to get up to speed?”

Line Endings

VSS translates line endings between operatings systems on text files. Bazaar does not do this unless you configure it to do so.

To be completed ...

Feedback and edits

See Improving these documents.