HomeSite+ and the Bazaar DVCS

I’ve finally come around to releasing the toolbar I use in Homesite for working with Bazaar. There might be some people still enjoying Homesite as their editor of choice, and seeking a solid VCS system, so here’s an explanation of how I work, and a link to the toolbar I created for using Bazaar from Homesite.

VCS versus DVCS

There are a lot of well-known version control systems. Traditionally they had a central location for storing files, and a developer would “check out” a file, work on it, and check it in again, together with a description of what he (or she) did. Examples of VCS’s that work(ed) like that are Visual Sourcesafe and Subversion.

Lately there is a  new breed of VCS that doesn’t keep the sourcecode in a single central location. Every developer has his (or her) own repository (a repository is where the sourcecode is stored, together with all of the changes and descriptions.)
This allows developers to work and commit changes to their own repository, independent of the “main” code. Whenever they see fit, they then merge these commits with the “main” code. A developer can work on a bunch of files to add new features or fix a bug, and then commit them as a single new revision. Bazaar and GIT are examples of these new DVCS versioning systems.

There is an excellent explanation of the differences between traditional VCS systems and a DVCS here.

Using Bazaar under Windows

I’m writing this article to give you a quickstart in using Bazaar under Windows using HomeSite. It is in no way a complete reference to Bazaar. It just explains the way I use Bazaar currently. Bazaar has numerous other usage scenarios besides the one I use.

To start off, download Bazaar and Install it. I use the standalone version myself. When selecting the options for installation, make sure you have Bazaar add itself to your PATH environment variable, also make sure you install QBZR (a GUI for Bazaar). If you accept the default settings, this will automatically be done.

Now that Bazaar is installed, test it by opening a command window and typing “bzr”. Bazaar should respond with:

Bazaar 2.2.1 — a free distributed version-control tool
http://www.bazaar.canonical.com/
….

Setting up Bazaar for solo or team development using a central repository

The way I work with Bazaar is I store my source-code in a central location, I develop locally and I commit my changes to that central spot. This is in fact how traditional VCS’s work. As I mentioned, Bazaar has more scenarios to work in, but this one suits me well. I have my “main” repository on a NAS drive, and I work locally on one or more Windows machines, developing websites under IIS.

To set things up this way, what I do is the following:
I have mapped a drive letter to the directory on my NAS that has all of my different folders with sourcecode. In my case the drive letter is W:, on that disk there is a folder called “websites” and in there, there are folders for the sourcecode of all of the websites I’m developing.

When starting a new webproject, I create a new folder in W:\Websites\, in this example let’s call it “www.demosite.com”. So now I have a folder called W:\Websites\www.demosite.com\. In this folder I add all of the files and folders I already have for this project. I always have an images folder, a script folder and a css folder for example. Also, because most of the sites I maintain are classic ASP, I also have a global.asa file in there. Anyhow; add the files you want to start out with, and when you’re done, open a CMD window and navigate to the corresponding folder (in the example W:\Websites\www.demosite.com\)

Initialise a folder for version control

So now we have a directory of files and folders, and we want bazaar to keep track of any changes there. Note that it doesn’ t matter that you’re working on a networked drive, bazaar works over a networked connection aswell as locally. It can also work using SSH, FTP or HTTP connections, but that is out of the scope of this article.
Back to the CMD prompt; type “bzr init” to start versioning this directory and everything in it (no pun intended). Bazaar will respond with: “Created a standalone tree (format: 2a)”.

Bazaar will have created a hidden folder called .bzr where it will store its information. Unlike Subvsersion, which puts a hidden folder like this in every subfolder, this is the only folder Bazaar needs and uses. So removing versioning is as simple as throwing away this single .bzr folder.

Adding the contents of the folder and subfolders to Bazaar

Now that this folder is in version control, we need to add the files and subfolders in it to Bazaar. We do that by typing “bzr qadd”. This will invoke a GUI tool for adding files to bazaar. By default it will try to add all new files and folders under the versioned directory. Sometimes you will want to exclude some files from being versioned (like Windows’ thumbs.db files, for example). You can do so by creating an “ignore” file, or using “bzr ignore”. The ignore file is beyond the scope of this article, but it’s easy to setup and well documented on the bazaar website.
In the qadd dialog, add all of the files and folders you want bazaar to keep track of and click ok.

Commit the files and folders in Bazaar

The last thing we need to do now, is make our first commit! We have initialised the folder, added the files we need to keep track of, and now we need to tell bazaar to store this information in a commit. Type “bzr qcommit” in the cmd window and in the dialog that appears, type a description of what you’ve done. In this example we can just write “added all of the base files” or something. Bazaar will now add the changes and your message, and you have just committed revision one of your project!

Working in a team or from multiple computers

This is ofcourse very nice, but I want to work on this code from different computers in my house, and if it is a website, I want the code in the inetpub directory of my local IIS. Because the repository (yes, your sourcecode folder is now a repository) is in a central location, this is all possible.

To accomplish this, just open a cmd prompt in the spot where you want the sourcecode folder on your local machine, say “C:\inetpub\wwwroot\”. Now type “bzr checkout W:\Websites\www.demosite.com”. Bazaar will now fetch the sourcecode from that directory on W:, copy it to the local folder and hey presto, you have a local repository.
Please note that this works on a directory level, so the entire folder http://www.demosite.com is copied to c:\inetpub\wwwroot\. Keep that in mind when creating repositories.

