Disclaimer: The source control system I understand best is SVN. So that colors my usage of terms such as repo, checkout, etc. Also, I use Accurev on a daily basis, but I tend not to venture far from the core concepts that I feel I have a firm grasp of.
One sentence (with an asterisk): Accurev is a time-ordered repository that keeps a revision history of files changed for each stream/workspace, and allows you to develop different versions of the code (in streams) while each stream is transparently updated with the core code from its parent and child* streams.
(*) A stream is updated by a child stream only once a child stream promotes changes into the parent stream.
The main benefit of Accurev is the ability to maintain different versions of code easily. If you want to grasp it, I wouldn't look for quick abstractions or terms redefined in language you're familiar with. I'd look for examples and a gentle explanation of terms as they arise. Unfortunately, I only know what I need to know, but I'll give it a shot...
(I'll get to workspaces later. Don't worry about them at this point.)
When you create one stream parented off of another, it's like you did an SVN branch to create the child stream, but the (wonderful) difference is that SVN merges are taken care of for you each time you update the parent or child stream (or you are alerted when a conflict exists and you need to resolve it manually).
Let's say you start off with a stream, CompanyStream. Your codebase is managed by that stream, and it has a history of changes you've made to files. You then decide to create two child streams below that, ChildStream1, ChildStream2. Any changes made to files in CompanyStream will trickle down to both child streams, so they always have the latest code that they inherited from CompanyStream. (Inheritance of revision changes is a staple concept in Accurev.) Meanwhile, you're doing development specific to one vendor in ChildStream1, and changes specific to another vendor in ChildStream2. You can selectively decide which code from ChildStream1 and 2 get promoted to CompanyStream, but any changes made in CompanyStream should be things that you want to appear in both child streams. If you promote code from ChildStream1 into CompanyStream, then those changes will appear in ChildStream2 once it does an update (because again, it inherits CompanyStream)
The stream visualization would look like this:
CompanyStream --
|-- ChildStream1
|-- ChildStream2
Accurev Overlap = A file in a parent stream has been modified since you've Updated your stream. Visualize the parent stream as being above you (that's how it'll be displayed in the client), and that stream has progressed horizontally so that it overlaps the point in time that you're at.
Quick mapping of SVN to Accurev concepts:
SVN Checkin - Promote
SVN Checkout - Anchor (Anchoring something makes it a WIP - Work In Progress)
SVN Update - Update
Accurev Workspaces
I haven't mentioned workspaces yet. A workspace represents the code on your hard drive. A workspace is similar to a stream in that it can have a history, and it can keep track of changes you have made. (This is what a Keep does -- it stores a snapshot of the files you specify during that Keep operation in your workspace's history. You can revert to those file snapshots at any time. As a result, a workspace can also be viewed as your own personal, private stream, which is a record of changes made to the code within.)
Streams are abstract concepts that represent revision changes, and a history of what has happened. Streams and workspaces inherit the code from their parent streams. Unlike streams, however, workspaces cannot have child streams or child workspaces. Workspaces are like leaves on a tree; streams are like branches.
- What happens when I "keep" some files and then "promote" them?
You promote to a stream. You Keep to a workspace. Promoted changes are visible to all who can see the stream. Kept changes are visible only to you, the owner of the workspace.
The Kept files will have snapshots in your workspace (in case you ever want to revert to them). The promoted files will have snapshots (so to speak) in the stream you promoted them to. The big difference is that the promoted changes will trickle down to any streams or workspaces that inherit that stream.
- What if I don't promote the same files as I've just kept?
Then they will only be in your workspace. Also, I believe that when you do a promote, Accurev does a keep first (so you have a record of the file change in both your workspace and the stream to which you're promoting).
- Why does history sometimes get mis-attributed when non-conflicting (a.k.a. overlapping) updates happen? This, in particular, is reminiscent of a failure mode of Subversion that, from the basic explanations I've heard, I don't believe should exist with Accurev.
Can you give an example? My grasp of Accurev's file versioning is a little fuzzy. I believe that the version attribute will be assigned by the workspace or stream from which the most recent change was promoted (not Kept). It's possible that there are some stream inheritance relationships that cause a file to have attributes that don't seem correct until you trace it out.
- Why do diffs almost never contain what I expect them to? I believe what's happen is that diff against basis is showing me the diff against the current (moving) parent stream but what I really want is only to see changes I've made since I've last updated.
Then do a diff against "Backed," not against Basis.
The simple configuration that works for me is: I always create my own personal, private stream off of some public development stream. Then when I make changes I want to checkin (or be able to revert to), I promote to my own stream. I keep working in my workspace, and if I want to diff my workspace against what I've done previously or what's going on above me (changes that other people have made), I do a diff against Backed.
Sorry this is so long. Hopefully it helps...
