Bazaar‎ > ‎

Bazaar terminology

The following terms make up the basics of what you need to know about bazaar


Branch

A branch stores a complete history of an arbitrary large set of files and folders. The term is in the large similar to the branch concept as it's used in Subversion and ClearCase. It's a line of work.

The most common commands that will create branches are init, branch (a.k.a. get or  clone),

Repository

A repository is an internal Bazaar constuction. It where the revisiones and history of the branches is stored. many branches can share the same repository. If you don't care you can just ignore the concept of a repository, when you create a branch it will reuse an existing repositury if possible, if not, then it will simply create a new stand-alone repository for each branch.

The command for creating a new repository is init-repository.

Working-trees

A working-tree is a file representation of a branch. It's possible to have branches that doesn't have working trees. Obviously you won't be able to work in these branches directly then, but you can use such branches for sharing, integration, centralized storage etc. All the branches on Launchpad doesn't have working trees.

Checkout

A checkout is very much like a checkout in Subversion. You get a working tree on your local file system, but your commits will be tired directly to the brach the working tree is a represnetation of. So you need to be online with the branch - where evere it is - when you make commits.

Commands that deals with checkouts are checkout, bind, unbind.

Commit

When you have a working tree you are free to go an change any of the files in it. Unlike ClearCase you are not required 'in advance' to know which file you will be changing and obtain write permissions by the version control system. In Bazaar (as in Subversion) you'll have the ability to change files as you go, and Bazaar will keep tract of what files has been altered in your working tree. When you are ready to submit your changes to the branch you commit them.

Commands that includes commits are commit, pull, update

Local commits

Even though a checkout appears to be bound to a remote branch, it is really a full featured Bazaar branch by itself.

If you want to you can commit locally in the branch 'underneath' the chekcout. this means that you actually create new revisions and record the changes  - but only locally, in what appears to be the 'the local branch'.

You do local commits with the command commit --local.

When you want these local commits to be committed to the branch the checkout is tied to you simply do a regular commit.

Unbind

When you have a checkout you can detache it from it' remote branch by using the unbind command. When you do that, your commit are not transferede and synchronized with the branch anymore - they are just plain local. It's convenient what you are off a stable network connection to simply unbind you checkout - then you get the godd perforamnce.

The command for unbinding checkouts is simply unbind.

Bind

Bind is simply the process of turning a branch into becomming a checkout of another branch.

If commits has been made to your master branch while you were detached from it you must first commit locally - and then bind. The bind may result in a merge, which in turn may require conflicts to be resolved and those too must be committed locally before you can make the regular commit and thus update the master branch with the work you did while you were detached.

The command for binding is just bind.

Pull

Pull is turning a branch into a mirror of another branch. A typical example of use is when you have a remote branch which you'd like to monitor or keep up with, you simply get a copy of the branch using the get command and keep it up constant reflection of the master branch by using the pull command.

Pull required that the branches has not diverged. If the destination for the pull has made commits which the source of the pull doesn't know of, then the pull would simply overwrite (discard) these changes in the estination branch. Therfore the pull refuse to execute when the branches diverge.

You can force the synchronization and discard your commits in the destination by using pull --overwrite but typically that is not what you want to do.

The right thing to do is tho avoid the branches to diverge. Use the local branch as a representation of the master. if you need to change it then make sure you do those changes in a third branch setup for the purpose (use the branch command to set it up) and whne you are done developing at testing you pull from the master branch, then merge from thee development and finally push back to the master branch.

The commands for pulling is pull and pull --overwrite.

Push

As in real lifepush is the opposite of pull. So you turn a remote branch into becomming a mirror or you own. As with pull this is not allowed if the destination (in this case the master branch) has commits which your branch doesn't know of - you would overwrite them (and as with pull there is actually an --overwrite switch you apply, but this setup is becoming nasty!

If you try to push and the distination is diverged then you will have to merge from you destination-to-be and resolve any conflicts and then push. But this workflow has some unwanted side effects:

Say two developers both got the master branch at revision 45 and one of the creates a new local version, commits it and pushes it - it becomes version 46 on the master branch. The other developers has also created a new version and committed the the development branch and has also created a revision 46, but when he tries to push he can't because the branches has diverged. The revision 46 on the master branch is still unknown to him. So he merges the master branch into his development branch, lets make it easy and say there werent any conflicts so the commit is simple and now he has revsion 47. Revision 46 was his own contibution and revision 47 is his integration with his colleague. Now he can push it the the master branch. And he's allowed to do that now since thcnically the branches don't diverge anymore. But pushing means that the destination becomes a mirror of the source, so the master branch will have revision 46 and 47.

What used to be revision 46 - the first developers original contibution is now an embedded merge in revision 47 - and 46 is the second developers contribution.

Aaaargh -bad!

Clearly this is not a good way to collaborate between devlopers!

A simple way to solve the case is to work with checkouts of the master branch rather than branches. You can unbind or use local commits, but the point is that when you need to get in sync with you colleagues work on the master branch you'll be force to accept their work into your local commits first, and when you have resolved any conflicts and are ready to "push" you do a commit to the master branch - that will create a new revision - on top of the existing ones.

Aaaah - nice!

As described earlier (under the header 'pull') you also have the alternative (if you dont like checkouts) to have a local branch (get) of the master branch, and branch off from that (using branch), make your development here, keep the local mirror of the master branch updated (using pull) but restrain yourselv from actually doing any changes here except until you are ready to deliver your work. Then you merge the development branch into you synchronized master branch and then you commit your merge and push it to the real master.

Merge

Merge means to take the work commited into one branch and merge it into your current (merge only takes one parameter - the source, target is always the current branch).  After a merge there might have been conflilcts, these will have to be resolved. And after that you can commit the result of the merge.

The source of the merge doesn't have to be another branch. It can be a merge packet created by someone else using the send command.

Send

Send is a merge in the opposite direction. So you are merging the changes of your current branch into a remote branch. If you have local repesentation of both branches a merge is the right thing to do. But if you target branch is o a remote server without a tworking tree - or if it's inaccessible for a merge operation for other resons, then you can use the send command to generate the merge package and ship it to the someone who has access to the target and can perform a merge.

Rename and move

Like most other version control tools, moving or renaming files and folders around in the structure requires that the system somehow gets the information that this has happende. som when you move ar rename, don't us the native files system commands, and don't drag and drop files in file exploreres that aren't educated in what such operations implies whne working in version controlled repositories. Use the commands rename and move

Adding files to version control

Adding files and folders to Bazaar is as simple as create the files and add then using the add command. What more is there to say?

Information and status


The command info will let you know the details of your branch: who's the parent, who submitted (where did you merge from) the default targert for your pushes etc.

The status command will show you the pending commits, the files that have changed since your lase commit.

Also have a look at annotate which gives details history for a specific file and diff which tells you the differences between tho files.

Using merge -preview doesn't actually change your branch, but tells somthing about what the consequneces af a merge would be.

The log command shows you the revision log for a branch (or a subset of it).

Help

Run bzr help <topic> to get help on a specific topic. To learn all what you possibly can learn in Bazaar type bzr hlp topics and get a list of the higl-level catagoris which you can get help on - and dig down from there.

Comments