Using version control for Node-RED flows

In this article, I will introduce version control of Node-RED flows using the Git integration functionality. This version control functionality is the core of Git integration with Node-RED, as the Git command is used within Node-RED to record version history. Even flow developers who are not familiar with Git commands, such as factory engineers, can easily use this functionality because it is available through the Node-RED flow editor interface.

Problems using the flow editor without versioning

When flow developers first start using Node-RED, they use the flow editor without Git integration. With this default setting, they tend to encounter the following problems.

Problem 1: Unable to revert the flow

When you press the deploy button, the current flow is deployed directly to the Node-RED server where the flow is running. The previous flow is then lost from the backend server. If there are any problems with the deployed flow, such as unexpected behavior or crushing the instance while the server is running, the flow developer will consider recovering it using the previous flow. Flow histories exist in the browser’s memory. Therefore, you can use the Undo key (Ctrl + z) to restore the flow. However, after you close the flow editor, you cannot use the Undo key to return to the previous state because the flow histories are deleted from the browser’s memory.

Problem 2: File-based manual backup

To avoid the above situation, some novice developers save their flows using the Download button on the Export dialog. But these procedures are time-consuming tasks because they have to keep track of file names along with the reason for the flow changes. If they do not have a previous flow to use to restore the flow, they will have to fix the problem from the broken flow. This fix will be impossible because the flow in mission-critical systems such as factory automation is very large and complicated.

Problem 3: Risk of Changing the Flow

When the flow has continued to work correctly, the flow developer is reluctant to modify the flow because of the risk of unexpected failure. The Node-RED flow sometimes contains redundant definitions for variable names or some code in the function nodes. When developers change the same definitions in the flow, they should carefully modify the node or software code correctly. In my experience, I have seen developers feel pressure during these operations because they are responsible for a large system. Ideally, they feel free to change the flow because Node-RED is a rapid development environment, but no one wants to change the flow once the developed flow works correctly in the production environment.

The Git version control integration frees flow developers from such problems. This feature provides version control using the Git command in the same way as general code development. After modifying the flow, if it works properly, flow developers can save the flow status to the version history by creating the commit with a message describing what changes they made. Using the version history with commit messages and timestamps, the flow developer can also restore the flow if necessary.

Procedures for using version control

(1) Enable version control

To enable Git integration, run the node-red admin init command in PowerShell or a terminal. You can enable this feature in the Projects section of the wizard. Also, the Git command is required to use this functionality. So you need to download the Git installer and set up Git using the installer. See the previous article for detailed instructions.

(2) Create a new project

After opening the flow editor, you will see the following dialog to create a new project.

In this dialog, select “Open existing project” in the first dialog. (If you have already created another project, open the menu at the top right of the flow editor and select “New” from the Project menu).

To create the new project, enter the project settings as shown in the screenshot above.

(3) Create your first flow

In this tutorial, we will use the simplest flow consisting of inject and debug nodes. After placing these nodes in the central workspace, create the wire between the nodes. Then press the deploy button to run the flow on the Node-RED backend server.

When you click the inject node’s left button, the inject node triggers the message to the wire. From the wire, the debug node connected to the inject node outputs the received timestamp number to the debug tab of the sidebar.

(4) Change the status of the flow file to the staging

The next step is to change the status of the first flow to staging. The staging state is the Git principle equivalent of “git add” to select files that should be committed to the version. Once the files are ready to commit, you make the record with the message, timestamp, and developer information in the case of the general step. In another case, we can also restore the flow to the previous state. In the next step, we will try both procedures to perform the commit after changing the flow status to staging and then restore the previous flow. On the History tab, there are two sections, “Local Changes” and “Commit History”, as you can see in the screenshot.

The Local Changes section is used to manipulate the local flow and associated files to add and remove them from the history. (“Commit History” is an area to check the recorded history. I will explain it later). In addition, the “Local Changes” section is divided into “Local files” and “Changes to commit”. In the next step, we will use the Local Changes section first.

Click the plus button on the flow file that has the “Stage change” tooltip. Clicking the plus button changes the status of the flow file to staging status and moves the flow file to the “Changes to commit” section, which means it is ready for commit.

(5) Commit the change with a message

The next step is to use the “Changes to commit” section. To commit to history with a specific message, click the “Commit” button in this section.

This will bring up the text area at the bottom of the section, where you can enter your commit message. As an example message, I typed “The first flow” into the area and then clicked the “Commit” button at the bottom of the text area.

