AccuRev Basic User Training Version 4.5

1. AccuRevBasic User TrainingVersion 4.5 AccuRev Proprietary and Confidential Information

2. Outline This training course contains the following modules: • AccuRev Concepts • Basic User Operations • Workspace “Under the Hood” • Resolving Overlaps—Merge Tool • Advanced Workspace Operations • Information Gathering in AccuRev • Stream Browser Basics • AccuWork

3. AccuRev ConceptsVersion 4.5 AccuRev Proprietary and Confidential Information

4. Module Objectives At the end of this module, you will be able to: • Understand the concepts of TimeSafe technology and atomic transactions and their benefits in software configuration management. • Define the basic objects in AccuRev and what a stream hierarchy is.

5. TimeSafe technology and atomic transactions • TimeSafe Technology means: • Every operation is stored as a recorded transaction with a corresponding date and time. • There is no way to delete any transaction in the repository; the history is always fully preserved. • Benefits: • Absolute reproducibilityof the code base. • Consistent namespaceover time even if you delete, rename, or move an element.

6. TimeSafe technology and atomic transactions • AccuRev uses atomic transactions—you perform an operation on a set of elements at one time. • Transactions are “all or nothing” and cannot be interrupted in progress. • If, for some reason, a transaction does not complete, it is treated as if it never started. • Benefits: • Element versions with interdependencies are delivered together. • Data integrity is preserved. • No more broken builds!!

7. Basic objects in AccuRev • Depot: version controlled storage for a directory tree (files and directories) • Anything you want versioned lives in the depot • Text files • Binary files • Directories • Any collection of code that is shared among projects is stored in a singe depot.

8. Basic objects in AccuRev • Stream: A particular configuration of the code base • Dynamic streams: • Can change over time as elements are added, removed, or changed. • The base stream is the highest node in the stream hierarchy—it has the same name as the depot. • Snapshots: • Static streams that cannot be changed—they are frozen in time. • Analogous to labels.

9. Basic objects in AccuRev • Streams are organized into a stream hierarchy • Dynamic stream, snapshots, and workspaces are all part of the hierarchy. • This allows for staging and separation in the development process. • Changes to the code base flow right-to-left by promote operations. • Changes flow left-to-right through dynamic streams by inheritance. • The stream browser gives you a graphical view of the stream hierarchy. The stream hierarchy can be changed dynamically from within the stream browser.

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

11. Basic workspace concepts • All workspaces are private • Use a workspace to create new versions of the source • All workspaces have the user’s Principal name appended to the end of the workspace name • Based on a single Backing Stream (parent) • Workspaces are populated with the source from its Backing Stream

12. Workspaces Dynamic streams Base stream Snapshots Depot name Principal name Basic objects in AccuRev

13. Basic User OperationsVersion 4.5 AccuRev Proprietary and Confidential Information

14. Module Objectives This module will cover the following: • Identifying your principal name • Creating workspaces • Accessing your workspace • Common developer commands: add, keep, promote and update

15. AccuRev Principal Name • Your Principal name is created for you by the AccuRev Admin. • Used to track all operations in AccuRev • By default, your operating system login name is used as the principal-name for AccuRev operations • Can override with: • GUI: Tools  Login • CLI: set the ACCUREV_PRINCIPAL environment variable

16. Creating Workspaces, streams and snapshots • All of these can be created from within the stream browser. • To create a stream, workspace, or snapshot, highlight the stream to be used as a basis, then right-click and select the appropriate menu item. New Stream New Workspace New Snapshot

17. Creating a Workspace AccuRev gives you the option to create a new subdirectory with the name of the workspace • Steps for creating a new workspace: 1 2 3 4 AccuRev will automatically append your principal name at the end of the workspace name Built in EOL feed

18. Accessing your workspace • From the gui, use View  Workspaces or File  Open  Workspace • From the Stream Browser, double-click on your workspace to open • From the cli, cd into your workspace directory tree • 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

