AccuRev Developer Training

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

2. 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 Course Outline

3. AccuRev Basic Concepts

4. AccuRev Terminology Developer Workflow • Keep • Promote • Update • Merge  Repository | Database | Module | VOB  Configurations | Branch | “dynamic view”  Label | Tag | Baseline | Immutable  Writeable files | Private commits Depot Stream Snapshot Workspace 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

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

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

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

8. Basic Objects in AccuRev Workspaces Base Stream Snapshot Dynamic Streams Pass-through Streams Principal Depot Name

9. AccuRev Core User Operations

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

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

12. Creating a Workspace • Steps for creating a new 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 Finish with defaults (next page) Built in EOL feed

13. How to Access Source Code • GUI: View  Workspaces or File  Open  Workspace • GUI: Stream Browser  double-click on workspace open • CLI: cd into your workspace directory tree • Execute ‘accurev info’ to verify workspace existence • By default all files are writeable, so no checkout is needed • To work on files From the AccuRev GUI (within a workspace) • Right-click on a 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

14. 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 by “accurev add –E text/binary/ptext <file>” • Override by “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.

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

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

17. Keep & Promote Pending Filter Select Promote

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

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

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

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

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

23. Update Options (cont) 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

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

25. Search Results Searchfor *.h files In selected folder

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

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

28. Status Summary Folder View Search View (filters)

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

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

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

32. Hiding (external) Elements • External files can cause slower performance with the AccuRev commands in both GUI and CLI • e.g. statcommand must unnecessarily interrogate all external files in order to classify them as (external) • UseACCUREV_IGNORE_ELEMS environment variable • Space delimited list of file or directory patterns incl. wildcard • e.g. 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 (e.g. generated files) • .acignorecan be created and used per directory (similar to variable above)

33. Resolving Overlaps

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

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

36. Merging Algorithm • AccuRev/CM’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.

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

38. Running the Merge Command Merged Result… still in Workspace Stream Trivial merge shortcut Keep or Review merge Backing Stream Version Common Ancestor Workspace Stream File

39. Running the Merge Command Navigating thechange sections Resolvingconflicts Use Only My Changes Previous Search All Changes Conflicts Their Changes First Last Revert All Of My Changes Next My Changes Take My Changes Take Their Change Take Common Ancestor Change

40. Finishing a Merge Keep Results and Close

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

42. Advanced Workspace Operations

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

44. Private Sandbox Concepts • All wspace 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 • e.g. revert, purge, populate, diff • Guarantees consistency of workspace! • Exception: Diff-against-backed will compare the local file with the newest backing stream version. Use diff-against-basis to compare since last update.

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

46. Reverting from the CLI • Revert to Backed: use the “purge” command • $ accurev purge foo.c • purge will always “revert to backed” and rollback all changes including any kept versions • Revert to Most Recent: use the “populate” command • $ accurev pop –O foo.c • Populate will always 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

47. Changing an Element’s Namespace • AccuRev supports rename, copying, & 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>

48. Populate – Replacing (missing) Files • Populate • Populates (missing) files on disk • Retrieves the version from the last update • Use to recover an accidental OS file-system delete • Default is to refuse to do anything if it would overwrite any file in the workspace • GUI: Right-click file  populate • CLI: • $ accurev pop <filename> (single file) • $ accurev pop –R –O . (recursive/overwrite/all files)

49. Populate – Replacing (missing) Files

50. Update vs. Populate – IMPORTANT! • Update • does not restore (missing) files • Retrieves newer versions for (stale) files in workspace [will retrieve file if it has (missing )(stale) status] • Update only retrieves newer versions from the backing stream into your workspace • Populate • Used to restore (missing) files from disk • Will not always get you the latest version • The algorithm to populate is similar to revert / purge. • Gets the latest version of a missing file based on the last time the workspace was updated