What happens if I push a file that already exists unversioned downstream?

It will move the old file out of the way. This can be somewhat confusing if directories are involved, so here is a good example: Suppose you have a branch sparsely versioned (mixed in with stuff that isn’t versioned) and you make an identical copy. This copy contains both the version and unversioned contents. At this point both read out like this:

• Branch
  • index.html (versioned)
  • styles (unversioned)
    • common.css (unversioned)
    • specific.css (unversioned)
  • zscript.php (versioned)

Now down the line, you decide to version styles/common.css, but when you push find this:

Conflict adding file styles.  Moved existing file to styles.moved.
1 conflicts encountered.

Now you’ll find that the styles/ directory only contains the common.css, with specific.css being placed into the styles.moved directory:

• Branch
  • index.html (versioned)
  • styles (versioned)
    • common.css (versioned)
  • styles.moved (unversioned)
    • common.css (unversioned)
    • specific.css (unversioned)
  • zscript.php (versioned)

The main effect of this is that specific.css is moved out of the way. This will happen (writing as of  bzr 2.1.1) even if the versioned contents is identical. This is rather counter-intuitive to how mixing versioned and unversioned contents is otherwise tolerable.

What happens to a remove a file then push somewhere it exists unversioned?

Suppose you have a repository with some files under version control, and you’re pushing or pulling to another branch. Most likely scenario is a development, testing, or production branch/server. As you probably know, there is the --keep option, which leaves the file in the working tree (usually the file system). However, if the branch is pushed/pulled the files will be removed! Right now the only way (as of 2.1) to have the file not get removed on a push/pull is to also do a bzr rm before the push on the same file, but that’s not a realistic solution. See this Stack Overflow discussion.

If you use FTP (or other “dumb” protocols), you’ll probably at some time be told to run bzr update to update the current working copy. To avoid this, I usually do a bzr pull instead when using FTP to avoid this.

What’s wrong with my bzr diff?

If you’re getting stupid results from bzr diff, it’s probably because the line endings. If someone transfered the files from a Windows to a Linux machine or used the wrong FTP settings. Try running dos2unix -U (this is in the tofrodos package on Debian/Ubuntu Linux) on files of interest. Something like this usually works:

dos2unix -U `find | grep "\.php$"`

That will fix the lines on all your PHP files, as find is recursive. You can also use fromdos or a custom scrip that removes \r from \r\n combinations, but I would use the existing packages if possible.

How can I get a list of all the files under version control?

You can use bzr ls -VR --kind=file to list out just the files. It can be useful to create this list in one branch, then use the file list relative to another branch. For example, assuming files.txt is the output from the former bzr ls command:

tar -czf core_backup.tgz `cat files.txt`

How can I synchronize similar code bases?

You’ve probably got some existing downstream code bases you want to keep under version control. The problem here is that you have to create one branch before another, and either way they’ll start out not the same and have to be merged, right? One solution is to version the base system files that you’ll be providing updates for. This doesn’t include stylesheets, site-specific templates, etc. After having done a bzr commit, go to the branch directory and copy the .bzr/ directory to the downstream branch directory (which has the similar content). To archive the .bzr/:

tar -czf devbz.tgz .bzr/

Once you copy dev.tgz to the downstream branch you can untar it by:

tar -xzf devbzr.tgz

Now you’ll have the .bzr and you can do something like bzr revno or bzr log to see that the version information has been ported. To see what’s different, use bzr diff somefile and do other standard Bazaar operations to check out how the changes differ. However, if you do a bzr commit, that makes the downstream branch ahead of your development, which probably isn’t what you want. What I do here is a bzr export from the dev branch to the downstream:

bzr export dev.tgz

Which will have all of the files in the dev branch in a sub directory with the name of the branch. I use this command to untar it into the downstream directory, overwriting everything:

tar -xzf dev.tgz --strip-components 1

The two branches will be the same now, so a bzr commit won’t need to be made. Now you can make changes to the dev branch, and do a bzr pull or bzr push to get the changes into the downstream.

Can I push/pull from a branch with uncommitted changes?

Yeah, use the --no-strict option. This is nice if you forgot to do a push, then made some changes, but don’t want to bzr revert and lose them or bzr shelve them.

Things We’re Not Doing

I’m not telling you how to install Joomla, and I’m probably the only one that’s not going to do that.

We’re not going to be packaging this. Later, you can make the .xml and .zip later, use a tool to automate this, or copy the directory to other sites. Packaging is an important part of long term development (later).

