Version Control#

Using Version Control Systems#

Version control systems supported by PVRStudio are:

Version Control System	Address	Notes
C learCase	http://w ww-01.ibm.com/softwar e/awdtools/clearcase/	Disabled by default. To enable the plugin, select Help > About Plugins > Version Control > ClearCase, and then restart PVRStudio.
Git	http://git-scm.com/	Git version 1.9.0, or later Gerrit version 2.6, or later
M ercurial	http://m ercurial.selenic.com/
Perforce	ht tp://www.perforce.com	Server version 2006.1 and later Disabled by default. To enable the plugin, select Help > About Plugins > Version Control > Perforce, and then restart PVRStudio.

Setting Up Version Control Systems

PVRStudio uses the version control system’s command line clients to access your repositories. To allow access, make sure that the command line clients can be located using the PATH environment variable. Alternatively, specify the path to the command line client executable in the Command field in the version control system specific tab in Tools > Options > Version Control.

If authentication is required to access the repository, enter the user credentials in the Username and Password fields.

Enter a timeout for version control operations in the Timeout field.

For some version control systems, you can specify the maximum number of lines the log can contain in the Log count field.

After you set up the version control system, use the command line to check that everything works (for example, use the status command). If no issues arise, you should be ready to use the system also from PVRStudio.

For more information on using Git for Windows, see Using Git for Windows.

Setting Up General Options

Select Tools > Options > Version Control > General to specify settings for submit messages:

Wrap submit messages at limits the line length of a submit message to the specified number of characters.
Submit message check script is a script or program that can be used to perform checks on the submit message before submitting. The submit message is passed in as the script’s first parameter. If there is an error, the script should output a message on standard error and return a non-zero exit code.
User/alias configuration file is a text file that lists author names in mailmap format. For each author, you must specify a real name and email address and optionally an alias and a second email address. For example:
```
Jon Doe <Jon.Doe@company.com> jdoe <jdoe@somemail.com>
Hans Mustermann <Hans.Mustermann@company.com> hm <info@company.com>
```
After you specify a file in this field, you can select authors as values of the submit message fields in the Nicknames dialog.
User fields configuration file is a simple text file consisting of lines specifying submit message fields that take authors as values, for example:
```
Acked-by:
Initial-patch-by:
Reported-by:
Rubber-stamped-by:
Signed-off-by:
Tested-by:
```
After you specify a file in this field, you can add authors as values of the submit message fields when submitting changes. If you also specified a User/alias configuration file, you can select authors in the Nicknames dialog.
SSH prompt command specifies an ssh-askpass command that you can use (on Linux) to prompt the user for a password when using SSH. For example, ssh-askpass or x11-ssh-askpass, depending on the ssh-askpass implementation that you use.
Reset VCS Cache resets the version control system configuration to a state known to PVRStudio after it has been changed from the command line, for example.

Creating VCS Repositories for New Projects

PVRStudio allows you to create repositories for version control systems that support local repository creation, such as Git, Mercurial, or Bazaar. When creating a new project by selecting File > New File or Project, you can choose a version control system on the final wizard page.

You can also select Tools and then select Create Repository in the submenu for the version control system.

To import a project that is under version control, choose File > New File or Project > Project from Version Control and select the version control system that you use. Follow the instructions of the wizard to import the project.

Using Common Functions

The Tools menu contains a submenu for each supported version control system. This section describes using the functions that are available for all the supported version control systems. For more information about the additional functions and options available for a particular version control system, see:

Using Git <Using Git>

The Version Control output pane displays the commands that are executed, a timestamp, and the relevant output. Select Window > Output Panes > Version Control to open the pane.

Adding Files

When you create a new file or a new project, the wizard displays a page asking whether the files should be added to a version control system. This happens when the parent directory or the project is already under version control and the system supports the concept of adding files, for example, Perforce and Subversion. Alternatively, you can add files later by using the version control tool menus.

Viewing Diff Output

All version control systems provide menu options to diff the current file or project: to compare it with the latest version stored in the repository and to display the differences. In PVRStudio, a diff is displayed in a read-only editor. If the file is accessible, you can double-click on a selected diff chunk and PVRStudio opens an editor displaying the file, scrolled to the line in question.