19. Common commands: Add • The add command • creates a new element on the server • creates the initial version of that element in the Workspace Stream • 2-stage commit with add • Private in the workspace “only” (kept version) • Promote to share the files with other workspaces • Directories are also versioned • Adding a new file implicitly creates directory elements as necessary • Do not have to add the directory first

20. Common commands: Add • AccuRev does a best guess how the files should be stored in the database • Text • Binary • There are times when you will want to override this • To override this behavior • <accurev keep –E text/binary>

21. Common commands: Add Single Add command Single comment Single transaction 100’s or 1000’s of files External Filter recursive for whole Workspace

22. Common commands: Keep • AccuRev has a 2-stage checkin • 1st stage of the checkin - keep • 2nd stage of the checkin - promote • Keep--create a new version in your workspace • Known as a ‘real’ version • Versions are ‘privately’ versioned 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

23. Common commands: Promote • AccuRev has a 2-stage checkin • 1st stage of the checkin - keep • 2nd stage of the checkin - promote • Promote--make the version active in your basis stream • Like kept versions • History is fully preserved • You can revert to ‘any’ past version of a file • The version is now available to other people working from the same basis stream.

24. Select Promote Searches View Kept Filter Common commands: Promote

25. Common commands: Promote Select Promote This is your ‘default group’ which shows all active elements in your workspace. The default group serves 2 purposes--users can promote their changes from their default group and other users can easily see where active changes reside

26. Common commands: Update • Use ‘update’ to pull/get the latest changes • ‘update’ will not ‘overwrite’ any work in progress • Kept files • Modified files (see below) • Anchored files • ‘update’ only applies to files that are ‘stale’ • If ‘update’ encounters ‘modified’ files... it will error • Use one of three options • Revert the modified files • Keep your modified files (private versioning) • Anchor your modified files (update ignores anchored files) • CLI Commands: • accurev update • accurev update -i

27. Common commands: Update The Update command Update applies to the entire workspace Update ‘only’ applies to ‘stale/backed’ files The files that are updated are shown in the update log.

28. Common commands: Update Use Update Preview to see what files ‘would be’ updated if an ‘update’ is run ‘backed’ status

29. Workspace “Under the Hood”Version 4.5 AccuRev Proprietary and Confidential Information

30. Module Objectives This module will cover the following: • Understanding the different filters and window panes within a workspace. • Understanding the different element statuses • Distinguish between real and virtual file versions • Ignoring external files

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

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

33. Status Descriptions • Each element has a status associated with it, below is a list of each value and description. (Backed) An element has “backed” status in a workspace or stream if it is not currently active there. This means that the workspace/stream inherits the version of the element that is currently in the workspace/stream’s parent stream (also called the backing stream). (External) The file or directory has not been placed under version control. (It’s in the workspace tree, but not in the workspace stream.)

34. Status Descriptions (Kept) Refers to a version that has been created with a keep operation. (Modified) A file element has “modified” status in a workspace if the file’s contents have changed since the last time the user kept a new version of the file or update’d the entire workspace. AccuRev uses a combination of timestamp and checksum to determine which files have been modified.

35. Status Descriptions (Member) An element has member status in a workspace or stream if one of its versions is in the default group of that workspace or stream. An element with member status is said to be active in that workspace or stream; otherwise, it’s passive. The following commands "activate" an element in the current workspace: anchor, co, revert, keep, move, defunct, undefunct. (Stale) An element has “stale” status in a workspace if it is not currently active in the workspace, but a new version of the element has entered the parent stream. An update operation will overwrite the stale version with the parent stream’s new version.

36. Status Descriptions (Overlap) Version X, in a workspace or stream, has “overlap” status if the parent stream’s current version of the element contains changes that are not reflected in version X. Such a version cannot be promoted to the parent stream; the user must create a new version with a merge operation, combining version X with the parent stream’s version. The new, merged version can then be promoted.

