Version Control with Workspaces

A version control workspace is a folder on disk, next to your TIA Portal project or anywhere else you choose, that holds objects of the project as ordinary files: blocks, PLC data types, tag tables, technology objects and library types, one file per object. Because the folder is an ordinary folder, you can version it with Git, SVN or any other tool you already use. Studio and TIA Portal keep the project and the files in step: you connect objects to their files, write changes from the project into the files, take changed files back into the project, and see at a glance which side changed.

The workspaces belong to the project. TIA Portal stores them, their folders and every connection inside the project, so they come back the next time you open it. A workspace you created or changed in a project that you then close without saving is lost, like any other change.

Requirements

• A connection to TIA Portal with an open project. In a project opened offline the workspaces are not shown.
• TIA Portal V17 or newer to see and manage workspaces and groups. The language of the files can be chosen from TIA Portal V18, the library import settings from TIA Portal V20.
• TIA Portal V20 or newer to connect objects, export them, read the status and synchronize. On V17, V18 and V19 you manage the workspaces only, and the Workspace Status says so.
• Whether a TIA Portal installation offers version control at all depends on its version and update. When it does not, the Version Control Workspaces branch does not appear.
• Seeing the workspaces and their status works on every plan. Creating, changing and deleting workspaces, connecting, exporting, importing and disconnecting need the Pro plan; without it the upgrade dialog opens and nothing is changed.

The Version Control Workspaces branch

The Project Explorer shows the branch Version Control Workspaces at the end of the tree, after Project Library and Global Libraries:

• Workspace groups organize your workspaces, for example by line or by station. A group can hold workspaces and further groups. Groups are listed before workspaces, each sorted by name.
• Workspaces show their root folder as the description, or No root folder. Hover a workspace to see its root folder, its language and, from TIA Portal V20, how many objects are connected to it.
• Double-click a workspace to open its Workspace Status.

The connected objects themselves are not rows in the tree, because their state changes with every edit. You see them in the Workspace Status.

The branch is read when you click or expand it, like Hardware, HMI and the Project Library: until then the folder shows a small load icon. If you want it read as soon as the project connects, switch on Load Version Control Workspaces under Project Explorer in the Settings. Refresh in the Project Explorer reads the branch again together with the rest of the tree.

Every entry for the workspaces sits in the submenu Version Control Workspaces of the context menu.

Creating and managing workspaces

New Workspace

1. Right-click Version Control Workspaces or a group and choose New Workspace.... On a group, the workspace goes into that group; from the Command Palette it goes to the top level
2. Enter the name. Workspace names are unique in the whole project, also across groups, and may have up to 128 characters without a slash, a backslash or a control character
3. Choose the root folder of the workspace. The dialog opens in the folder of the TIA Portal project, as TIA Portal proposes it; if you choose the project folder itself, Studio uses a subfolder with the name of the workspace, so the files never land next to the project file. Any other existing folder works too
4. From TIA Portal V18, choose the language of the files: Editing Language of the Project, or Other Language... and enter a language code such as de-DE. The language must be active in the project and cannot be changed later
5. The message confirms the new workspace with its root folder, and the new row is selected

From TIA Portal V18 a small .vci folder appears in the root folder; TIA Portal keeps the settings of the workspace there. Several workspaces may share one root folder.

New Group

Right-click Version Control Workspaces or a group and choose New Group..., then enter the name. Group names are unique within their parent group.

Rename

Rename on a group or a workspace asks for the new name. An open Workspace Status follows the workspace to its new name.

Delete

Delete asks first and says what goes:

• Deleting a workspace removes the workspace and the connections of its objects. The objects stay in the project, and the files and the .vci folder stay in the root folder on disk. Confirm with Delete Workspace
• Deleting a group removes every workspace and every group inside it, together with their connections. The objects stay in the project and the files stay on disk. Confirm with Delete Group and Workspaces

The message names how many connections were removed. An open Workspace Status of a deleted workspace closes.

Set Root Folder

Set Root Folder... on a workspace chooses another root folder. When the workspace has a root folder, from TIA Portal V20 you can also choose Remove Root Folder: the workspace keeps its connections but has no folder until you set one again. Connecting and exporting need a root folder.

Library Import Settings

From TIA Portal V20, Library Import Settings... on a workspace sets how library types in that workspace are taken into the project:

• Choose Global Library for Type Imports... picks the global library file that imported library types go to, and Remove Global Library for Type Imports clears it again
• Delete Unused Type Versions After an Import or Keep Unused Type Versions After an Import decides what happens to type versions that are no longer used after an import