With Git, Mercurial, and Subversion, the diff is displayed side-by-side in a diff editor by default. To use the inline diff view instead, select the Switch to Text Diff Editor (1) option from the toolbar. In the inline diff view, you can use context menu commands to apply, revert, stage, and unstage hunks, as well as send them to a code pasting service.

Viewing Versioning History and Change Details

Display the versioning history of a file by selecting Log or Filelog. Typically, the log output contains the date, the commit message, and a change or revision identifier.

Annotating Files

Annotation views are obtained by selecting Annotate or Blame. Selecting Annotate or Blame displays the lines of the file prepended by the change identifier they originate from. Clicking on the change identifier shows a detailed description of the change.

To show the annotation of a previous version, right-click on the version identifier at the beginning of a line and choose one of the revisions shown at the bottom of the context menu. This allows you to navigate through the history of the file and obtain previous versions of it. It also works for Git and Mercurial using SHA-1.

The same context menu is available when right-clicking on a version identifier in the file log view of a single file.

Committing Changes

Once you have finished making changes, submit them to the version control system by choosing Commit or Submit. PVRStudio displays a commit page containing a text editor where you can enter your commit message and a checkable list of modified files to be included.

Reverting Changes

All supported version control systems support reverting your project to known states. This functionality is generally called reverting.

The changes discarded depend on the version control system.

A version control system can replace the Revert menu option with other options.

Viewing Status

You can select Status to view the status of the project or repository.

Updating the Working Tree

You can select Update to update your working tree with the latest changes from the branch. Some version control systems allow you to choose between updating the current project and updating all projects.

Deleting Files

You can select Delete to delete obsolete files from the repository.

Using ClearCase#

IBM Rational ClearCase is a version control, workspace management, parallel development support, and build automation solution developed by IBM. The ClearCase client plugin is available on Linux and Windows for accessing a ClearCase server.

Using GNU Diffutils with ClearCase

You can use the GNU Diffutils tool With ClearCase to compare files and activities:

Download Diffutils and extract it to a directory in your PATH.
Select Tools > Options > Version Control > ClearCase.
Select the External radio button. The radio button is disabled if diff is not found in the PATH.
In the Arguments field, specify arguments for running diff.

Checking out and Checking in

In addition to the standard version control system functions described in Using Common Functions, you can check out and check in files.

To create a writable copy of a file, select Tools > ClearCase > Check Out. If you check out files in a Unified Change Management (UCM) view, they are added to the change set of a UCM activity. By default, the activities are automatically assigned names. To disable this functionality, select Tools > Options > Version Control > ClearCase, and then deselect the Automatically assign activity names check box.

To automatically check out files when you edit them, select Tools > Options > Version Control > ClearCase, and then select the Automatically check out files on edit check box.

To cancel the checkout for a file and delete the checked-out version, select Tools > ClearCase > Undo Check Out.

To check in checked-out versions of files in the change set of the current UCM activity, select Tools > ClearCase > Check In Activity.

To create a permanent new version of the current file or all files in the versioned object base (VOB), select Tools > ClearCase > Check In. To be asked to confirm that you want to check in the files, select Tools > Options > Version Control > ClearCase, and then select the Prompt on check-in check box.

By default, you are asked to enter a comment when checking files out or in. To suppress this prompt, select Tools > Options > Version Control > ClearCase, and then select the Do not prompt for comment during checkout or check-in check box.

If you change the read-only attribute of a file that is loaded into a snapshot view and modify the file without checking it out, you hijack the file. To revert a hijacked file to its checked in version, select Tools > ClearCase > Undo Hijack.

By default, the files in the VOBs are indexed for quick access to their statuses. To disable indexing, select Tools > Options > Version Control > ClearCase, and then select the Disable indexer check box. To only have some VOBs indexed, specify them in the Index only VOBs field.

Using Git#

Git is a fast decentralized version control system. Git is available for Windows, Linux, and macOS.

You can use the Gerrit code review tool for projects that use Git.

Using Git for Windows

If you configure Git for use with git bash, only, and use SSH authorization, Git looks for the SSH keys in the directory where the HOME environment points to. The variable is always set by git bash.

However, the variable is typically not set in a Windows command prompt. When you run Git from a Windows command prompt, it looks for the SSH keys in its installation directory, and therefore, the authorization fails.

You can set the HOME environment variable from PVRStudio. Select Tools > Options > Version Control > Git, and then select the Set “HOME” environment variable check box. HOME is set to %HOMEDRIVE%%HOMEPATH% when the Git executable is run and authorization works as it would with git bash.

Working with the Current File

To work with the current file, select the commands in Tools > Git > Current File. Some of the commands are also available for the project or local repository that contains the file.

Viewing Git Diff

You can diff the current file or project to compare it with the latest version stored in the repository and to display the differences. To display the diff in a read-only editor, select Diff of. If the file is accessible, you can double-click on a selected diff chunk and PVRStudio opens an editor displaying the file, scrolled to the line in question.

The diff is displayed side-by-side in a diff editor by default. To use the unified diff view instead, select the Switch to Unified Diff Editor (1) option from the toolbar. In both views, you can use context menu commands to apply, revert, stage, and unstage hunks, as well as send them to a code pasting service.

Viewing Git Log

To display the versioning history of a file, select Log of. The log output contains the date, the commit message, and a commit identifier. Click on the commit identifier to display a description of the change including the diff in the Git Show view.

Right-clicking on a commit identifier brings up a context menu that lets you apply actions on the commit, such as view annotations or cherry-pick or revert a commit.

Select image:: images/reload_gray.png (Reload) to rescan the files.

Viewing Annotations

To view annotations, select Blame. The view displays the lines of the file prepended by the commit identifier they originate from. Clicking on the commit identifier shows a detailed description of the change.

To show the annotation of a previous version, right-click on the commit identifier and select Blame Parent Revision. This allows you to navigate through the history of the file and obtain previous versions of it.

The other actions in the context-menu enable you to apply actions to the commit, such as cherry-pick, checkout, or revert it.

To rescan the files, click image:: images/reload_gray.png (Reload).

Staging Changes

To mark a new or modified file for committing it to the repository, select Stage File for Commit. To undo this function, select Unstage File from Commit.

Resetting Changes

Git has an index that is used to stage changes. The index is committed on the next commit. Git allows you to revert back to the state of the last commit as well as to the state staged in the index.

To revert all changes and reset the current file to the state of the index, select Undo Unstaged Changes.

To return the current file to the state it was in right after the last commit, select Undo Uncommitted Changes. This reverts all changes, discarding the index.

Working with the Current Project

To work with the current project, select the commands in Tools > Git > Current Project. The Diff Project and Log Project commands, which are also available for the current file, are described above.

Cleaning Projects

To clean the working directory, select Clean Project. All files that are not under version control are displayed in the Clean Repository dialog. Ignored files are deselected by default. Select the files to delete and click Delete.

Working with Local Repositories

To work with the local repository, select the commands in Tools > Git > Local Repository. The commands that are also available for the current file or project are described above.

Viewing Reference Log

Reference logs record when the tips of branches and other references were updated in the local repository. To view the reference log, select Reflog.

Viewing Git Status

To view the status of the repository in the Version Control output view, select Status.

Committing Changes to Git

To submit your changes to Git, select Commit. PVRStudio displays a commit page containing a text editor where you can enter your commit message and a checkable list of modified files to be included.

When you have finished filling out the commit page information, click on Commit to start committing.

The Diff Selected Files button brings up a diff view of the files selected in the file list. Since the commit page is just another editor, you can go back to it by closing the diff view. You can also switch to an open diff view by selecting it in the Open Documents pane in the sidebar.

Amending Commits

To apply latest changes to the last commit, select Amend Last Commit. You can also edit the commit message.

To amend an earlier comment in a series of related commits, select Fixup Previous Commit. This operation is done using interactive rebase. In case of conflicts, a merge tool is suggested.

Resetting Local Repository

To reset changes, select Reset. This opens a dialog where you can select the commit to reset the working directory to. This is useful after applying patches for review, for example. You can choose between a Soft reset that does not touch the index file nor the working tree at all, a Hard reset that discards all changes to tracked files in the working tree, and a Mixed reset that resets HEAD and the index (nothing remains staged) without touching the working directory.

To recover removed files, select Recover Deleted Files.

To change a series of commits in the local repository, select Interactive Rebase. You can reorder or discard commits, squash them into a single commit, or edit the commit messages.

Working with Branches

To work with Git branches, select Branches. The checked out branch is shown in bold and underlined in the list of branches in the Git Branches sidebar view.

If you checked out a specific commit, the list of branches displays a Detached HEAD entry.

For local and remote branches, the changes log can be shown by double clicking on the branch name.

To refresh the list of branches, click image:: images/reload_gray.png (Refresh).

The following operations are supported in the context-menu for a branch:

Menu Item	Description
Add	Create new tracking and non-tracking branches.
Remove	Remove a local branch. You cannot delete remote branches.
Rename	Rename a local branch. You cannot rename remote branches.
Checkout	Check out the selected branch and make it current. You can stash changes you have made to tracked files.
Diff	Show the differences between the selected and the current branch.
Log	Show the changes in a branch.
Reset	Reset the active branch to the selected branch. You can choose between a Hard, Mixed, and Soft reset. For more information, see Resetting Local Repository.
Merge	Join the development histories in two branches together. If the commit you are merging can be reached by following the first commit’s history, there is no divergent work to merge together. To allow Git to move the branch pointer forward, select Merge (Fast-Forward). If you do not want to fast-forward the branch, select Merge (No Fast-Forward).
Rebase	Copy local commits to the updated upstream head.
Cherry Pick	Cherry pick the top commit from the selected branch.
Track	Set the current branch to track the selected one.
Push	Push the committed changes to the selected remote branch.

The following additional context-menu operations are available for Remote Branches. The context-menu can be opened on Remote Branches or on a specific remote repository.

Menu Item	Description
Fetch	Fetches all the branches and changes information from a specific remote repository, or from all remotes if applied to Remote Branches.
Manage Remotes	Opens the Remotes dialog.

Configuring Merge Tools

Only graphical merge tools are supported. You can configure the merge tool to use on the command line. For example, to use the KDiff3 merge tool, enter the following command:

git config --global merge.tool kdiff3

Applying Patches

Patches are rewriting instructions that can be applied to a set of files. To apply a patch file that is open in PVRStudio, select Patch > Apply from Editor.

To select the patch file to apply from the file system, select Apply from File.

Using Stashes

With Git, you can put your current set of changes onto a virtual shelf called a stash. Stashes are useful, for example, to put aside a set of changes to work on higher priority tasks or to pull in new chages from another repository.

To stash all local changes, select Stash > Stash. The working copy is reset to the state it had after the last commit. To save the current state of your unstaged files and reset the repository to its staged state, select Stash Unstaged Files.

To display a dialog that shows all known stashes with options to restore, display or delete them, select Stashes.

To save a snapshot of your current work under a name for later reference, select Take Snapshot. The working copy is unchanged. For example, if you want to try something and find out later that it does not work, you can discard the changes and return to the state of the snapshot.

To remove a single stashed state from the stash list and apply it on top of the current working tree state, select Stash Pop.

Applying Actions to Commits

To browse a directory or the commit history and to apply actions on the commits, select Tools > Git > Actions on Commits. You can checkout, revert, or cherry-pick commits or view them in the diff editor.

Initializing Git Repositories

To start controlling a project directory that is currently not under version control, select Tools > Git > Create Repository. PVRStudio creates a new subdirectory named .git that contains all the necessary repository files. However, nothing in the project is tracked yet, so you will need to create an initial commit to start tracking the project files.

Working with Remote Repositories

To work with remote repositories, select the commands in Tools > Git > Remote Repository.

To fetch all the branches and change information from a remote repository, select Fetch.

To pull changes from the remote repository, select Pull. If there are locally modified files, you are prompted to stash the changes. Select Tools > Options > Version Control > Git and then select the Pull with rebase check box to perform a rebase operation while pulling.

To push committed changes to the remote repository, select Push.

Managing Remote Repositories

To manage remote repositories available in Git, select Tools > Git > Remote Repository > Manage Remotes. Double-click the names and URLs of the remote repositories to edit them.

The following operations are supported:

Menu Item	Description
Refresh	Refresh the list of remote repositories.
Add	Add a new remote repository.
Fetch	Fetch all the branches and change information from a remote repository.
Push	Push committed changes to the remote repository.
Remove	Remove a remote repository.

Using Git with Subversion

You can use Git as a client for a Subversion server. To fetch changes from a Subversion repository to a Git repository, select Tools > Git > Remote Repository > Subversion > Fetch.

To view the Git Subversion log, select Log.

To publish the commits from the current branch to the Subversion server, select DCommit. This will create a revision in Subversion for every local Git commit. Afterwards, the branch is rebased or reset (depending on whether or not there is a diff between Subversion and head).

Reviewing Code with Gerrit

If your Git project uses Gerrit for code reviews, you can view your changes in PVRStudio.

To push committed changes to Gerrit, select Tools > Git > Remote Repository > Push to Gerrit.

Select the Draft/private check box to push changes that are only visible to you and the reviewers. If you are using Gerrit 2.15 or later, you can select the Work-in-progress check box to push changes that do not generate email notifications.

To view the same information about each change as in the Gerrit web interface, select Tools > Git > Remote Repository > Gerrit.

To view details of the selected change, select Show.

To cherry-pick the selected change to the local repository, select Cherry Pick. To remove the change after testing it, select Tools > Git > Local Repository > Reset. In the Undo Changes to dialog, select the state to reset the working directory to, and then select OK.

To check out the change in a headless state, select Checkout.

To refresh the list of changes, select Refresh.

The Remote field lists the remotes of the current repository that are detected as Gerrit servers. Select Tools > Options > Version Control > Gerrit to specify a fallback connection to a Gerrit server over SSH. The Gerrit REST interface and the curl tool are used for HTTP connections.

Select the HTTPS check box to prepend https to the Gerrit URL if Gerrit does not provide it.

Working with Git Tools

To start a graphical interface to Git, select Tools > Git > Git Tools > Git Gui.

Note: On macOS, the default Git installation does not contain Git Gui. To use Git Gui, install it separately. To start Git Gui from PVRStudio, select Preferences > Version Control > Git, and set the path to the environment that contains Git Gui in the Prepend to PATH field.

To start the commit viewer for Git, select Tools > Git > Git Tools > Gitk. You can also start the tool to view commits in the current document or in the folder that contains the current document. To specify arguments for running Gitk, select Tools > Options > Version Control > Git.

To use some other application for viewing Git history, such as GitX or QGit viewer, select Tools > Options > Version Control > Git and specify the path to the application executable in the Command field. To start the application, select Tools > Git > Git Tools > Repository Browser.

To resolve merge conflicts, select Tools > Git > Git Tools > Merge Tool.

Using Mercurial#

Mercurial is a free, distributed source control management tool.

In addition to the standard version control system functions described in Using Common Functions, you can select the following functions in the Tools > Mercurial submenu:

Menu Item	Description
Import	Apply changes from a patch file.
Incoming	Monitor the status of a remote repository by listing the changes that will be pulled.
Outgoing	Monitor the status of a remote repository by listing the changes that will be pushed.
Pull	Pull changes from the remote repository.
Push	Push changes to the remote repository.

Using Perforce#

Perforce is a fast software configuration management system developed by Perforce Software.

Since PVRStudio 4.9, the Perforce plugin is disabled by default. To enable it, select Help > About Plugins > Version Control > Perforce, and then restart PVRStudio.

Configuring Perforce

In the Perforce options, you can specify workspace details: P4 user, P4 client, and P4 port. To specify the details individually for several projects, use configuration files instead. Create a p4config.txt configuration file for each project in the top level project directory.

Editing Files

In addition to the standard version control system functions described in Using Common Functions, you can select Tools > Perforce > Edit File to open a file for editing within the client workspace. By default, files are automatically opened for editing. To disable this feature, select Tools > Options > Version Control > Perforce, and then deselect the Automatically open files when editing check box.

To list files that are open for editing, select Tools > Perforce > Opened.

To group files for commit, select Tools > Perforce > Pending Changes.

To view information about changelists and the files in them, select Tools > Perforce > Describe.

By default, you are prompted to confirm that you want to submit changes. To suppress the prompt, select Tools > Options > Version Control > Perforce, and then deselect the Prompt on submit check box.