Starting a project

Planning your workspace

Before starting a project, take a moment to think about how you would like to arrange the relevant files on your computer. While Bazaar is very flexible in how it lets you organize things, some ways work faster and smoother than others, particularly for large projects or a large number of projects.

While it may seem overkill initially, it’s a good idea to plan for the day when you’ll have multiple projects, hosted on multiple services. For example, you may have some open source projects hosted on Launchpad (Canonical’s project hosting service) or SourceForge. Other projects may be hosted on servers at work.

To allow for this, the following directory structure is suggested:

<home directory>/Projects/<group>/<project>

where group might be a name like lp, sf, work or personal. Having a top level Projects directories is completely optional. I find it useful though to keep all projects in one place and I configure my shortcut to Bazar Explorer to start in that directory. Having a Projects folder in my home directory also fits naturally with the other directories there: Documents, Pictures, Music, etc.

If it makes sense, choose a more explicit grouping than hosting service. For example, you may have one group for MySQL-related projects, another for Wordpress plugins and another for Bazaar plugins.

Note

Project groups make ideal virtual repositories in Bazar Explorer. Organizing projects like this can also simplify settings managed via bzr’s location.conf file. More details on these topics will be presented later.

The examples in this guide will assume the directory structure above. In particular, we’ll assume you have a directory called Projects/lp already created. If you choose a different organization, please adjust the examples accordingly.

Starting a new project

Fire up Bazaar Explorer and select the Initialize dialog. This is available under Start a new project on the Welcome page. Alternatively, open the dialog using Bazaar ‣ Start ‣ Initialize.

Enter the location. From the Browse button, add a new folder using the relevant capability in your operating system. Alternatvely, simply edit the text to be the path you want, e.g. myproject under Projects/lp.

Press OK. After the initialization completes, close the dialog. Explorer should now be displaying the empty repository you just created.

Double-click on the trunk branch to open it.

You are now ready to create files and directories. The buttons at the bottom of the Working Tre browser can be used to do this. For example, click on the Create a new file button. In the dialog presented, enter README.txt.

The file should appear in the Working Tree browser. Double-click on the file to add some content. Save the file. The status report will now show the file as Unversioned and recommend adding the unversioned items.

Open the Add dialog using the “+” button (under What’s next?, next to the Unversioned section heading or in the toolbar).

Click OK. The status report will refresh to show that the file has been added. It will also recommend Diff and Commit as sensible next steps.

Open the Commit dialog. Enter a commit message and press OK.

Close the dialog. The status report will now change to tell you that the current revision is now 1.

You have now recorded the first revision in your project. Congratulations!

Workspace models

As mentioned previously, Bazaar is very flexible in how it lets you organize things. The Workspace models presented on the Initialize dialog are commonly used ways of organizing the building blocks, i.e. repositories, branches and checkouts.

In 98% of cases, either the feature branches or colocated branches model is the best choice. Here’s how they differ.

1. The feature branches model looks like this:

   repository/          (branches under here have trees)
       branch 1/
       branch 2/
       etc.

2. The colocated branches model looks like this:

   checkout/
       repository/      (branches under here are tree-less)
           branch 1/
           branch 2/
           etc.

In the feature branches case, you make changes inside the branches and every branch has a complete set of files. In the colocated branches case, the top-level is the tree where you make changes, rather than being a repository holding branches.

In most cases, the best model comes down to personal preference. In some case though, the colocated branches model is the only choice, e.g. if you want to version control files in a special location (like /etc or a set of web-server configuration files).

Putting an existing project under version control

If you already have a tree of source code (or directory of documents) you wish to put under version control, the steps to follow are almost identical to those for starting a new project:

1. Initialize the workspace.
2. Add the files and directories you want tracked.
3. Commit the initial content.

Note

Remember, if the files must stay exactly where they are, select the colocated branches workspace model instead of the feature branches one in the Initialize dialog.

If you pick the feature branches model, select the Move existing files, if any, to working tree location option to move the files down into the trunk branch.