37. Status Descriptions (Missing) This status indicates you deleted the file from your workspace using on operating system delete command. (Stranded) An element has “stranded” status in a workspace or stream if it’s currently active, but there is no pathname to the element. This occurs when the element’s directory (or a higher-level directory) is removed from the workspace or stream.

38. Status Descriptions (link) An element whose content is a reference to a file/directory element (or to another file/directory link). The link object behaves much like a standard file/directory, but actually provides access to another file/directory element (the "target" of the link) in the same depot. (xlinked) An include/exclude mode operation ("Include from Stream") that includes an element in a workspace or stream, specifying an alternative backing stream for that element.

39. Search Filters • These filters are located in the lower hand corner of your workspace or stream. • Runs an operation that determines all the elements in a workspace or stream that have a particular status.

40. Search Filters • Pending - Selects elements whose status includes either (modified) or (kept). These are elements that have had an AccuRev content or namespace change. • Modified – Selects files whose status includes (modified). This indicates a content change that has not yet been preserved with Keep (but may have followed a previous Keep). • Kept – Selects files whose status includes (kept). These are files whose content changes have all been preserved with Keep, or elements with namespace-level changes (Rename or Defunct command).

41. Search Filters • Non-member –Selects files whose status includes (modified) but not (member). These are files that have content changes, but are not in the workspace’s default group. (They have not been activated with a Keep or Anchor command since the file’s last update or promotion.) • Default Group – Lists the set of elements that are currently active in a particular workspace or stream. This will include all elements whose status contains (member).

42. Search Filters • Overlap – Selects the subset of Pending files whose status includes (overlap) — the current version in the parent (backing) stream is not an ancestor of the version in your workspace version. This means there might be content or namespace changes in the backing stream version that are not present in your workspace version. You need to perform a Merge with the backing stream version before you can Promote your workspace version. • Deep Overlap - Reports (overlap) files in the current workspace or stream. Also reports (overlap) versions in the parent stream, in the grandparent stream, ... all the way up the depot hierarchy.

43. Search Filters • Mod. in Def. Grp. – Selects elements whose status includes both (modified) and (member). This is the intersection of the sets of files selected by the Modified and Default Group search criteria. • External – Selects files and directories that exist in the workspace tree (local file system), but have never been placed under version control with the Add command.

44. Search Filters • Missing - Selects elements that should be present, but aren’t. That is, there’s a version of the file or directory in the workspace stream, but the file or directory was removed from the local file system (the workspace tree) by an operating system command or some non-AccuRev program. • Stranded - Selects the elements in the default group of a workspace or dynamic stream that have become stranded. A default group member becomes stranded when there is no pathname to the element in that workspace or stream.

45. Search Filters • Defunct - Selects the elements in the default group of a workspace or dynamic stream whose status is (defunct).

46. Depot database TRAINING_QA version TRAINING_int version File storage area on server New Workspace version Real and virtual file versions • Real Version—file version created in a user’s workspace • Creates a new version object in the depot’s database • Creates a new file in the depot’s file storage area • Virtual Version—file version in a dynamic stream or snapshot • Pointer to a real version stored in the depot’s storage area • Creates a new version object in the depot’s database

47. External files • External files can cause slow performance with the AccuRev filters (both gui and cli) • Use ACCUREV_IGNORE_ELEMS • Will improve overall performance with the workspace • Commands that act on the entire workspace • To ignore external files that will always remain external can be directory specific or based on extension (using wildcards).

48. Resolving Overlapsv4.5 AccuRev Proprietary and Confidential Information

49. Module Objectives At the end of this module, you will be able to: • Define the closest common ancestor algorithm for merging. • Use the graphical merge tool to merge text files.

50. Merging (overlap status) • Sometimes, you will modify or keep a file that has also been changed in the backing stream • Someone else has done a promote of the file before you • Version in your wspace has an ‘older’ ancestor • The file’s status will include overlap and highlighted • A Merge is required before you can promote the file to the backing stream