AccuRev Developer Training

2. AccuRevDeveloper Training AccuRev, Inc. 300 Baker Ave Concord MA

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

4. AccuRev AccuRev Basic Concepts

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

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

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

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

9. Stream Browser – New Look Depot / Base Stream Dynamic Streams Time Based Stream Active Content Workspace Streams Snapshot Stream Principle Pass-Through Stream Depot

10. Traditional Stream Browser Workspace Streams Dynamic Streams Time Based Stream Depot / Base Stream Active Content Snapshot Stream Pass-Through Stream Principle Depot

11. AccuRev Core User Operations

12. Module Objectives • Identifying your principal name • Creating workspaces • Accessing your workspace • Common developer commands: add, keep, promote and update

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

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

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

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

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

18. Keep

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

20. Keep & Promote

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

22. Keep & Promote Switch To Stream File Mode Switch To Stream Transaction Mode Switch To Stream Issue Mode

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

24. Incoming Filter - Update Preview Initiate the Update Update applies to the entire workspace

25. Conflicts Filter - Update Preview • Merge resolves conflicts (covered later)

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

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

28. Update Preferences Update Progress Log Preference Update Merge Preference

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

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

31. Search For Files Searchfor *.h files

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

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

34. Status and Filter Summary

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

36. Elements & Directory Structure • To see an element’s depot-relative pathname, right-click and select properties: Depot relative path name Element Id

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

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

39. AccuRev Resolving Overlaps

40. Module Objectives • Understand (overlap) status • Closest common ancestor algorithm • AccuRev’s graphical merge tool • Merge history • Namespace overlaps • Registering a different merge tool

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

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

43. Conflicts Filter - Running the Merge command

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

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

46. Finishing a Merge Keep Results and Close

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

48. AccuRev Advanced Workspace Operations

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

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