The header of the Workspace Status shows both settings.

Reveal Workspace Folder

Reveal Workspace Folder opens the root folder in the Windows file manager. If you open that folder in Studio as a folder of your own, the built-in source control of Studio takes over the files, so you can commit, compare and push them like any other files; see Git Client.

Putting objects into a workspace

There are two ways to bring an object into a workspace. Connect to Workspace... links objects to files that already exist in the folder, for example after you cloned a repository. Export to Workspace... writes the files from the project and links them in one step. Both need TIA Portal V20 or newer.

Right-click one or several of these rows, or a folder that holds them, and open the submenu Version Control Workspaces:

• blocks (FB, FC, OB, DB, fail-safe blocks included)
• PLC data types
• PLC tag tables
• technology objects
• the folders Program blocks, a block group, PLC data types, PLC tags and Technology objects; a folder stands for the objects inside it

Types of the project library are kept in a workspace through the assistant, see AI assistant support.

Export to Workspace

1. Choose Export to Workspace...
2. Pick the workspace. When the project has none yet, Studio offers New Workspace...; a workspace without a root folder asks you to set one first
3. Choose the file format (see below)
4. Enter the folder below the root folder that receives the files, for example Blocks\Main, or leave it empty to write into the root folder. A missing folder is created. A full path or .. is not accepted
5. Choose Keep the Project Folder Structure (the default, as in TIA Portal: below that folder the files go into subfolders that mirror the block groups of the project, for example BlocksKernelSinamicsSpeedCtrl.scl) or Put All Files into That Folder
6. Confirm with Export. TIA Portal writes one file per object and connects the object to it. A file with the same name in the same folder is overwritten

Connect to Workspace

1. Choose Connect to Workspace...
2. Pick the workspace and the file format, as for an export
3. Choose the folder that holds the files. The folder dialog opens at the root folder, and the folder must be the root folder or lie below it
4. Choose whether the files lie in subfolders that mirror the block groups of the project (the default) or all in that folder
5. Each object is connected to the file with its name in the matching folder. The files must exist already; nothing is written

File formats

Before the format choice, Studio asks TIA Portal which formats each object supports. Objects TIA Portal cannot keep in a workspace are reported as not supported. The pick offers Preferred Format of Each Object and every format TIA Portal offered, each with the number of objects it applies to; objects that do not offer the chosen format use their preferred one.

Preferred Format of Each Object takes SCL where it is offered, otherwise SimaticML, otherwise SimaticSD, otherwise the first format TIA Portal offers. A library type is written as three files: its source and two small description files that TIA Portal needs to read it back.

The result

One message sums up the run, for example Exported 12 of 14 objects to the workspace "Station_A"., says how many were already the same on both sides, and names every object that was not processed, with the reason: an object TIA Portal cannot keep in a workspace, a format the object does not offer, a missing file, a file that is already connected, a read-only file, a know-how protected block or, on TIA Portal V21, an object that has to be compiled first. When an object failed, the message is a warning and offers Open Workspace Status.

The Workspace Status

Open Workspace Status on a workspace, a double-click on its row or the button in the export message opens one tab per workspace. It shows the state of every connected object.

Header. The workspace and its group, the root folder, the language of the files and the comment of the workspace when it has one; from TIA Portal V20 also the global library for type imports and whether unused type versions are deleted after an import.

Summary. The number of connected objects and how many are in each state.

Table. One row per connected object with a check box, the Object (its place in the project), the File (its path below the root folder), the Format, the State and, for a conflict, the Resolve buttons. Select all objects in the table head ticks every row.

The toolbar offers:

• Refresh asks TIA Portal for the current state of every connected object
• Export Selected to Workspace writes the ticked objects that changed in the project, or whose file is missing, to their files. Other ticked rows are left out
• Import Selected from Workspace takes the ticked files that changed in the folder into the project. It always asks first, Import ... objects from the workspace "..." into the project?, because TIA Portal replaces each object in the project with the content of its file. Save the project before, if you want to keep a way back. Confirm with Import
• Disconnect removes the connection of the ticked objects after a confirmation. The objects stay in the project and their files stay in the folder

TIA Portal reads the files of a workspace as they are, without formatting them first. If you edit SCL files of a workspace in Studio, run Format Document before you import them, so they arrive in the TIA Portal layout with the values of the SCL Formatting section in the Settings.

Both changed. An object changed on both sides is never part of an export or import of the selection. Decide in its row instead:

• Keep Project Version writes the project version to the file; the changes in the file are lost. Confirm with Overwrite File
• Keep File Version imports the file into the project; the changes made in the project are lost. Confirm with Overwrite Project Object

Open editors. A block, data type or tag table that is open in a Studio editor while you import its file shows the imported content right away. An editor with unsaved changes keeps your text; when you save it, Studio tells you that the project has a newer version and lets you decide.

Equal objects. An object that is the same on both sides cannot be synchronized; TIA Portal refuses it, and Studio says there is nothing to synchronize.

Saving a connected block in Studio. When you open a connected block from the Project Explorer, change it and save it, the block stays connected: Studio compiles the saved block, keeps its connection and writes the saved version to its file in the workspace folder right away, so the row stays Equal. One message names the file that was written. If the file could not be written, for example because it is read-only, a warning tells you to export the object from the Workspace Status before you import anything, because the workspace would otherwise show it as File changed.

Read-only files. If your version control system keeps files read-only until you check them out, an export into such a file is refused. Make the file writable, for example by checking it out, and try again.

After each action, the footer shows the running operation, one message sums up the result and names every object that was not processed, and the view reads the status again. When the files in the folder change while the tab is open, for example after a pull, the banner Files in the workspace folder changed. Click Refresh to read the current state. appears; the view never asks TIA Portal by itself.

When no object is connected yet, the view tells you to use Connect to Workspace or Export to Workspace in the Project Explorer.

A typical workflow with Git

1. Create a workspace whose root folder is the folder of your repository, or a folder inside it
2. Select the Program blocks folder and the PLC data types folder and run Export to Workspace...
3. Commit the files with Git, in Studio's source control or in any other client
4. After a pull, open the Workspace Status: the objects whose files arrived changed show File changed. Tick them and run Import Selected from Workspace
5. After working in TIA Portal, the changed objects show Project changed. Export them and commit again

What TIA Portal does

• TIA Portal writes one file per object, named after the object, and from TIA Portal V18 a .vci folder with the settings of the workspace into the root folder
• An export onto a file of the same name that is not connected yet overwrites that file without asking; Studio's confirmation says so before you start
• Both directions overwrite the other side: an export replaces the file, an import replaces the object in the project. Studio asks before every import and before resolving a conflict
• An object that is the same on both sides cannot be synchronized
• Deleting a workspace or a group, or disconnecting objects, never deletes files and never changes the objects in the project
• The workspaces are saved with the project

Known limitations

• Connecting, exporting, the status and synchronizing need TIA Portal V20 or newer. On V17 to V19 the workspaces can only be managed
• The content of software units is not covered: blocks, PLC data types and tag tables inside a software unit cannot be connected or exported from Studio, and an object of a software unit that was connected in TIA Portal itself appears in the Workspace Status without its kind
• TIA Portal offers the SimaticML format for technology objects, but may refuse to export one; the message names the object and the reason TIA Portal gave
• On TIA Portal V21 an object that is not compiled cannot be exported; compile it in the project and try again
• Importing a changed library type file is not offered on TIA Portal V20, because it would end TIA Portal. Import it with TIA Portal V21 or newer. Exporting library types works on both
• The language of a workspace is chosen once, when it is created
• Whether the version control interface is available depends on the installed TIA Portal version and update

AI assistant support

The assistant reaches the workspaces through the Manage TIA Version Control Workspaces tool. It lists the groups and workspaces, reads the status of a workspace and the file formats of objects, creates, changes and deletes workspaces and groups (a new workspace may live in the folder of the connected TIA Portal project, in your Documents or Desktop folder, in the export folder or in an open folder), connects objects to existing files, exports objects into a workspace (you may name a whole folder of the Project Explorer, such as Program blocks or a block group, and the files keep the folder structure of the project unless you ask for a flat folder; a root folder that does not exist yet is created after you approve it), disconnects them and synchronizes in the direction you ask for. For example: "Which workspaces does the project have?", "Export all blocks of PLC1 into the workspace StationA, folder Blocks" or "Take the changed files of Station_A into the project".

Listing and reading the status change nothing and run without asking. Before every other action the assistant shows you a card with what it will do, and runs it only after you approve it: the card of an import says that TIA Portal replaces the objects in the project, the card of an export that the previous content of each file is lost unless your version control system keeps it, and the card of a delete what is removed and that the files stay. An object changed on both sides is touched only when you name it and say which side wins. Afterwards the assistant reports each object that was not processed, with the reason. The tool is part of the tool category tia-version-control and needs the Pro plan. For how the AI chat reaches tools, see AI Integration.