Version Management using a VCS

PLCnext Engineer supports version management with two common version control systems (VCS): SVN (Apache Subversion) and Git. PLCnext Engineer acts as VCS client in each case. Both, SVN and Git can either be installed on a separate server or you can hire the services of a hoster.

General information on version control systems (VCS)

This topic contains the following sections:

The purpose of a VCS is to archive files/documents and capture each modification made to them. In our context, these files are PLCnext Engineer solutions with all its contained data (code, variable, HMI, version information, device parameters etc.).

After adding a solution to a repository, you can send (commit) newer versions into this repository. VCS stores all versions with a time stamp and user name.

Background information: purposes and functions of a VCS

Further Info
For further details on SVN and Git please consult the respective VCS documentation.

Security Considerations

The VCS used should be protected against unauthorized access and therefore manipulation. This applies to the communication between the VCS clients (PLCnext Engineer in our case) and the server where the repository is hosted as well as to the repository itself.
The security measures should involve encryption, authentication, and authorization. Examples:

Only establish secured connection channels between VCS client and repository.
Encrypt the repository.
Restrict the access to the server hosting the repository.

Further Info
Refer to the topic "Security in PLCnext Engineer" as well as to the "Phoenix Contact Industrial Cyber Security Guide" for further information.

Versioning of a project in PLCnext Engineer

In PLCnext Engineer, the version management is completely implemented in the VERSION CONTROL window. This window is located in the Cross Function Area at the lower screen border.

How to place a project under the control of a VCS:

In the VERSION CONTROL window, select the VCS to be used from the 'Version control' dropdown list.
If necessary, create a new repository by clicking the 'Create repository' button. In the browse dialog, you have to select an empty folder. Here, the address of a VCS hoster on the Internet can be specified instead of a local or network folder.
To use an already existing repository, skip this step and enter the path to the existing repository in the next step while getting the working copy.
Create a so-called working copy in the working copy folder which is under VCS control.
What is a working copy (folder)?

The working copy folder is your own private working area. This folder is no different from any other folder on your hard disk, and you can edit the data in it in any way you want. The data in it is (after the check-in, see step 5) connected to the data in the repository. Besides your solution data, the folder will contain an invisible subfolder (.svn/.git) which defines and manages this connection. This folder must not be deleted.
Each VCS-related command you are executing on the project stored in the working copy folder corresponds to an interaction between the repository and the working copy.

For that purpose, click the button 'Get working copy' in the VERSION CONTROL window.
In the appearing dialog, select the following:
- The 'Repository' into which the project should be integrated.
  If you have created a new repository in step 2, this new repository is already preset.
  To select an existing repository click the '...' browse button and set the desired path.
- The 'Working Copy' folder where you want to store your local copy of the project in uncompressed format.
  
  Note
  The working copy folder must be empty.
Click 'OK' to connect the working copy folder to the selected repository.
The folder then contains an invisible subfolder (.svn/.git) which must not be deleted.
The data already stored in the repository are copied to the working copy folder. This means, if the repository already contains PLCnext Engineer solutions or any files, these are copied to the working copy folder.
Save the project to be put under VCS control into the working copy folder.
Select 'File > Save Project As...', set the file type '*.pcwef' and select the working copy folder as destination path.
With this step, the solution files are added to the repository.

Note
The project must be saved in uncompressed (flat) format but not in compressed format (*.pcwex). In pcwex format the project cannot be versioned in a VCS.

The solution is now versioned in the repository. The VERSION CONTROL window then shows the used repository and working copy folder in its 'Info' tab.
Example: version info

In the left column, the currently used working folder is selected (MyWorkingFolder in the example). Here, several folders can be shown here, for example, if the project references libraries which are located in different working folders.

Behind the repository and working folder path on the right, browse buttons are available to explore the corresponding folder.
After adding it to the repository in the previous step, you have to commit the current project version to the repository. This way, the current version of each single solution file is checked-in.
1. Open the 'Pending Changes' tab in the VERSION CONTROL window.
2. Click the 'Commit' button.
A dialog appears where you can enter a comment describing the current version. This comment will later be displayed in the 'History' tab when exploring the revisions.
Example:
Continue with the further editing of the project.
After saving it the next time, the following occurs:
- PLCnext Engineer automatically makes a comparison with the latest version in the repository. Any modifications you made since you committed the version the last time are listed on the tab 'Pending changes'.
  Here, several commands are available in the toolbar which are described below.
  Example: tab 'Pending Changes' (SVN repository)
  
  In the following example, a new local FB has been added to the project in which variables have been declared and code was developed.
- The 'History' tab shows which versions have been committed. For each version, the user is shown who has committed the version. Furthermore, the time stamp is visible as well as the comment which was entered while checking-in the data.
  When selecting an entry, the committed modifications of this version are listed in the 'Logical Items' column on the right.
  Several commands are available in the toolbar which are described below.
  Example: tab 'History' (SVN repository)

Commands on the 'Tools' view

If 'Tools' is selected on the left side of the VERSION CONTROL window, the following commands are visible on the right.

Icon Command Description SVN/Git Command

-- 'Version control' drop down list Selects the VCS used. n/a

Create repository Creates a repository for the VCS selected. A new repository can only be created in an empty folder.
The repository can be created on a local or network folder. n/a

Get working copy Creates a working copy by checking out data from the repository. A dialog appears where you have to select the repository and set an empty working folder. SVN: Checkout

Git: Checkout

Icon	Command	Description	SVN/Git Command
--	'Version control' drop down list	Selects the VCS used.	n/a
	Create repository	Creates a repository for the VCS selected. A new repository can only be created in an empty folder. The repository can be created on a local or network folder.	n/a
	Get working copy	Creates a working copy by checking out data from the repository. A dialog appears where you have to select the repository and set an empty working folder.	SVN: Checkout
Git: Checkout

Commands on the tabs 'Pending Changes' and 'History'

If a working copy folder (repository) is selected on the left side of the VERSION CONTROL window, the tabs 'Pending Changes', 'History' and 'Info' are visible on the right.

The buttons that are available for executing VCS-related commands in the tabs 'Pending Changes' and 'History' depend on the VCS used.

'Pending Changes' tab

The list of pending changes is updated approx. 2 seconds after saving the project. Unsaved modifications cannot be listed here. Modifications on the project may also occur after clicking some VCS-related commands such as 'Update'/'Pull' or 'Revert'/'Revert to Revision'.

Icon Command Description SVN/Git Command

Refresh Refreshes the list of pending changes and sets the number of visible list entries. SVN: Refresh (in Repo browser)

Git: n/a

Commit Sends the modifications you made to your working copy to the repository (check-in).
Make sure that your working copy is up to date prior to commmitting (using the 'Update' (with SVN) or 'Pull' (Git) command).
Note that with Git, the revision is committed to the local repository and have to be pushed to the public main repository later (see 'Push' below). SVN: Commit

Git: Commit

Push Transfers data from your local Git repository to the public master repository.
Pushing is necessary for synchronizing several local repos with the master repository thus integrating the local modifications of each user.
Afterwards, other users can pull modifications into their local repository and working copy (see 'Pull' below). SVN: n/a

Git: Push

Update Updates your local working copy with changes that other users committed to the SVN repository.
The command checks the repository for updates (compared to your working copy) and, if available, merges them into your working copy.
Any modifications you made in the affected files are kept.
The repository is not changed by the 'Update' command. SVN: Update

Git: n/a

Revert Discards all pending changes and reverts the project to the revision which was committed last. SVN: Revert

Git: Revert

Pull Checks the public master Git repository for differences (updates compared to your working copy) and merges them into your local Git repository and into your working copy.
Such updates are necessary if the public master repository contains commits of other users.
Any modifications you made in the affected files are kept.
The public master repository is not changed by the 'Pull' command. SVN: n/a

Git: Pull

Icon	Command	Description	SVN/Git Command
	Refresh	Refreshes the list of pending changes and sets the number of visible list entries.	SVN: Refresh (in Repo browser)
Git: n/a
	Commit	Sends the modifications you made to your working copy to the repository (check-in). Make sure that your working copy is up to date prior to commmitting (using the 'Update' (with SVN) or 'Pull' (Git) command). Note that with Git, the revision is committed to the local repository and have to be pushed to the public main repository later (see 'Push' below).	SVN: Commit
Git: Commit
	Push	Transfers data from your local Git repository to the public master repository. Pushing is necessary for synchronizing several local repos with the master repository thus integrating the local modifications of each user. Afterwards, other users can pull modifications into their local repository and working copy (see 'Pull' below).	SVN: n/a
Git: Push
	Update	Updates your local working copy with changes that other users committed to the SVN repository. The command checks the repository for updates (compared to your working copy) and, if available, merges them into your working copy. Any modifications you made in the affected files are kept. The repository is not changed by the 'Update' command.	SVN: Update
Git: n/a
	Revert	Discards all pending changes and reverts the project to the revision which was committed last.	SVN: Revert
Git: Revert
	Pull	Checks the public master Git repository for differences (updates compared to your working copy) and merges them into your local Git repository and into your working copy. Such updates are necessary if the public master repository contains commits of other users. Any modifications you made in the affected files are kept. The public master repository is not changed by the 'Pull' command.	SVN: n/a
Git: Pull

'History' tab

Icon Command Description SVN/Git Command

Refresh Refreshes the history list and sets the number of visible list entries ('Next 100' or 'Show All'). SVN: Refresh (in Repo browser)

Git: Refresh in Show log

Export revision Exports the revision marked in the history list into a directory. The project is exported in *.pcwef format. SVN: Export (in Windows Explorer context menu or Repo browser)

Git: Export this revision (in 'Log messages' window TortoiseGit)

Revert to revision Reverts the current project to the revision marked in the history list.
After reverting, the current project usually has pending changes. These pending changes can be commited or reverted on the 'Pending Changes' tab (using the 'Revert' command). SVN: Revert to this revision (in 'Log messages' window TortoiseSvn)

Git: Reset 'master' to this (in 'Log messages' window TortoiseGit)

Command	Description	SVN/Git Command
Refresh	Refreshes the history list and sets the number of visible list entries ('Next 100' or 'Show All').	SVN: Refresh (in Repo browser)
Refresh		Git: Refresh in Show log
Export revision	Exports the revision marked in the history list into a directory. The project is exported in *.pcwef format.	SVN: Export (in Windows Explorer context menu or Repo browser)
Export revision		Git: Export this revision (in 'Log messages' window TortoiseGit)
Revert to revision	Reverts the current project to the revision marked in the history list. After reverting, the current project usually has pending changes. These pending changes can be commited or reverted on the 'Pending Changes' tab (using the 'Revert' command).	SVN: Revert to this revision (in 'Log messages' window TortoiseSvn)
Revert to revision		Git: Reset 'master' to this (in 'Log messages' window TortoiseGit)