When you create new branches on your computer, they are normally private and only accessible by you. In order to work with others, you need to make your branches accessible to your collaborators, and likewise they also need to share their branches with you.
In this section, we will focus mainly on the technical details of making branches accessible to others as read-only remote branches. Setting up a full-blown Bazaar hosting server is beyond the scope of this chapter; we will only explain a few relatively simple ways of sharing with others, including any necessary server configuration.
Not all methods may apply to you and your network environment. Feel free to skip subsections and focus on only what is relevant in your particular case.
In all the branch operations, you must specify the source branch to work with by its URL. In case of local branches, the URL is simply the local filesystem path of the branch, as we have seen in the previous chapters. In case of remote branches, the URL starts with a prefix depending upon the transport protocol used.
Bazaar supports many protocols to work with remote branches. The complete list is explained on the urlspec help page. For example:
$ bzr help urlspec URL Identifiers Supported URL prefixes: aftp:// Access using active FTP. bzr:// Fast access using the Bazaar smart server. bzr+ssh:// Fast access using the Bazaar smart server over SSH. file:// Access using the standard filesystem (default) ftp:// Access using passive FTP. http:// Read-only access of branches exported on the web. https:// Read-only access of branches exported on the web using SSL . sftp:// Access using SFTP (most SSH servers provide SFTP). ...
These are the basic protocols supported by Bazaar; additional protocols are provided by plugins. Although in general all the branch operations work transparently regardless of the protocol, access may be limited to read-only operations, and there may be inherent differences in performance depending upon the protocol.
Protocols that use the Bazaar smart server provide the fastest access. In case of these methods, Bazaar is installed on the server, and incoming branch operations are handled by the bzr serve command internally. These protocols are tuned for performance, and can support both read-only and write operations.
Other protocols are slower than the smart server, because they cannot use the bzr serve command. Thus the Bazaar client cannot receive assistance from the server side and it has to do more work and transfer more data. These protocols are often referred to as dumb servers.
The FTP and SFTP protocols support both read-only and write operations, while the HTTP and HTTPS protocols allow only the read-only access by default.
Depending upon the remote branch, you may need to specify the username, password, and port number as a part of the URL. The general format of a URL is as follows:
<protocol>://[user[:password]@]host[:port]/[path]
This format works with all the protocols. For example:
http://[email protected]:8080/repos/myproject bzr+ssh://[email protected]:8022/repos/myproject
If access to the Internet must go through a proxy, you must set the URL of the proxy server in appropriate environment variables:
http_proxy: This is used to access a remote branch viahttp://https_proxy: This is used to access a remote branch viahttps://ftp_proxy: This is used to access a remote branch viaftp://oraftp://
For example, if the proxy URL is http://proxy:8080/proxy.js, then you can set it as follows in Windows:
$ set http_proxy=http://proxy:8080/proxy.js $ set https_proxy=http://proxy:8080/proxy.js $ set ftp_proxy=http://proxy:8080/proxy.js
In GNU/Linux and Mac OS X:
$ export http_proxy=http://proxy:8080/proxy.js $ export https_proxy=http://proxy:8080/proxy.js $ export ftp_proxy=http://proxy:8080/proxy.js
If you and your collaborators have access to some kind of distributed filesystem, such as a network filesystem in GNU/Linux and Mac OS X, or a network share in Windows, then you can create remote branches without additional setup.
In GNU/Linux and Mac OS X, specify the network filesystem path to create the remote branch. For example:
$ bzr push /path/to/nfs/path/to/create --no-tree
In Windows, specify the UNC path on the network share. For example:
$ bzr push //ServerComputerName/ShareName/path/to/create --no-tree
In both the examples, we used the --no-tree flag to tell Bazaar to skip creating a working tree. Since the working tree is pointless and potentially confusing to exist in a mirror branch, this is a good measure to save disk space and speed up the push operation.
As long as collaborators have read access to the remote branches created in this way, they can work with these branches directly or create local mirror branches based on them. In fast local networks, the network overhead of accessing these branches may be negligible, thus creating local mirrors may be unnecessary.
Using an SSH server to share branches with others is very easy to set up with minimal configuration. If you and your collaborators have access to an SSH server, there are several ways to access branches:
- Using Bazaar's smart server and individual SSH accounts
- Using Bazaar's smart server with a shared restricted SSH account
- Using individual SSH accounts with SFTP
Using Bazaar's smart server provides fast access to branch data. However, for this to work, Bazaar must be installed on the server, and the bzr command must be included in the execution path of the user account used when connecting to the SSH server. In this case, the incoming branch operations are handled by the bzr serve command internally, which is tuned for fast performance.
If Bazaar is installed on the server, you can benefit from using the smart server by constructing the remote URL of the branch in the following format:
bzr+ssh://[user@]host/[path]
Here:
useris the username of your SSH accounthostis the hostname of the SSH serverpathis the absolute path of the Bazaar branch in the server's filesystem
For example, if you have a user account named jack on the SSH server example.com, and there is a Bazaar branch at the path /srv/bzr/projectx on the server, then you can access the branch by the URL bzr+ssh://[email protected]/srv/bzr/projectx, as follows:
$ bzr info bzr+ssh://[email protected]/srv/bzr/projectx
Collaborators can use their own SSH account to access the branch by simply replacing the username in the URL. Keep in mind that standard filesystem permissions apply; collaborators can only access the branches if their user accounts have the appropriate filesystem permissions on the branch paths.
When referring to branches under your own home directory, you can replace the home directory part in the absolute path with ~ (tilde, the home directory indicator in UNIX systems). For example, the following commands are equivalent:
$ bzr info bzr+ssh://[email protected]/home/jack/bzr/projectx $ bzr info bzr+ssh://[email protected]/~/bzr/projectx
Since, by default, other users don't have write permission to your home directory, it can be a suitable place to put your branches in order to provide strictly read-only access to others.
If you cannot or don't want to install Bazaar on the SSH server, another option is to use SFTP instead, if it is enabled on the server. You can construct the remote URL in the same way as in the previous section, but replace the bzr+ssh:// prefix in the branch URL with sftp://.
The main difference between these two modes is that when using SFTP, the Bazaar smart server is not used at the server side, therefore performance is slower. Nonetheless, this can be a suitable option if installing Bazaar on the server is not possible.
Instead of creating individual SSH accounts for each collaborator, an interesting alternative is to use a shared SSH account with command restrictions.
This setup requires that collaborators use the SSH public key authentication when connecting to the server, and that appropriate access permissions to the branches are configured in the ~/.ssh/authorized_keys file of the shared SSH account.
Let's suppose that:
- There is a shared repository on the server in
/srv/bzr/projectx - You want to let
jackcreate his branches in/srv/bzr/projectx/jack - You want to let
mikecreate his branches in/srv/bzr/projectx/mike - The shared repository is owned by the user
bzruser
To make this work, add the following two lines to the ~/.ssh/authorized_keys file of bzruser:
command="bzr serve --inet --allow-writes --directory=/srv/bzr/projectx/jack",no-agent-forwarding,no-port-forwarding,no-pty,no-user-rc,no-X11-forwarding PUBKEY_OF_JACK command="bzr serve --inet --allow-writes --directory=/srv/bzr/projectx/mike",no-agent-forwarding,no-port-forwarding,no-pty,no-user-rc,no-X11-forwarding PUBKEY_OF_MIKE
Replace PUBKEY_OF_JACK and PUBKEY_OF_MIKE with the SSH public key of Jack and Mike, respectively. For example an SSH public key looks similar to the following:
ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAo6+TOzByRt9EVUjpMBs5kRft9SSPamI3cRlvaX4DuMbRqjtfkRTO4tik+MAWaFeIHyO5EsdFBGp+XVH9BMqehXdjAQga4Wa2oGX/w7bn+O+gdIoJE2wzMlGV2eXcaW2PKdDIqQpUn0n+xX68vjRaCiZmqGXWhVej3cVi9dtIwIQMrcIF4T+4wONic09UjPXZKbjL2GmkzsR6SMQJBomr4TUcRgyaR5ija9R8AzvsSdNeDKkVwf83lva3jruwEMute3aZFulM5JqvjFIFqooAlSjWjdniF8ZdweeN1c2Q2QH+eCl48hY2drUsdZ+oQH+xp8x6llkZiDWFE/RZLa3Glw== Joe
The command parameter restricts the login shell to the bzr serve command. In this way, the users will not be able to do anything else on the server except run Bazaar commands. The --directory parameter further restricts Bazaar operations to the specified directory. To give only read-only access, simply drop the --allow-writes flag.
The other options on the line after
command are to make the SSH session as restricted as possible, as a good measure for security.
When accessing branches in this setup, the path component in the branch URL must be relative to the directory specified in the authorization line. For example, Jack can access his branch in /srv/bzr/projectx/jack/feature-123, as follows:
$ bzr info bzr+ssh://[email protected]/feature-123
The drawback of this setup is that you can only have one configuration line per SSH key. One way to work around this can be by adding another shared SSH account, configuring it to have read access to the shared repository, and creating the ~/.ssh/authorized_keys file as follows:
command="bzr serve --inet --directory=/srv/bzr/projectx",no-agent-forwarding,no-port-forwarding,no-pty,no-user-rc,no-X11-forwarding PUBKEY_OF_JACK command="bzr serve --inet --directory=/srv/bzr/projectx",no-agent-forwarding,no-port-forwarding,no-pty,no-user-rc,no-X11-forwarding PUBKEY_OF_MIKE
Again, replace PUBKEY_OF_JACK and PUBKEY_OF_MIKE with the SSH public key of jack and mike, respectively. Notice that we removed the --allow-writes flag and adjusted the --directory parameter to specify the shared repository rather than the per-user directories.
If you use the same SSH server frequently, it can be convenient to set up an alias in your ~/.ssh/config file as follows (only in GNU/Linux and Mac OS X):
Host repo Hostname example.com User jack
In this way, you can omit the username and shorten the server name in the URL:
$ bzr info bzr+ssh://repo/~/myproject/mybranch
To use a different SSH client instead of Bazaar's default, you can specify the path of another SSH client using the BZR_SSH variable. This can be especially useful in Windows, if you use PuTTY to store your SSH private keys. You can tell Bazaar to use PuTTY by setting BZR_SSH, as follows:
set BZR_SSH=c:program filesputtyplink.exe
You can use the Bazaar smart server directly to listen to incoming connections and serve branch data.
Use the bzr serve command to start the smart server. By default, it listens on port 4155 and serves the branch data from the current working directory in read-only mode. It has several command-line parameters and flags to change the default behavior. For example:
Use the -h or --help flags to see the list of supported command-line parameters.
Branches served in this way can be accessed by URLs in the following format:
bzr://host/[path]
Here, host is the hostname of the server, and path is the relative path from the base directory as configured in the server process.
For example, if the server is example.com, and the smart server is configured to use the directory /srv/bzr/repo, and there is a Bazaar branch at the path /srv/bzr/repo/projectx/feature-123, then the branch can be accessed as follows:
$ bzr info bzr://example.com/projectx/feature-123
The advantage of this setup is that the smart server provides good performance. On the other hand, it completely lacks authentication.
On GNU/Linux and UNIX systems, you can configure inetd to start the bzr serve command automatically as needed, by adding a line in the inetd.conf file as follows:
4155 stream TCP nowait bzruser /usr/bin/bzr /usr/bin/bzr serve --inet --directory=/srv/bzr/repo
Here:
4155is the port number where the Bazaar server should listen for incoming connection.bzruseris the user account thebzr serveprocess will run as./usr/bin/bzris the absolute path of thebzrcommand.- /
usr/bin/bzr serve --inet --directory=/srv/bzr/repois the complete command to execute when starting the server. The--directoryparameter is used to specify the base directory of Bazaar branches.
Once configured, this setup works exactly in the same way as explained in the previous section, and it has the same advantages and disadvantages.
If you have a website, and you have an SSH or SFTP access to the server hosting the website, then you can make your branches available to others in read-only mode by pushing them to somewhere visible on the website.
For example, if your website's files are in /var/www/example.com, you can push your Bazaar branches to /var/www/example.com/bzr/projectx/ and let others access them via the URL http://example.com/bzr/projectx, as follows:
$ bzr info http://example.com/bzr/projectx
Although in this setup the Bazaar client cannot receive assistance from the server side, it can figure out the necessary information for completing requests by downloading from the appropriate .bzr directories. As a result, the performance is significantly slower compared to a smart server, and this kind of setup is referred to as dumb server.
Although normally the HTTP and HTTPS protocols allow only read-only access, write operations can be possible by using the WebDAV plugin.