[Legacy] How to Use kbfiles


—Update: Don’t! Use LargeFiles Instead!—

KBFiles has been replaced by it’s successor, LargeFiles. KBFiles appear to still work with Kiln (as of 2.9.61) but the extension is no longer being developed and may stop working in a future version of Kiln. LargeFiles is a Mercurial extension, so it will be maintained and kept up to date by the Mercurial community.

—End of Update—

If you are still using kbfiles, you can read on, but please consider converting to LargeFiles as soon as possible.

How It Works

Before we get into using kbfiles we need to learn a little about how kbfiles works. For every bfile a standin file is stored in your repository. If you have a file bar/foo then the standin will be .kbf/bar/foo. The standin stores the SHA1 hash of the bfile. When you clone a repository first the Mecurial repository is cloned, then we look through all of the standins and download the file with the correct SHA1 hash from Kiln.

Using kbfiles

Commands like clone, commit, push, pull, and update all work with kbfiles without any new options. The following Mercurial commands work with kbfiles: add, archive, backout, bisect, clone, copy, fetch, forget, incoming, log, merge, outgoing, remove, rename, revert, status, summary, update, and verify. The Kiln web interface is exactly the same for kbfiles repositories as it is for normal repositories.

Working with a kbfiles repository is very similar to working with a normal repository. For example the following sequence of commands works on a kbfiles repository exactly like it would on a normal repository.

hg clone http://path-to-repo-on-kiln kbfilesrepo
cd kbfilesrepo
<edit a bfile>
hg commit -m 'Updated a bfile'
hg pull
hg merge
hg commit -m 'Merged'
hg outgoing
hg push

Creating a kbfiles Repository

We still need to create a repository that uses kbfiles. To use kbfiles with an existing repository you will need to convert the repository to a kbfiles enabled repository. The conversion is simple with the kbfconvert command, for example:

hg kbfconvert sourcerepo destrepo --size 10

This converts sourcerepo to destrepo. Any file larger than 10 megabytes will be stored as a bfile. Run hg kbfconvert –help for more information about the command. The conversion might take a few hours, but you only have to do it once.

Adding New kbfiles

Adding is a little different with kbfiles because you need to specify whether the new file should be stored as a bfile or a normal file. Add the –bf option to specify that a file should be added as a bfile, for example:

hg add --bf movie.avi

The command will add movie.avi as a bfile. Read hg add –help for other kbfiles options.
You can also specify a size and a pattern in your hgrc file. Any file larger than that size in megabytes or that matches the pattern will be added as a bfile instead of a normal file. Below is an example kilnbfiles section of an hgrc file.

size =5
patterns = glob:**.avi

Now any file added which is larger than 5mb or has the extension .avi would become a bfile. These options are only used on repositories which already have a bfile, normal repositories will not be affected.

Using Normal Repositories With kbfiles Enabled

The kbfiles extension should be left on even when you work with normal repositories. It will not change how normal repositories work, but in some cases it might change the output of a command slightly. For example hg outgoing will now print “Searching for changes” twice.

What Doesn’t Work (Yet)

TortoiseHg integration with kbfiles did not make it in Kiln 2.0. You can’t corrupt your kbfiles repository with TortoiseHg, but most of the commands will not work. Using TortoiseHg with kbfiles is not recommended even though some parts of it might work.

Some Mercurial commands don’t work with kbfiles. For example hg serve won’t work correctly.
kbfiles repositories can only be pushed or pulled locally or through Kiln. Pushing or pulling through a repository on a networked drive will not work properly.