AccuRevDeveloper Training AccuRev, Inc. 300 Baker Ave Concord MA
Course Outline Tuesday Thursday Change Package Concepts “Carry Over” Change Package Modify Change Package Stream Creation for Developers Include / Exclude in Workspace Undoing a Promote Collaboration Bug Tracking /Issues Web UI Documentation / Help • Terminology • Workspaces • Keep • Promote • Update • Stream Browser • Workspace Search Filters • File Status • Overlaps & Merge • Workspace Concepts • Update vs. Populate • History (element & stream) • Diff (element & stream) • Stream Browser Workflow
AccuRev AccuRev Basic Concepts
AccuRev Terminology Repository | Database | Module | VOB Configurations | Branch | “dynamic view” Label | Tag | Baseline | Immutable Writeable files | Private commits Depot Stream Snapshot Workspace Developer Workflow • Keep • Promote • Update • Merge Keep: stores a user’s private changes in the AccuRev depot, but does not make them available to other users Promote: makes changes previously saved with Keep command available to other users Merge: incorporates changes promoted by other users into a user’s private workspace, allowing for conflict resolution Update: incorporates changes promoted by other users into a user’s private workspace
Basic Objects in AccuRev • Stream: a configuration of elements • Dynamic streams: • Contents change as elements are promoted or reverted • Hierarchy of streams defines the promotion-based workflow • Snapshots streams: • Static streams that cannot be moved, renamed, or altered • Contents are immutable • Analogous to labels or baselines
Basic Objects in AccuRev • Workspace: a developer’s private area (sandbox) • Contains two components: • Workspace stream — dynamic stream that tracks the versions of files in the workspace • Workspace directory tree — set of writable files that exist on a client machine • All changes are private (until you promote them) • A workspace can be considered an “instance” of a stream.
Basic Objects in AccuRev • All workspaces are private • Use a workspace to create new versions of the source • User’s principal name appended • Ensures users cannot remove someone else’s workspace • Each user has their own namespace for workspaces • Based on a single backing stream (parent) • Workspaces are populated with the configuration source from its backing stream • Updating a workspace retrieves new(er) versions from any parent stream up to the base stream or a snapshot.
Stream Browser – New Look Depot / Base Stream Dynamic Streams Time Based Stream Active Content Workspace Streams Snapshot Stream Principle Pass-Through Stream Depot
Traditional Stream Browser Workspace Streams Dynamic Streams Time Based Stream Depot / Base Stream Active Content Snapshot Stream Pass-Through Stream Principle Depot
AccuRev Core User Operations
Module Objectives • Identifying your principal name • Creating workspaces • Accessing your workspace • Common developer commands: add, keep, promote and update
Creating Workspaces, Streams, and Snapshots • All of these can be created from within the stream browser • Highlight the stream to be used as a basis • Right-click and select the appropriate menu item • Each require minimal storage on the server New Stream New Workspace New Snapshot
Creating a Workspace AccuRev will automatically append your principal name to the end of the workspace stream name AccuRev can automatically append your workspace name as a new subdirectory to the end of the location Built in EOL feed Finish with defaults (next page)
How to Access Source Code • GUI Menu: • View > Workspaces • File > Open > Workspace • GUI Stream Browser - double-click workspace • CLI: cd into your workspace directory tree • Runaccurev infoto verify workspace context • By default all files are writeable, so no checkout is needed • To work on files From the AccuRev GUI (within a workspace) • Right-click file and select Edit or use the Edit icon • After editing, save and exit the editor • Any IDE can be used to edit source code • All writeable files means never needing to ‘checkout’ first • AccuRev will detect what files have been modified
Add and Keep • The add command • Creates a new ‘real’ version • Creates the initial version of that element in the Workspace Stream • Simply an alias for ‘first keep’ • Directories are also versioned • Adding a new file implicitly creates directory elements as necessary • Do not have to add the directory first • AccuRev does a best guess how the files should be stored in the database • Text or Binary – always parallel mode • Force with accurev add –E text/binary/ptext <file> • Override with accurev keep –E text/binary/ptext <file> • GUI: Advanced button on keep dialog • Can force symbolic links (-s option) • Can exclusively lock file (-E serial option) • Use ptext file type to preserve the contents and prevent CR/LF translation. Ideal for Unicode files or configuration files with embedded binary or multi-lingual data.
Add and Keep • GUI • “Create a new directory” • “Create a new file” • ‘keep’ does the work of ‘add’ • CLI - Command Line • accurev add –c “Good Comment” core.h • accurev add –c “Good Comment” -x
Keep & Promote • Keep – create a new version in your workspace • Creates a new ‘real’ version • Versions are private on your workspace stream • Kept versions are permanently backed up on the server • Other users working from the same basis stream will not automatically see your changes • Promote – make the version active in your backing stream • Creates new ‘virtual’ version • History is fully preserved • The version is now available via inheritance to other streams/workspaces related to the same backing stream
Keep & Promote Select Promote button or from right-click list This is your ‘Active Files’ list, which shows all active elements in your workspace. The Active Files list serves 2 purposes - users can promote their changes from their list and other users can easily see where active files reside
Keep & Promote Switch To Stream File Mode Switch To Stream Transaction Mode Switch To Stream Issue Mode
Update • ‘Update’ retrieves all newer versions from all parent dynamic streams • Algorithm stops scanning for updates at first time rule (i.e. snapshot) or top-most base stream • ‘Update’ will not overwrite any work in progress • Kept files – since your version represents the “latest” file • Modified files – AccuRev does not want to clobber unsaved work • Anchored files – Files that you intend to work on • ‘Update’ only applies to files that are (stale) • If ‘Update’ encounters ‘(overlap) (modified)’ elements, it will fail • Use one of three options • Revert the modified files (throw away your changes) • Keep your modified files (private versioning) • Anchor your modified files (update ignores anchored files) • Set “Update Resolves Trivial Merges” under Tools | Preferences. Update to automatically resolve trivial conflicts with (overlap) (modified) elements. • Force Update with Merge • From CLI • accurev update • accurev update –i <update preview>
Incoming Filter - Update Preview Initiate the Update Update applies to the entire workspace
Conflicts Filter - Update Preview • Merge resolves conflicts (covered later)
Incoming Filter - Update Preview Update applies to the entire workspace Initiate the Update Update started Scanning for recently touched elements- ok Checking touched elements for changes- ok Preparing for update- ok Calculating changes- ok Making 3 changes Removing "gcc/gcc/config/1750a/1750a.c" . Content (5 K) of "gcc/gcc/config/i386/gas.h" - ok Content (1 K) of "gcc/gcc/config/config.h" - ok Update complete.
Workspace Explorer Update applies to the entire workspace Update ‘only’ changes ‘stale/backed’ files Initiate the Update Update started Scanning for recently touched elements- ok Checking touched elements for changes- ok Preparing for update- ok Calculating changes- ok Making 3 changes Removing "gcc/gcc/config/1750a/1750a.c" . Content (5 K) of "gcc/gcc/config/i386/gas.h" - ok Content (1 K) of "gcc/gcc/config/config.h" - ok Update complete.
Update Preferences Update Progress Log Preference Update Merge Preference
Update Options Initiate the Update Update and Force Trivial Merge(s) (overlap)(modified)’s Update with Merge always forces trivial merge regardless of set preferences
Exercise • Create a workspace off of a stream • Add new files to source control • Promote those files into the backing stream • Update workspace to retrieve new elements
Search For Files Searchfor *.h files
Working in the Workspace ‘Open Parent’ tells you what your backing stream (parent) is Workspace Filters The Folders View Workspace Tree location Workspace Stream AccuRev Principal Name
Working in the Workspace The Status column tells you the state for any file in the current directory in relation to your backing stream The Version column gives you the Stream location and version number of the file
Elements & Directory Structure • Files and folders are stored by depot-relative pathname • Every file and folder has an internal unique element id (eid) • Supports tracking history of path and name changes. • The root level directory always has eid 1 • The root level directory is represented as • An element in this directory structure: • is stored as... \.\sources\Project_1\HelloWorld_1\HelloWorld.cpp
Elements & Directory Structure • To see an element’s depot-relative pathname, right-click and select properties: Depot relative path name Element Id
Finding (modified) files in your workspace • A file has a status of (backed) if it is the current version of the file in the parent stream hierarchy • AccuRev uses a combination of timestamp and checksum to determine which files are (modified) • Any file with a newer timestamp is a candidate • A checksum is only performed on candidates (Optimization) • The status of the file will change to (modified)
Hiding (external) Elements • External files can cause slower performance with the AccuRev commands in both GUI and CLI • For example, stat command must unnecessarily interrogate all external files in order to classify them as (external) • Use .acignore file(s) in you workspace • Line delimited list of file or directory patterns including wildcards *.o *.jar *.war build/* • Improves overall performance with the workspace especially for commands that act on the entire workspace • Use to ignore external files that will always remain external but part of the workspace • For example, files generated by a build
AccuRev Resolving Overlaps
Module Objectives • Understand (overlap) status • Closest common ancestor algorithm • AccuRev’s graphical merge tool • Merge history • Namespace overlaps • Registering a different merge tool
Merging (overlap) status • An (overlap) occurs when you modify or keep a file that has also been changed in the backing stream • Someone else has done a promote of the same file before you • Version in your workspace has an ‘older’ ancestor • The file’s status will include (overlap) and be highlighted • A merge is required before you can promote the file
Merging Algorithm • AccuRev’s merge algorithm for text files considers three versions: • contributor 1: backing stream version (left pane) • contributor 2: your version (right pane) • “common ancestor” version (center pane) • Changes or Conflicts? • If a section of text was changed by just one contributor, the change is automatically accepted • If both contributors changed the same section of text in different ways, there is a conflict. You have to resolve the conflict manually.
Running the Merge Command Trivial merge shortcut Keep or Review merge Merged Result… still in Workspace Stream Backing Stream Version Common Ancestor Workspace Stream File
Running the Merge Command Navigating thechange sections Resolvingconflicts Previous Use Only My Changes All Changes Conflicts Last Search Their Changes Revert All Of My Changes First Next My Changes Current Take My Changes Take Their Change Take Common Ancestor Change
Finishing a Merge Keep Results and Close
Exercise • Create an overlap situation with your neighbor • Modify & promote the same piece of code & assign to same Change Package • Resolve this overlap using the merge operation
AccuRev Advanced Workspace Operations
Module Objectives • Private sandbox concepts • Revert file changes • Rename and move elements • Populate missing elements • Remove files from the directory tree • Filter rules to include / exclude elements
Private Sandbox Concepts • All workspace commands are relative to last Update • The update command only retrieves newer versions of files from the parent stream hierarchy • If a newer file version exists since your last update, that new version will not be considered • Examples: Revert, Purge, Populate, Diff • Guarantees consistency of workspace! • Exception: Diff against backed • Compare local file with the newest backing stream version • Use Diff against basis to compare since last update