presenting the fundamental abstractions

[Andrew King]

To further my own understanding, and to help put off a few of those
similar questions I have been asked by my colleagues, I thought I
would try and write out a bit of an explanation of bzr concepts. In so
doing, I came up with some questions as well. Anyway, I thought this
might be a good way of fixing my misconceptions, or starting a
concepts section on the bzr wiki. (As it is written by someone who
isn't a bzr developer, hopefully I may have more idea of what people
don't "get" (including me!).

Unfortunately, I came up with 4 components, not 3, so that is a bad start :(

==========

bzr fundamental components

This is an attempt to explain how bzr works in terms of its
fundamental components, rather than in terms of work flow or use
cases.

1. Revisions -

At its most basic, bzr tracks revisions. A revision is a set of
changes to one or more files, with associated metadata (such as the
author).

A simple example of a revision may be adding a single file, or
changing one line in a file. More complicated revisions could be
additions, deletions and changes to hundreds of files.

2. Branch -

A branch is a set of revisions. A revision exists in one or more
branches. A branch itself is not editable, it is modified by means of
a working tree (commit etc.) (see later), or via addition or deletion
of revisions from another branch.

3. Working Tree -

A working tree is a set of files and directories. It is connected to
exactly one branch, and is in fact, the set of files that would be
produced if you applied all the revisions in that branch in order.
Each working tree is associated with one particular branch. However,
not each branch needs a working tree. A branch can exist without a
working tree. If this is the case, it can only be modified by commands
that add or remove revisions from other branches (pull, push).

4. Repository -

A repository is a collection of revisions. It is effectively a tool
for caching revisions for sharing between branches. You cannot get the
current state of a repository. A repository cannot have a working
tree. A repository could also be named a "revision cache". If you try
and create a branch in a directory that does not have a repository as
a parent, it will automatically create one.

Bzr commands, and what they work with or do (in terms of the components above).

bzr init
   - branch
   - working tree
This creates a new branch at the specified location, with no revisions
in it. This also implicitly creates a working tree with no files in
it, since you can start creating files and add them.

bzr branch
   - revisions
   - branch
   - working tree

This "copies" a branch from another location. This means it creates a
new branch with all the revisions from the specified branch location.
If the branch currently has no repository, it creates a working tree
with the latest version of the files from that branch. If it has a
repository, it uses the repositories default setting for working
trees, ie. create a working tree, or don't create a working tree. This
is slightly different to copying all the files manually (ie. with a
file system command) because it verifies all the files etc. are
correct.

# why does the repository determine whether or not there is a working
tree? How do you do this with the branch command? Why does a branch
share the "has a working tree" or "doesn't have a working tree" aspect
of its repository (if it has one?).

bzr add
   - working tree
This marks a particular file in a working tree to be included as a
file to be managed by bzr when the next "commit" is done.

bzr status
   - revisions
   - branch
   - working tree
This shows all the files that differ from the current branch (ie. that
differ from the current state of files if you were to apply all the
revisions in the branch in order). If you were to "commit", all these
changes would be added as the next revision to the branch.

bzr commit
   - revisions
   - branch
   - working tree
This adds a revision to the current branch with all the changes that
have been made to the working treeas compared to the current set of
revisions in the branch.

bzr revert
   - revisions
   - branch
   - working tree
This resets the working tree to the latest version of the branch.

bzr pull
   - revisions
   - branch
This is a way of adding revisions that are present in a foreign branch
to the current branch.
This adds all the revisions in the FROM branch to the TO branch that
are not already in the TO branch. If the TO branch has additional
revisions, this command fails (it will not do anything and print out a
warning). Depending on the "transport" (see later), this may or may
not update the working tree. (ie. the files the user sees may get
updated or may not).

bzr push
   - revisions
   - branch
This is a way of adding revisions that are present in the current
branch to a foreign branch.
This adds all the revisions in the current branch to the foreign
branch that are not already in the foreign branch. If the foreign
branch has additional revisions, this command fails (it will not do
anything and print out a warning). Depending on the "transport" (see
later), this may or may not update the working tree. (ie. the files
the user sees may get updated or may not). If it can't update the
working tree, it will print a warning. It is then necessary for
someone to use the "bzr update" command on that branch/working tree.
If no foreign branch is specified, it will create the branch at the
foreign location.

bzr merge
   - revisions
   - branch
   - working tree

This command is necessary to reconcile two different branches if two
branches both have additional revisions. This applies all the extra
revisions of the current branch to the current branch's working tree.
It is not possible to do a merge in a branch that does not have a
working tree. As this modifies the working tree, it is then necessary
to use 'bzr commit' to modify the current branch with the accepted
revisions (and new changes due to handling conflicts etc.) If there
are no additional revisions in the current branch, merge falls back to
doing a pull. In this case, it does not modify the working tree, it
instead modifies the branch.

bzr bind
   - branch

This command 'ties' two branches together, so that whenever a revision
is added or removed from a specified branch, it is also added or
removed from the bound branch.

bzr unbind
   - branch

This command 'unties" two branches that were previously 'tied'.
Revisions added to the foreign branch will not be added to the
specified branch.

bzr uncommit
   - branch
This removes the last revision from a branch.

bzr checkout
   - branch
   - working tree
If no foreign branch is specified, it will create a working tree for
the branch specified.
If a foreign branch is specified, it will create a local branch which
is bound to the foreign branch, and create a working tree for the
local branch.
checkout --lightweight creates a working tree for the foreign branch
specified, but does not "copy" the branch (ie. all the revisions
locally). All operations therefore need to connect to the remote
location to do anything.

# Why does checkout do 2 seemingly very different things? This seems
to cause a lot of confusion. Am I misunderstanding the components
here?

bzr annotate
   - branch.
Show the origin of each line in a file.
# Why can't annotate work on a remote branch?

bzr init-repo
This commands creates a "caching" area for any revisions present in
any branches "inside" it. (ie. in a nested directory). If a revision
is to be added to a branch, it first checks the repository to see if
that revision is already cached.
It also (for some reason?) controls whether branches inside it will
have working trees or not. (Am I misunderstanding what a repository is
here?)

bzr diff
   - 2 branches
or
   - branch
   - working tree
This command can either show the diff between 2 different branches, or
show the diff between the current working tree and its branch.

bzr update
   - branch
   - working tree
This updates the files in the working tree to have all the revisions
in the branch applied. This will happen if someone else has added some
revisions to the branch (via push or something) but the working tree
was not also updated.

# Other questions?
# How do I create a repository after I have already created a branch?
# How do I remove a working tree from a branch that has one?

=========

I understand it is by no means complete, but any comments would be appreciated.

cheers,
Andrew.