Also see the "Questions for Bazaar" page on Launchpad for more answers to frequently asked questions.
<<TableOfContents: execution failed [Argument "maxdepth" must be an integer value, not "[maxdepth]"] (see also the log)>>
1.1. How do I set my email address
bzr whoami "$NAME <$EMAIL>", where $NAME is your name, and $EMAIL is your email address. Advanced options are discussed on BzrSettingEmail.
1.2. How do I publish a branch?
Just copy the whole branch (including the .bzr directory) to a web server. Bazaar is designed so you can publish your branch on standard (dumb) servers. Bazaar supports the following protocols:
- HTTP (read-only)
- SFTP (the one that comes with ssh)
Support for more protocols is coming.
Another option is to push changes with rsync by using the rspush plugin in Aaron Bentley's BzrTools.
1.3. What's "Channel request for unknown channel 1"?
It is a harmless message, due to a buggy destructor in Paramiko, the library we use for SFTP.
1.4. With bzr-0.8.2 I get parent directory does not exist for sftp:// branches
You need to install paramiko to get support for sftp:// branches. This may be known as python-paramiko or python2.4-paramiko depending on what system you are using. Newer versions of bzr make the dependency more obvious.
1.5. Can I hardlink branches?
This is no longer recommended. It still works under certain circumstances, but it does not work under all circumstances. The recommended method to do cheap branching is now to use a repository, which will share the metadata between branches, rather than having to copy all of the data for each directory.
1.6. What is the difference between pull and merge?
Pull is used to update your branch to the latest version in another branch. It only works if your branch is an older version of the other one, not if they have diverged. It copies the other branch's revision history as your own-- the result is that often when you pull, your local branch becomes a clone of the other one.
Merge applies the changes made in another branch to your source file directory. It doesn't require your branch to be an older version of the other, though automatic merging requires that the branches be related in some way. It does not affect revision history, and combines your changes with the other branch's changes, usually producing a new tree state that has never existed before.
1.7. What is the difference between update and merge?
In the case you use a central repository and work with further developers on the same branch, update is used to merge the changes made by other developers on the central branch (the branch your working tree belongs to!) into your working tree. Doing this updates the revision of your working tree (and local branch). When you try to commit and your working tree isn't uptodate commit urges you to use update.
merge is used to merge in the changes from another branch. For doing this you need a committed working tree.
1.8. How do I fix a stale lock?
#5988 - Use the break-lock command, or just remove the 'held' directory inside the lock directory. There will be a show-lock command soon.
1.9. How to move uncommitted changes from one tree to another
- I started hacking on a branch, and realized that I actually wanted those changes in another branch before commiting (I say "branch" since I have branches with working tree in the same place).
The best way is to do merge --uncommitted, to apply the uncommitted changes from the wrong tree into the right one.
1.10. How to recreate working tree in a branch that was pushed over sftp?
- I push a branch from one machine to another over sftp. Branch was pushed first time (on target machine this branch did not exist before). Because push does not update (and create) working tree I need to recreate it manually. How to do this?
You can run 'bzr checkout .' to put a working tree there. Then, 'bzr update' on the remote host will update an existing working tree.
1.11. When I branch from a web server, I get "ERROR: No such file"
One common cause of this problem is a server misconfiguration. Bazaar uses url-style percent-encoding to record non-ascii and uppercase ascii characters, so that its repositories work on all filesystems. But some web servers will double-decode urls, which causes them to look for the wrong files.
You can test whether your web server is doing this by trying to access the url http://your-server/path/percent%2541. If the error message refers to percentA, the web server is double-decoding the URL.
bzr 0.9 avoids producing file-ids with capital letters, so if you add your files using bzr 0.9, you should be able to host your branch, even if the server is double-decoding. But this solution doesn't apply to existing branches.
1.12. When using ftp, I get 'connection refused'
By default Bazaar uses passive ftp, which works well for most networks and servers. In some situations you may need to use "active ftp" to get a successful connection. To do this, use the aftp protocol scheme, eg aftp://host/dir.
1.13. This transport does not update the working tree
In Bazaar, branches are commonly collocated with working trees. For some Bazaar transports like ftp and sftp, if there is a remote working tree then we can't update it. (This is partly because of limits in what we can do over the transport and partly that we just don't support it.) In order to get the remote working tree up to date, you need to call bzr update on the remote side. You can automate this with the Push and update plugin.
1.14. Help! I pushed my local changes to the mainline, and now my revisions are gone!
If you work on your local branch, then push to the mainline, it might appear to you that your changes had been lost: if you look at your local branch, your commit with feature "foo" is, say, revision 509, whilst on the mainline revision 509 is "bar" by someone else. This is in fact exactly as it should be and nothing has been lost. You can confirm this by looking at the output of bzr log http://url/to/mainline/. One of the recent commits will be a so called merge revision, and in addition to its own message will also show several subrevisions numbered something like 507.1.3, which correspond to your local commits.
To understand why, you have to realise that Bazaar works in terms of independent branches, and not one central repository and slave checkouts. This means, in particular, that revision numbers are only meaningful for a single branch; if you have two independent branches, their revision numbers will necessarily differ after the point where they diverged. When Bazaar merges two branches, it doesn't compare revision numbers, instead it compares revision ids, which are guaranteed to be globally unique amongst revisions and trees. Because branches (and their histories) are DAGs (Directed Acyclic Graphs), what happens happens during a merge is that Bazaar adds revisions present in the source but not in the target onto the target's graph, in a way that's compatible with how those revisions were committed in the source. It will not make the target graph identical with the source, since that would lose the target's own history. However, it is made equivalent, so that when you look at the resulting source tree, it's as if the merged commits were made in the target branch.
For more information about revisions and revisions numbers (including the dotted revision numbers), take a look at the Bazaar user guide.
2. Migration from Other VCS
2.1. How to migrate from CVS?
2.2. How to migrate from Subversion
2.3. Other VCS
Most VCSs are supported by Tailor.
2.4. Tracking Upstream CVS/SVN/etc
See TrackingUpstream for a description of how to use bzr to track local changes of another project which uses something other than bzr.
3. How do I do ... like I did in <other VCS> ?
3.1. Switching branches in-place
In CVS, one uses cvs update -r$REV to switch the working copy to a branch or revision tag. In SVN you use svn switch.
To do the same in Bazaar, use bzr switch.
4. Architecture and implementation
4.1. Are binary files handled?
(Of course, all files are in a sense binary. "Binary files" typically means non-text files, such as JPEG images, that contain unprintable characters, aren't organized into lines, and can't be diffed/merged as text files.)
bzr currently handles binary files just fine: you can add them, commit them, recover them, etc, and this should continue for future versions. bzr will allow you to plug in support for diffing or merging non-text files. Unlike other systems, it does not rely on base64 transformation of binaries into text for storage.
bzr diff used to spit out binary diffs, which looked ugly. The current bzr codebase just prints out that binary files have changed.
That said, bzr is primarily a source code control system, not a media archive system. So it is not a priority to support enormous (hundred-megabyte) binaries or multi-gigabyte trees. There are other tools better suited to that.
4.2. Is non-ASCII data handled?
bzr works in Unicode internally. Repository files are stored in UTF-8 and so can be shared between people using different operating systems or languages.
The encoding for input and output is determined by the user's locale, as interpreted by Python's locale.getpreferredencoding() function. At the moment we assume all user data is in the same encoding: commit messages, terminal output, configuration files, etc. This is probably not true for all users, and special cases might be added as they become necessary. (It is becoming more true as systems tend to become natively Unicode: Ubuntu and Fedora for example use UTF-8 by default.)
4.3. Should Bazaar really be written in Python?
Some people are concerned that a program written in Python will be adopted more slowly than one written in C.
We are two or three times more productive at development in Python than in C. Where performance is limited by python we will introduce C modules for the performance sensitive areas.
Python is installed on many machines, and easy to install on the rest. We will keep the number of library dependencies as low as possible.
Good support for non-Linux platforms is an important goal, and this is arguably easier to do in Python, where more OS dependencies are handled by the standard library.
4.4. Permissions storage
When I make a new branch or check out an existing repository, the permissions bits are lost.
Versions of Bazaar of 0.1 and later support the tracking of the executable bit. Other permission bits are not currently tracked.
4.5. When do you plan to...?
Please see ReleaseRoadmap for our current plans.
5. What is the difference between Bazaar and Baz
"Baz" was an old tool based on Arch that is now deprecated.
The baz-import command from BzrTools converts archives from the Arch format to bazaar.
6. Getting involved
6.1. What can I do to help?
Subscribe to the mailing list. The mailing list web page is at http://lists.canonical.com
- Download the development code, try it out.
Have a look at the TODO file in the development tree for some suggested tasks of various levels of difficulty.
- Send any questions, queries, bug reports, patches or suggestions through to the list.
6.2. How do I report a bug?
Please send bug reports to the mailing list. It is helpful if you can provide steps to reproduce the problem, or a link to a branch that exhibits the problem.
6.3. What are the guidelines for contributing code?
Please see the HACKING file.