user guide help (definitions of terms)

[Neil Martinsen-Burrell]

On 2009-08-04 07:56 , Inky 788 wrote:
> Regarding the [user
> guide](http://doc.bazaar-vcs.org/bzr.dev/en/user-guide/index.html), it
> says that a revision is "a snapshot of the files you're working
> with.". Does that mean the current state of all your
> version-controlled files upon the last commit?

Yes.

> Is there a distinction between the actual state of the physical files
> after a commit and some object in my project's .bzr dir representing
> that state?

There is a distinction in that one is a collection of files and 
directories on your disk and the other is an internal data structure of 
Bazaar that describes the same thing.  If you are getting at whether 
Bazaar stores a revision as a collection of files on you hard disk, then 
the answer is no: revisions are stored in an internal, serialized, 
compressed format.

> Is "snapshot" == "revision"? (I intuitively know what a snapshot means
> (or would seem to mean). So, I suppose "snapshot" implies that you
> made a commit.)

Yes.  Revision is the technical term from version control and snapshot 
is supposed to be a more common word with the same meaning.

> Later in the guide (under "Putting the concepts together"), it goes
> into the working tree, branch, and repository all being in a single
> location. I see what a working tree is (it's my directory of files in
> my project), but I need to first understand exactly what those other
> things are before I can understand them being in separate locations.

A branch is a collection of revisions that are connected together as a 
directed acyclic graph (DAG) by virtue of their parent-child 
relationship.  Each revision in a branch can have one or more parent 
revisions from which it is descended.  (Multiple parents arise as the 
result of merging.)  Commonly, a branch represents the history of a 
single "project".

A repository is a storage location for revisions (in the internal format 
mentioned above).  A separate repository allows for savings in storage 
because different branches may contain the same revisions in their 
history.  This is commonly the case for branches that descend from the 
same parent branch.

> Is a repository physically all the contents of my project's .bzr directory?

No.  A repository is one of the things that is stored within the .bzr 
directory.

> Is a "branch" represented by an actual file inside the .bzr directory?

No.  It is represented by a number of files within the .bzr directory.

> Is a "revision" represented by an actual file inside the .bzr directory?

No.  Revisions are stored in a compressed, serialized format called 
packs.  Each pack can contain multiple revisions.

> What is the thing called that gets me from one revision to another (a
> "changeset" perhaps?) ? Is it represented by a file in my .bzr
> directory?

It is not represented by a file.  Changeset is a commonly used word for 
such an item, but patch, transformation and delta are also used to 
represent the same concept.  In principle, a Bazaar branch is a 
collection of revisions.  The storage of these revisions may be done in 
terms of the transitions between these revisions, but that is an 
implementation detail.

Try the following:

nmb at guttle[/tmp]$ bzr init test_branch
Created a standalone tree (format: pack-0.92)
nmb at guttle[/tmp]$ cd test_branch
nmb at guttle[/tmp/test_branch]$ touch a
nmb at guttle[/tmp/test_branch]$ bzr add
adding a
nmb at guttle[/tmp/test_branch]$ bzr ci -m 'first revision'
Committing to: /private/tmp/test_branch/
added a
Committed revision 1.
nmb at guttle[/tmp/test_branch]$ ls .bzr/*
.bzr/README  .bzr/branch-format

.bzr/branch:
branch.conf  format  last-revision  lock/  tags

.bzr/branch-lock:

.bzr/checkout:
conflicts  dirstate  format  lock/

.bzr/repository:
format  indices/  lock/  obsolete_packs/  pack-names  packs/  upload/

You can see that there are branch, repository and checkout (=working 
tree) subdirectories of the .bzr directory.  Any of these three 
subdirectories may or may not be present in a .bzr directory.  See the 
following:

nmb at guttle[/tmp]$ bzr init-repo test_repo
Shared repository with trees (format: pack-0.92)
Location:
   shared repository: test_repo
nmb at guttle[/tmp]$ ls test_repo/.bzr
README  branch-format  branch-lock/  repository/
nmb at guttle[/tmp]$ bzr init test_repo/branch1
Created a repository tree (format: pack-0.92)
Using shared repository: /private/tmp/test_repo/
nmb at guttle[/tmp]$ ls test_repo/branch1/.bzr
README  branch/  branch-format  branch-lock/  checkout/
nmb at guttle[/tmp]$ bzr reconfigure --branch test_repo/branch1
nmb at guttle[/tmp]$ ls test_repo/branch1/.bzr
README  branch/  branch-format  branch-lock/
nmb at guttle[/tmp]$ bzr checkout --lightweight test_repo/branch1 branch1_work
nmb at guttle[/tmp]$ ls branch1_work/.bzr
README  branch/  branch-format  branch-lock/  checkout/

-Neil