If you’re familiar with the Git command, it might be easier to explain that “git commit -m <message>” was executed internally.

It deletes all working files from both sections within the “Local Changes”. This means that the file is recorded in the version history. When you open the “Commit History” section, there is a version history that includes the commit that was made.

At this point, the initial procedure for adding the commit to the version history is complete. As the next step, I will modify the flow and return it to the state of “The first flow”.

(6) Modify the flow

As an example of modifying the flow, the template node is inserted between the inject and debug nodes. To add the node to the flow, search and pick the template node from the palette, then release the node on the wire.

When the inject node’s button is clicked in this flow, the template node creates a new message, “This is the payload: <timestamp>!”. Using the debug node, you can check this message in the debug tab.

(7) Restore the flow

If you are having problems with the modified flow, you may want to revert to the previous flow, which you have named “The first flow”. To revert the flow, simply click the revert arrow button with the tooltip “Revert Change” in the “Local files” section of the “Local Changes” panel.

After clicking the button, the following notification dialog will appear. Of course, you should press the “Revert Changes” button in this dialog.

The flow editor immediately reverts the flow to the previous commit. So you can see the previous flow, which only consists of the inject and debug nodes.

As I explained above, the flow development is recoverable using Git’s integration functionality. All states of operations are stored in the persistent local filesystem. So even if you close or reload your browser, you can still recover your flow.

Next, I will explain other techniques related to operations.

Other techniques

Reverting flow using a Git command

In this tutorial, I explained that you can revert to the most recent commit in history. If you want to go back to the older commit, you will need to use manual command operations due to unimplemented operations on the flow editor.

First, you need to find the commit ID in the Commit History section of the History tab.

Copy the commit ID of the target commit to the clipboard. In the case of the screenshot, the commit ID of the “first flow” is “a3a61b0”.

Next, open PowerShell to run commands if you are using Windows. In the case of macOS or Linux, open the terminal for command-line operations.

Next, change the working directory to the directory that contains the project artifacts. On Windows, the directory containing the project files is “C:¥Users¥<user name>¥.node-red¥projects¥<project name>”. If the user name is “kazuhitoyokoi” and the project name is “awesome-app”, type “cd C:¥Users¥kazuhitoyokoi¥.node-red¥projects¥awesome-app”.

In a macOS or Linux environment, the working directory should be changed to “~/.node-red/projects/<project name>”. Type “cd ~/.node-red/projects/awesome-app”.

Finally, type the following command to revert to the previous commit

git reset --hard <commit ID>

In the case of awesome-app, type git reset --hard a3a61b0 to invoke the first flow. After restarting Node-RED and reloading the browser, you can see the first flow in the following screenshot.

In this command operation, the second flow was lost due to the ` — hard’ option. Therefore, flow developers need to use this operation carefully.

Showing the difference between commits

The flow editor has a UI that allows you to view the difference between commits by double-clicking the commit message or file name in the History tab.

The example above is the diff UI after adding the commit from the second flow. Because the output of the inject node was changed from the debug node to the template node, the blue inject node is highlighted with “changed” status. This commit added the template node to the flow. Therefore, the orange template node has the status “added”. The input of the debug node has been changed from the inject node to the template node, but it doesn’t have any change information because the flow format only defines the downstream of the flow content.

If you are interested in more details about each property of the node, you can also expand the elements in the tree view. The following screenshot shows the node properties after adding the second line to the template node.

In the tree view of the template node, there is a button highlighted by the red rectangle above to show the details of the differentiation. After clicking the button, you can see the differentiation between the lines.

This UI is also available for other nodes, such as the function and comment nodes, which have a multi-line text area.

Automatic commit addition

Sometimes flow developers forget to create a commit when they are focused on flow development. In this case, the flow cannot be recovered if it breaks. To avoid this situation, Node-RED has a useful feature to automatically add commits. To enable this configuration, open the “Manage palette” from the flow editor menu, and then go to the “Git config” tab in the user settings.

In the workflow settings on this interface, select “Automatic” from the “Manual” option. After enabling this configuration, whenever the flow is changed using the deploy button, the commit will be created in the background.

Conclusion

In this article, I introduced version control for Node-RED flows using Git’s integration features. I also mentioned several issues that developers may face when using the flow editor without version control, including the inability to revert flows, time-consuming file-based backups, and the risk of modifying the flow. Using version control can solve these problems by allowing developers to store flow status in the version history using commit messages and timestamps. By using version control, developers can manage their flows more effectively and feel more confident about making changes.