Make sure you’ve got a MySQL database, and a front-end like phpmyadmin, squirrel or some other way to add a row into jos_components. (You can use the mysql client with an INSERT statement too)

We’re only making the back-end (administrator/) interface. You can duplicate your efforts for the front-end (components/com_joombzr)

Inserting into MySQL

Go into phpmyadmin, select your database, then select the jos_component table. In some fashion, insert something like this:

INSERT INTO jos_components (
   id, name, link,
   menuid, parent, admin_menu_link, admin_menu_alt,
   option, ordering,
   admin_menu_img, iscore, params, enabled
) VALUES (
   NULL, 'JoomBzr', 'option=com_joombzr',
   '0', '0', 'option=com_joombzr', 'Site Version',
   'com_joombzr', '0',
   'js/ThemeOffice/edit.png', '0', '', '1'
);

The name of my component is JoomBzr. You can edit this now or afterwards. I’ve messed with component names and directories a lot, and it’s pretty straight forward. I’ve renamed components, and you’ll probably do that at some time too.

Creating Directories

Your going to want to make this directory:

administrator/components/com_joombzr
This is where everything for the back-end and interface .

Later you’ll create one in components/com_joombzr for the front-end. This component only has the back-end, remember?

Creating Hello Joomla on the Back-End

Create administrator/components/com_joombzr/joombzr.php and simply put:

<?php echo "Hello Joomla!";

Notice there is no closing ?>. This is standard practice now for PHP-only scripts. You can now navigate to this component in the back-end (administrator/) and select it from the Components menu. This will get you results within a short time. From here you can create a controller, and some models and views.

Here are the main places I have to synchronize to and the reasons for doing so:

Linux Notebook
This is where I write most of my code and I mainly use Bazaar here as a way to keep a changelog and sometimes revert changes. It’s also nice to be able to get some quick stats. You can also create a repository within another, for example, if some piece of code starts to grow legs of it’s own.

Windows Machine
I keep a Windows install for gaming, but I do have Eclipse and Cygwin installed here. I simply use Bazaar to check out and test my code. Windows-specific changes are usually made from here and need to make their way back to my Linux machine for further testing.

Web Server
This is where I push all my public code. For things I’ve open sourced, the address is http://bzr.santiance.com/ and anyone can branch this. Release early, release often. For proprietary work this would be a private server. I authenticate via SFTP, but regular FTP is also supported.

The Public
When someone makes changes to my code the way I synchronize is with Bazaar or a patch. Some simple changes only require a patch, but more elaborate changes warrant a merge.

At any time all three of these can have different copies of the code. Bazaar handles merges quite gracefully, and when there is a conflict it’s quite clear how to resolve it. Before I truly embraced this system I was able to navigate my way through armed with just the 5 minute tutorial.

Example

I usually start by developing something on my Linux notebok, but I do the same thing from within Cygwin if I do develop something starting on a Windows machine. On Linux I keep my Eclipse projects in ~/workspace/, and in Windows I keep them in C:\cygwin\home\kris\. After I’ve crafted up something I’ll create a repository and add the project files and source code then commit my changes:

bzr init
bzr add src
bzr add .project
bzr commit

Supply the changelog information and Bazaar will have saved this initial commit. Now I like to get my code to either the public server or private development server if the work is proprietary. I do this by:

bzr push sftp://user@bzr.santiance.com/projectname

One great thing about Bazaar is that you can push/pull changes from all kinds of places. If I don’t have (internet) connection to my web server, I can push/pull from my Windows and Linux machines over SFTP or a network mount. I can later push these changes back to the web server, so I get some data redundancy to help avoid losing code.

For clients that don’t want to use version control, which sadly do exist, you can easily take a snapshot of the code to be sent:

bzr export TheProject.tar.bz2

You can change the archive file type by modifying the file extension. I most commonly use .tar.gz, .tar.bz2, and .zip for my projects.

BZR vs GIT

So, why do I have a Github account? Mainly because other projects I’ve worked with use git, since most of my original work would find it’s way to Launchpad. Both Launchpad and Github make it easy to submit changes from the command-line once you’ve got an account. Luckily Bazaar has plug-ins that make working with repositories in another format much easier for us.

When it comes to the argument of simplicity and low barrier of entry, my hat’s off to Bazaar. It’s handled every scenarios I’ve thrown at it, and my projects have survived the advancement of their storage format from pre 1.0 to (now) post 2.0. Both tools are equally capable, but Bazaar‘s interface is more intuitive.

Send hate and flames @KristopherIves