Concepts and Overview

Git is popular with many developers for its simplicity and speed. However, professional enterprises need more control and scalability for their large investment in intellectual property. Many developers prefer AccuRev’s interface; release engineers require AccuRev’s stream architecture for capturing the exact revisions needed for a build environment, and managers require AccuRev’s TimeSafe auditablility and its ACL-based security.

How does an organization meet these differing requirements and preferences?

AccuRev GitCentric provides enterprises with the solution: developers who embrace Git can continue using Git the same way they do today, while other development groups, release and test engineers, and managers who require AccuRev’s power, functionality, and security can work together via the AccuRev GitCentric interface. GitCentric also incorporates the open source Gerrit Code Review package for optional code review functionality.

In the most basic terms, Git repository branches are mapped to AccuRev streams, so that the two stay in sync. Changes to the Git repository get transmitted to the AccuRev depot, and changes in the AccuRev depot get transmitted to the Git repository. Updates happen automatically. Git users do not need change their work practices for the AccuRev environment, since GitCentric is transparent to them.

GitCentric functionality applies to two audiences:

• Regular users can register themselves, maintain their preferences, and (if implemented at their site) access the optional code review functionality.

When using GitCentric, the documentation you need depends on what component you are using.

• For GitCentric administration and use, you’re already here: the AccuRev GitCentric User’s Help (available in both PDF and HTML) from the GitCentric web interface:

• For Git documentation, you can use git help from the command line. You can also use a search engine to locate several good tutorials and discussions available on the web.

• For AccuRev documentation, access the complete documentation set in HTML and PDF from the Help Contents & Manuals menu in the AccuRev GUI:

The AccuRev Installation and Release Notes are available from the Micro Focus Product Documentation page here: http://supportline.microfocus.com/productdoc.aspx

Because GitCentric spans the environments of AccuRev, Git, and Gerrit Code Review, you may encounter some conflicts or overlaps in terminology. For example, Gerrit Code Review often uses the term “project” to refer to a repository. AccuRev uses the terms “repository” or “repo” when referring to a repository, and reserves the term “project” for referring to specific Gerrit functionality, or when referring to some kind of planned or defined undertaking. See Appendix D GitCentric Glossary for definitions of terms used in GitCentric.

The following diagram shows the basic configuration of a very simple GitCentric environment where the Git repository, Tomcat web server, and AccuRev server with databases for both GitCentric and AccuRev reside on the same server:

In this simple configuration, the GitCentric server hosts:

• an AccuRev server which includes a PostgreSQL database, and which functions as both the GitCentric AccuRev server and a production SCM AccuRev server with a trigger (server_master_trigger) to notify GitCentric of changes in AccuRev

• a GitCentric installation directory, which generally (but not necessarily) contains a storage area for one more Git repositories which include triggers (pre-receive and update) and configuration files. (The triggers are Git hooks that get copied to your GitCentric repos and which help keep AccuRev synchronized with your repo. Search the web for more information about Git hooks.)

In this simple environment, the AccuRev server hosts both the AccuRev depot containing the streams that are mapped to branches in the Git repo, along with the database server for both GitCentric and AccuRev, and another trigger that keeps your repo synchronized with AccuRev. In fact the Tomcat server is also a part of the AccuRev installation, under the <ac_home>/WebUI directory.

For the sake of this discussion, we will assume the simple configuration in which the Git repo and the AccuRev server (which includes the Tomcat server, the GitCentric database, and the production SCM database) all reside on the same machine.

Regardless of the complexity of the installation, the basic GitCentric process remains the same: Git users push and pull files between their local Git repos and the GitCentric Git repo. AccuRev users promote and update files between their workspaces and the AccuRev Server. And GitCentric keeps the branches in the Git repos synchronized with streams in the AccuRev servers.

All GitCentric users -- whether they are Git developers or GitCentric administrators -- use GitCentric to self-register their accounts and their SSH public keys, and to maintain their account preferences. If code review is configured, then Git developers will also access Gerrit Code Review through GitCentric.

However, many GitCentric features are geared toward administrators so that they configure AccuRev servers and their mappings to Git repository branches.