Because we used the “bzr checkout” command, instead of  “bzr branch” which  does something similar, bazaar now knows that your local version of http://www.demosite.com is linked to the “main” repository on W:\Websites\. That means that every time you change something in your code locally on C:, and you do a “bzr qcommit”, it will commit to the repository on W:\Websites\www.demosite.com\ as well as to c:\inetpub\wwwroot\www.demosite.com\. This means both repositories are being kept up-to-date.

An advantage of bazaar is that when, for example, the NAS is out of order, or you have your laptop away from your network, you can still change code locally and add the changes to your local bazaar repository using “bzr qcommit”. There’s a checkbox in the GUI that allows you to commit locally only, when you return to your network, you can merge all of your commits again with the repository in the central location.

Also, if you’re working with a team of people, all of these individual developers can do the same “bzr checkout” from the central location like we did above, and have a copy of the repository on their local machine. They can commit their changes, and these changes will also be added locally and to the central location. The only extra step involved is that you’ll have to do a “bzr update” command before you can do a commit.
In a team scenario, it’s possible that one of your co-developers has added a feature and commited it to the main repository. In order to update your own (local) repository with the latest code from the main repository, use “bzr update” to update. Again, because we used “bzr checkout” to create a local repository, bazaar knows where the main repository is stored, and typing “bzr update” will fetch the latest version from that location.
This way of working enables you to work in a team using a central repository of your sourcecode.

To recap, a few bazaar commands:

bzr init – prepares a folder for version control, bazaar adds a .bzr hidden folder to store information.
bzr qadd – GUI tool to add new files you have created in your project and want to add to version control
bzr remove [file] – remove files from version control. The –force option will delete these files from disk, –keep will remove them from bazaar, but not from disk.
Note: deleting a file from disk using homesite or Windows explorer will mark the file as “missing” in Bazaar, use this if you want to keep the version history of the deleted file.
bzr checkout – create a copy repository from an existing repository, “binding” the copy to the original, this is called a “checkout”
bzr qbranch –  GUI tool to create a copy repository from an existing repository, not “binding” the copy to the original, this is called a “branch”.
bzr qpush – GUI tool to push any changes in one repository to another (unbound) repository
bzr qcommit – GUI tool to commit changes to the local repository. If the local repository is bound to another repository, the other repository is also updated.
bzr bind – bind a branch to a repository. (If you used bzr branch, but later on you decide you still want to bind to the original  repository)
bzr qannotate [file] – GUI tool for looking at a file and seeing all changes per line.
bzr qlog [file] – GUI tool for looking at all revisions that changed a file

An example of the workflow in the current setup

The way of working, when the repository is setup and you are working locally on a checkout (a bound repository from another location), is :

– start editing, add a feature, or fix a bug in your local code
– go to the local directory in a CMD window (I usually have one open the entire time)
– use “bzr update” to see if your local code is up to date with the central version, if not, bazaar will update your local version
– use “bzr qadd” if you have added any new files to the code
– use “bzr qcommit” to add a description of what you did and commit your changes to the local and the central repository

The Bazaar toolbar for Homesite

Finally for the Homesite toolbar;
I’ve found that working with bazaar is very easy, but as you can see, it does require some work in the command prompt. Especially when working in an editor, it can become tiresome to go back and forth to the command prompt every time, so here’s what I did:

First I installed a “command prompt here” menu option in the (right-click) context menu of Windows. Here is an explanation of how to do this. This option will show up in HomeSite aswell, when you right-click a folder. Windows 7 has this feature built-in when you press shift and right-click a folder, but that doesn’t work in HomeSite. I used the registry-hack from  the aforementioned site, this works fne in Windows 7 aswell. I no longer need to press the shift-key and it works from HomeSite.

Using this context-menu item I can easily open a command prompt to any of my website folders from Homesite, I no longer have to navigate in DOS to the correct folder.

The second thing I did was create a toolbar for Bazaar for HomeSite. It has the functions in it I use most. Please note that it is made for the way of working I described above. (so using a checkout). It is also possible to use a repository that is not linked to a central location, but in that case you have to use “bzr push” to push any changes you make locally to another repository. These are the buttons I have implemented:

* bzr status -> shows the status of your current repository
* bzr update -> updates your files if they are bound to a master branch
* bzr commit-> commits your files
* bzr anotate -> shows the changes in the file that is currently open in Homesite
* bzr log (current file) -> shows all revisions of the current file
* bzr log -> shows all revisions of the current repository
* register WSC -> this is not bazaar related, but a tool I use a lot personally in ASP development. You can easily remove this button in HomeSite.

You can find the Bazaar toolbar for Homesite here. To download it, you’ll need Bazaar installed :) The instructions for using Bazaar to download code from Launchpad is here.

Note that you can edit the toolbar yourself, you’re very welcome to implement things further, some buttons are just a call to one of the qbzr GUI tools, others have some more intelligence: HomeSite can use vbscript scripts to automate things, and for example, I have implemented a script that can figure out where the current root of the repository is as seen from the current open file. Let me know if you have an interesting addition so I can integrate it on Launchpad.

Advertisements

Tags: , , ,

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

w

Connecting to %s


%d bloggers like this: