What is a one-sentence explanation of how Accurev works?

Question

I understand git, Subversion, CVS and a myriad of other source control systems.

I've begun using Accurev and it confounds me.

I believe I need to form a mental model that relates it to other SCM's. Ideally relative to git because I understand git the best.

I would explain git as "a directed graph of commits where a commit is a diff, a parent (or parents) hash, and a hash of itself." You can easily move on from there to explain concepts like rebase and what merges really are, fast-forward vs. actual merges and so on. I've found it easy to teach new users complex git concepts in about 15-20 minutes.

I would really like to understand Accurev at that level. So...

What is the once sentence abstraction of how Accurev works that makes it possible to explain how it behaves?

Some examples of questions I would like my mental model to answer:

• What happens when I "keep" some files and then "promote" them?
• What if I don't promote the same files as I've just kept?
• 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.
• 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.

Answer 1

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...

Answer 2

Since several others have attempted to answer your direct question - with Dave's answer being the most concise and accurate - I'll take a stab at your bullets:

• What happens when I "keep" some files and then "promote" them?

  A Keep of a file will create a new version of that file, still private to your workspace. Excellent for autonomous coding, creation of diversion points, just plain private development. You can at any time in the future revert to any previous kept version of a file, either from yourself or from any other contributor. When you are comfortable with the version you have current (you've compiled, built, tested, whatever), you can Promote it into your parent stream, thus exposing others to your version without the risk of breaking things like you can when you commit at check-in time.

• What if I don't promote the same files as I've just kept?

  Again, total workspace autonomy. You can work on 100 files at once if you're the kind of developer who can keep track of what you're doing. You can Promote none, all, one, some - doesn't really matter - and you can do this on your timeline.

• 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.

  Not sure I know specifically what you're referring to here. When you run an Update in an AccuRev workspace, it will never overwrite your work-in-progress. If you're working on elements that would otherwise be inherited - meaning the content in your parent hierarchy has changed - they will be listed as (overlap) in your workspace. Again, you can choose when to perform the merge, and still Update other changes from above, and even continue working on the file in conflict. The merge happens in the workspace, as opposed to at Promote time, giving you the option to once again compile, build, test the result prior to delivering elsewhere.

• 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.

  A Diff against Basis will show you how the version in your workspace compares to the version that you last inherited from an update or workspace creation. A Diff against Backed will show you how your version compares to what is currently in the parent stream. So if someone has promoted changes to that file while you still have yours in progress, Diff against Basis will only compare against your original while Diff against Backed compares against the new content in the parent. Incidentally, in the History -> Browse Versions view you can diff any two versions of a file against each other.

Hopefully this provides a bit of perspective about your specific questions.

Answer 3

I would explain git as "a directed graph of commits where a commit is a diff, a parent (or parents) hash, and a hash of itself."

A git repository is, FWIW, a forest of history trees, of which the commit leaves are (commit metadata plus) trees of directories and files. No diffs, not in Git, at least when it comes to the concept. If the storage engine happens to do deltification, that is another story.

As for AccuRev, I watched their 2-minute introductory video (link intended for reference, not advertisement), and it looks pretty much like your average time-arranged SCM history tree (branches). The items with the watery-wave icon are branch heads, and the yellow folder-like thing is a working copy. When the presenter moves the working copies, he seems to be doing a rebase of all his subordinate's working copies (evil that! just think about the merge conflicts!). The icon with three green dots (the issue list) would be a commit list then that is cherry-picked when you copy it.

In one sentence: nothing you don't know already through prior experience to cvs/svn/git — move along I'd say.

Answer 4

Accurev is derived from ClearCase and takes after ClearCase UCM streams.
(The Accurev model has some similarities with UCM, and well-received by former ClearCase users)

A Stream is a configuration, that is the list of labels (for read-only components) or files (for writable components) you need to work (compile, and/or test, and/or debug, ...).

That is why Accurev is presented as a Stream-Based Architecture for SCM.

If has one private stream per developer (the workspace stream) from which you can promote to more common streams. Each promotion update the configuration (which again is just the list of what you need to work) of the parent stream.

Answer 5

I'll give you the technical (non-biz) single sentence based on the style of your Q:

AccuRev takes an object oriented approach to modeling s/w configurations. It's that simple and it's awesome! Especially if you're modeling a workflow or better yet, setting up continuous delivery (another topic). But I've seen so, so many people dismiss this powerful technology and data model approach because they cannot look beyond traditional 'branches' ala cvs, svn, p4, cc, ad infinitum. The best analogy would be to compare a series of AccuRev streams to rules in a config spec in clearcase... (note: it's just an analogy) but much more powerful as streams are first class entities that maintain time-based configuration and history.

The trick to understanding AccuRev is that while any given "stream" -represents- a full configuration (i.e. you can check it out), the actual contents of that stream are determined dynamically by aggregating any local file/dir changes, any changes from the parent, on up the tree to the very top where the rest of the files are gathered. So anytime you see a 'tree' of streams, they are NOT branches... rather a series of inheritance based configurations where the top stream is like the 'superclass' and all [grand]children are [sub]subclasses. New file/dir changes are promoted up the tree as they go from development, integration, QA, etc.

HTH _ dave