Synchronising Changes × Mattrbld

As pointed out before, Mattrbld works locally on your device. Every change you make stays on your device until you push it back to the central Git repository that houses your project. This is different from other headless CMSs which either work entirely on a server, or push every single change you make no matter how small it is, causing unnecessary runs of CI services and thus incurring unnecessary costs.

In this article, you will learn how to sync the local changes you made using Mattrbld with the remote Git repository and what steps Mattrbld takes to ensure that you are always working with the latest version of your project.

Staying Up-To-Date

There are two times when Mattrbld fetches the latest version of your project from the remote repository:

When first opening the project via the Home screen
Before pushing any local changes to the central repository during the sync process

If you are working offlline, or Mattrbld isn’t able to perform the first fetch (technically a git pull) for any other reason, it will warn about it and offer an option to retry if possible. Currently, there’s no way to force a manual refresh of a local project other than closing and re-opening it from the Home screen.

If you’re working on a project that is hosted on a private repository, you will be asked to authenticate whenever the local version is to be updated. You can learn more about how this works in the article on authentication.

Synchronising Local Changes

As soon as you edit a file in Mattrbld, it will be marked as “locally changed”, which is usually also visually shown by adding an orange marker or chip next to its name. It will also be listed in the “Local Changes” section of the project dashboard.

As you use Mattrbld, you’ll notice that files are generally marked either as “in sync” with a green marker, or “locally changed” with an orange marker. These correspond to the colour of the project status chip visible in the project sidebar and allow you to know at a glance whether or not a file has been modified since it was last synchronised with the remote repository.

All of these locally changed files are only changed on your device, even if they aren’t marked as drafts. In order to share them with others, they will have to be synced. If, for example, you are working on a website project in Mattrbld and you create a new page, this page won’t be visible as soon as you create it, even if it’s not marked as a draft, but only after you have synced it back to the central repository (and a CI re-generated the website, if necessary).

Since syncing also pushes your local drafts back to the remote repository so you can continue working on them on a different device, it is deliberately referred to as “synchronising” and not “publishing”—if the project is configured correctly, drafts will stay private until published.

How to Sync

All your local changes are synchronised via the “Sync local changes” dialog, which you can open from the project dashboard, or by clicking the status chip next to the project name in the sidebar when it is orange and labelled “changes”.

The sync local changes modal in Mattrbld, showing a field to add a commit message and the option to select what changes should be synchronised. In this case, one file is marked as modified, while two are marked as "added" and one as "removed". A purple button in the bottom right corner is labelled "Sync 4 changes"

In this dialog, you can add a message describing the changes you have made which will then show up in the “Recent Changes” section of the dashboard so your collaborators (or your future self 😉) know what changed. If you’re familiar with Git, this is your commit message and if left blank it will default to ‘Updated content through Mattrbld’.

Below that input field you will be able to select which changes you would like to include in this particular sync—you don’t have to sync everything at once, but keep in mind that anything you do not sync will only be accessible on the device you are currently using.

You will also be able to see what changed in files labelled as “Modify” or discard all local changes to a particular file by using the corresponding options in the context menu when right-clicking one of the list entries.

Discarding the changes in a file is a destructive action that cannot be undone. Mattrbld will ask for your confirmation before doing so, but be absolutely sure you know what you are doing before confirming the discard.

And finally, a click on the “Sync xyz changes” button will start the sync process, which consists of:

Pulling the latest changes from the central repository
Pushing any drafts (if configured)
Pushing all other files

If you haven’t opted into remembering your password until the end of the session, or if you’re working on a public repository, you will be asked to authenticate once again before the sync process can complete.

Checking Changes

If the sync dialog shows files you weren’t aware of changing, you can show what was changed in them by right clicking the file and selecting “Show changes”. This will open another dialog which will show additions to the file in green and removals in red.

A screenshot of the change details modal in Mattrbld showing what changed between the local version of the blog post and the one on the server. Removals are shown on a red, additions on a green background — Changes in a Mattrbld Devlog

Like Git, Mattrbld operates on a line-based differentiation system, so if you encounter a line that has both additions and removals, this means that the line was modified instead of simply being added or removed.

Keep in mind that changes can only be displayed for files that were modified, since files that were newly added or deleted cannot be compared to anything. Since binary files, such as images, are always replaced, you also won’t see what changed for those either.

As of version 0.3.0, Mattrbld creates a hidden, empty file named .gitkeep in every directory you create via the Mattrbld interface. This has to be done so those directories get synced between devices, since Git cannot sync empty folders.

As such, you can view these files as recording the creation of the directory itself. If you do not sync them and there are no other files in the directory, the directory won’t appear on other devices, which can lead to issues for example when a content directory only contains drafts (since those are technically stored in a different place).

Moving On

From importing, over configuring and collaborating, to syncing the local changes, you have now learned most of what there is to know about projects in Mattrbld, which concludes this section of the documentation.

The next section will teach you how to set up Schemas and Collections so the content of your project can be managed through Mattrbld. If you haven’t done so yet, now would be a great time to import your first project and set it up, so you can follow along with the next articles. 😊

Staying Up-To-Date

Synchronising Local Changes

How to Sync

Checking Changes

Moving On

Take full control over your content.