A GitCentric administrator uses the GitCentric GUI (and optionally the GitCentric CLI commands) to configure the mapping between Git branches and AccuRev streams. A Git repository (“repo”) is associated with a single AccuRev server, and with an AccuRev username (the “service account”) for performing GitCentric administrative tasks. Once this association is defined, a GitCentric administrator can proceed to map Git repo branches to AccuRev streams on that server. The directory within a stream that is mapped to a Git branch is called the “mount point”.

After the mapping has been done, the GitCentric bridge webapp uses triggers to automatically keep the Git repo and the AccuRev depot in sync, while the GitCentric GUI gives you the ability to create repos, map branches to streams, set ACLs, etc.

Note that you can have multiple GitCentric AccuRev user accounts:

• “service account” users, accessed internally by the GitCentric bridge, for automatically syncing the Git repos and their mapped AccuRev streams

Service account users must be defined (either as an individual user, or as a group) in the AccuRev server acserver.cnf file(s), using the ASSIGN_USER_PRIVILEGE setting in AccuRev 5.4 or later. Note: Best practice is to assign this to a group, so different members of the group can have different access rights. For example, one member of the group might be from an off-shore organization, with different access rights than another member of the group.

Regardless of how many Git repositories or AccuRev servers you configure, when you associate a repo with a server, you map them at the branch and stream level: a Git branch is mapped to an AccuRev stream.

• You cannot map a Git branch to the root stream in an AccuRev depot. (If you need to do this, simply create a new stream off the root, and then map to that.)

If you push a file to the repository and it would require merging with the version of the file on the mapped AccuRev stream, GitCentric cancels the push and informs the user that he or she must pull the latest changes, merge and retry the push, the same way Git always handles these situations.

When you first map a Git branch to an AccuRev stream, you can specify whether the files in Git or on AccuRev take precedence.

Since AccuRev streams inherit versions from their backing streams, it is important to remember that if any element is promoted to a backing stream above a stream that is mapped to a repo, that element will automatically be pushed to the repo from AccuRev.

GitCentric reflects the flexibility of both the Git and AccuRev environments, and it is possible to configure your repositories and streams in countless ways. However, Borland recommends keeping the following thoughts in mind:

Therefore, you probably do not want to create a repository that maps to an entire depot. You want your Git branches to map to directories within AccuRev streams that contain smaller, independent sections of functionality.

As with any new tool, it is important that you first understand what your current process is. If you are an existing Git shop, make sure that you have a clear picture of how your repositories and branches are configured, and what your workflow is. In evaluating this, you may find that you need to better define your current environment. If you have never gone through this exercise, consider searching for the following terms on the web: “git”, “workflow”, and “model”. This will point you to some good discussions about successful Git implementations. Once this is done, then you will be in a better position to decide how to map your branches to AccuRev streams.

Also, remember that both Git and AccuRev bring different strengths to your organization. Git provides a convenient, distributed version control system to your development end users. AccuRev provides powerful, centralized version control for users such as build administrators, release engineers, product managers, etc. Git branches can be somewhat transient -- if you start to develop something on a branch and then change your mind, you can delete the branch. AccuRev is TimeSafe™ -- all versions and transactions are captured permanently in the AccuRev database. When carefully planned, mapping between these environments means that GitCentric provides the best of both worlds to your organization.

When you configure a Git repository to work with AccuRev through GitCentric, you map a Git branch to an AccuRev stream. If you wish to take advantage of AccuRev promote operations, you map the parent AccuRev Stream to one branch, and the child AccuRev stream to another branch.

If you configure things correctly and follow a few basic rules, then:

• Promotes from the child stream to the parent stream in AccuRev will result in a merge between the corresponding branches in the Git repository if the content under the mount point is empty in the child stream. (That is, the merge will happen if the child stream is completely inherited so that it is the same as the parent at the mount point).

Note that the desired condition when these operations are completed is for the “default group” in AccuRev stream “C” to be empty. (The “default group” is the set of elements or files in a stream that are under current development. A file is removed from a stream’s default group when that file is either promoted or “revert to back”ed (or purged). See the AccuRev documentation for more details.)

To ensure that this happens reliably and predictably, configure your system so that:

1. One stream is the parent of another stream, and each of these streams are mapped to branches in the Git repository. In this example, the parent stream is called “P” and the child stream is called “C”

3. The mount point must be the same in each AccuRev stream for the branches that are mapped to them. (If one branch is mapped to one mount point in one stream, and the other branch is mapped to a different mount point in the other stream, the files will never line up.)

4. Any AccuRev rules that are applied to the C stream are also applied to the P stream. (For example, avoid include/exclude rules one stream that cause that cause its contents to differ relative to the other stream. And do not use cross-links on writable elements.)

From a Git viewpoint, this ensures that the branches point to the same commit graphs when their contents are identical. From an AccuRev viewpoint, this ensures that the default groups in the streams get cleared out when appropriate, and do not keep growing to include (potentially) all files in the system.

Borland recommends that you merge into the child branch first, and then fast forward merge the parent branch. If you merge into the child branch first, AccuRev will reflect this by performing a promote from the child stream to the parent stream. However, if you merge into the parent branch first, AccuRev will achieve the desired “zero default group” state by performing an AccuRev purge on the child stream.

The Git commands for merging into the child branch are:

There are two common reasons for mapping two different Git repositories to the same AccuRev stream:

In this case, you might have two different parts of a product in two different directory structures in the same stream, such as a GUI development tree and a database development tree. In the Git environment, you could have the GUI work being done in one repository and the database work being done in another. By mapping the branches in these repositories to the correct mount points in the same stream, you can keep the work separate. (Keeping the branch names consistent across repos will be helpful if you need to make branch-mapping changes en masse using the children-of option in the SSH config-branch CLI command.)

In this case, you could have two different sets of users with different access privileges accessing the same files. Privileged Git developers in corporate headquarters could have one repo mapped to the mount point with one service account having “lenient” AccuRev ACLs (see below). Less privileged off-shore contract developers could have a different repo mapped to the same mount point with a different service account having much more restrictive AccuRev ACLs. See Configuring for Security on page 10 for more information about ACLs and security.

Also, by mapping branches from different repos to a single AccuRev stream, you can automate the process of updating repos with changes: when a change gets pushed to a repo that is mapped to an AccuRev stream, that change gets propagated to all other branches that are mapped to that stream (assuming that the AccuRev ACLs allow a repo to “see” the changed file).

Figure 1 above illustrates a simple case of a single Git repository being associated with a single AccuRev server through GitCentric. Figure 3 and Figure 4 above illustrate multiple repositories being mapped to a single AccuRev server.

However, GitCentric can also configure multiple Git repositories with multiple AccuRev servers. For example, you could have one repo associated with one AccuRev server, and two other repos associated with a different AccuRev server. (However, a single repo cannot be associated with multiple AccuRev servers. And having multiple GitCentric servers configured with the same AccuRev server is not supported.)

If you choose to configure multiple AccuRev servers, AccuRev strongly recommends that you use the same GitCentric administrator user and password for all AccuRev servers to avoid the need to constantly log in and out as you move between servers.

Note that if you choose, you can administer your Git repos with GitCentric and not have their branches mapped to any AccuRev streams at all. You do need to associate a Git repository with an AccuRev server for security purposes, but you do not need to have its branches mapped to use GitCentric.

If your AccuRev installation has one or more replica servers, you should always try to associate GitCentric with the AccuRev master (if possible), and NOT a replica. Even if your GitCentric installation is physically located in close proximity to a replica server, you should try to configure GitCentric to work with the remote master AccuRev server, not the geographically closer replica server. (This may not be possible if your installation has implemented firewalls and VPN or some other kind of security that prevents you from communicating directly with a remote master server.)

As touched upon in Figure 4 on page 8, one of the advantages of using AccuRev GitCentric in a Git environment is that you can use both GitCentric and AccuRev security features to control access to files, a feature not natively provided by Git.

GitCentric makes use of two kinds of Access Control Lists (“ACLs”):

Using these two types of ACLs, you can approach GitCentric security in two ways:

• Mapping multiple repos as different “views” on AccuRev-controlled elements. The AccuRev-controlled elements may optionally be secured with AccuRev Element ACLs (EACLs).