The Bky Manual

Ángel Ortega

This document is a brief manual for the Bky Version Control System.

Initialize a repository

bky init [-m "Initial commit message"]

Creates the basic infrastructure to convert the current directory in a working directory + bky repository. This means creating the .bky directory and asking for an initial commit message (unless specified by -m).

Putting new files under version control

There is no special command for this; any new file in the working directory will be put under version control unless considered 'non-interesting' by rsync's -C (CVS) command line option. This means that .o, .a, .bak and many more will automatically be ignored (see rsync documentation). For any other file not convered there that must be ignored, create .cvsignore files whenever needed.

Listing the changed files

bky status

This command lists the files under version control that have been modified, compared with the working directory's parent (probably the HEAD). New files will be listed as well. Files that will disappear will be prefixed by 'deleting'.

Seeing differencies

bky diff
bky diff {commit_id}
bky diff {commit_id} -p
bky diff {commit_id} {commit_id}

The first form compares the files in the working directory with those stored in the working directory's parent commit id, the second one compares the files in the working directory with those in the selected commit id or tag, the third compares the specified commit id with its own parent and the fourth compares the files stored in those two commit ids. The output of these commands is in 'diff -u' (unified) format.

Please note that diff does not compare binary files.

Commiting changes

bky commit [-n]
bky commit [-m "message"]

Commits the changes in the working directory into the repository. A commit message is asked for by spawning a text editor, unless one is specified by the -m option.

Generating changelogs

bky log

Dumps a log of the commit messages starting from the working directory's parent commit id back to the start of the project's history.

Changing the working directory to specific revisions

bky update -r {commit_id}
bky update -A

The first form updates the working directory with that in the specified commit id, and the second ones does the same with the project's HEAD (this one works as an effective revert function). In any case, any non-commited change to the working directory will be lost.

Please note that this command is NOT the same as the CVS one. Don't use update neither to know about changes by other users (this can't be done in distributed version control systems) nor to merge (you must do that by applying diffs with the patch utility).

Tagging special revisions

bky tag {tag}

Creates a tag for the working directory's parent commit id. The tag must follow the filesystem's conventions for file names.

If tag is not specified, all tags are listed.

Pushing the repository to a remote site

bky push [rsync_directory]

Pushes the repository (including the working directory) to a remote site. The remote repository is an rsync destination (can include a host name). The remote site will become an exact copy of the current repository, so be careful.

The last remote repository is stored in .bkyremote and used in next calls if ommited. This value is shared with the 'bky pull' command.

Pulling the repository from a remote site

bky pull [rsync_directory]

Pulls the repository (including the working directory) from a remote site. The remote repository is an rsync source (can include a host name). The current repository will become an exact copy of the remote one, so be careful.

The last remote repository is stored in .bkyremote and used in next calls if ommited. This value is shared with the 'bky push' command.

Exporting the head of a project

bky export {rsync_directory}

Exports the working directory's parent commit id into another directory, without any bky metadata. This is usually done to start a branch.

Working with branches

There is no special command to start a branch; on distributed systems, you just copy the project files to another place and start from there. When the branch is ready to be merged, a diff patch is created against the root of the branch and applied to the trunk.

If you are starting a branch to implement a complex feature that will end up in the trunk, you probably won't need all the project history, so you can start a new bky project for itself. You'll also want do this if you are modifying another one's sources and want to put your changes under bky's control.

cd myproj
bky-export ../myproj-cool-features
cd ../myproj-cool-features
bky-init -m "Start of cool-features branch."

or

tar xzvf another-ones-project-1.0.tar.gz
cd another-ones-project-1.0
bky-init -m "Start of my changes to another-ones-project."

So you'll start to work in your changes, deleting, modifying and adding files, and bky-committing when you consider and such. After you think you're over, you'll have to patch the trunk of your project or send the changes to the developer of the external project. So you'll want to create a diff between the root of your branch (the commit id # 0) and your HEAD:

bky-diff 0 > ~/cool-feats.patch

That you'll apply to your trunk

cd myproj
patch -p0 < ~/cool-feats.patch
bky-commit -m "Merge of the cool-features branch."

or send to the original developer

mail him@example.com -s "You'll like it!" < ~/cool-feats.patch

Sometimes you want to start a branch not from the HEAD of your project, but from an important checkpoint in the past (for example, to start a branch fixing bugs to your 1.0 release when you're deep in the development of the 1.1 one). It's easy:

cd myproj
bky-update -r version-1.0
bky-export ../myproj-1.0-bugfixes
cd ../myproj-1.0-bugfixes
bky-init -m "Start of the 1.0 bugfixes branch."

Importing from CVS

The cvs2bky Perl script helps in migrating from CVS to bky. You need the cvsps and patch tools to do it:

mkdir project
cd project
bky-init -m "Bky init."
cvsps -b HEAD -g {cvs project name} | cvs2bky

Cvsps usually chokes on binary files, so you'll probably have to add them manually before the bky-init call. Also, sometimes cvsps guesses bad and patchsets arrive with an incorrect order; if that is your case, you probably have to dump its output to a file (instead of piping directly) and reorder the patchsets yourself.

If your CVS repository is remote, the whole operation can be very long.