AccuRev Developer Training

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

3. Course Outline • Creating Workspace • Keep • Promote • Update • Workspace Search Filters • History (element & stream) • Diff (element & stream) • Stream Browser Workflow • Change Package Concepts • “Carry Over” Change Package • Modify Change Package • Stream Creation for Developers • Include / Exclude in Workspace

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. Basic Objects in AccuRev Workspaces Base Stream Snapshot Dynamic Streams Pass-through Streams Depot Name Principal

10. AccuRev Core User Operations

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

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

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

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

15. Add • 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 add or 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.

16. Add External Filter recursive for whole Workspace Single Add command Single comment Single transaction 1, 100’s, or 1000’s of files

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

18. Keep & Promote Select Promote Pending Filter

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

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

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

22. Update Initiate the Update Update ‘only’ changes ‘stale/backed’ files Update applies to the entire workspace

23. Update Preview and Preferences Action to be performed Update Merge Preference Update Progress Log Preference Update Preview Search Filter

24. Update Options Initiate the Update Preview all (stale)’s Update and Force Trivial Merge(s) (overlap)(modified)’s Update with Merge always forces trivial merge regardless of set preferences

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

26. Search Results Searchfor *.h files Limits to current folder. Unclick to search full Workspace contents

27. Working in the Workspace ‘Basis’ tells you what your backing stream (parent) is The Folders View The Searches View Workspace Tree location Workspace Stream AccuRev Principal Name

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

29. Status and Filter Summary

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

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

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

33. 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 ACCUREV_IGNORE_ELEMS environment variable • Space delimited list of file or directory patterns incl. wildcard ACCUREV_IGNORE_ELEMS=*.o *.jar *.ear *.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 • .acignore can be created and used per directory (similar to variable above)

34. AccuRev Resolving Overlaps

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

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

37. Merging Algorithm • AccuRev’s merge algorithm for text files considers three versions: • contributor 1: backing stream version • contributor 2: your version • “common ancestor” version • 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.

38. Running the Merge command All overlap files in the workspace in relation to its backing stream Invoke merge tool to merge changes

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

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

41. Finishing a Merge Keep Results and Close

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

43. AccuRev Advanced Workspace Operations

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

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

46. “Revert To…” • Reverting will rollback to a previous version • Two revert options in the GUI • Most Recent Version (last kept version) • Backed Version (since last update)

47. Reverting from the CLI • Revert to Backed • use the purge command $ accurev purge foo.c • purge will always Revert to backed, rollback all changes including kept versions • Revert to Most Recent • use the populate command $ accurev pop –O foo.c • populate will not retrieve the most recent version • Revert to Any Version • Use checkout” with specific version $ accurev co –v “53/5” foo.c • checkout has nothing to do with locking, unlike other systems • History of checkout is preserved; see version browser for file

48. Element Namespace Changes • AccuRev supports rename, copy and move • Element history is fully preserved • Restore to any previous version of a file, even if the name has changed or its location has been moved • Must be done in AccuRev $ accurevrename <oldname> <newname> $ accurevmove <oldpath> <newpath> $ accurevmv <oldpath> <newpath>

49. Populate • Replaces (missing) files on disk • Retrieves the version from the last update • Used to recover an accidental OS file-system delete • Default is to refuse to do anything element is already in the workspace • GUI: right-click File > Populate • CLI: $ accurev pop <filename>(single file) $ accurev pop –R –O . (recursive/overwrite/all files)

50. Populate