UUID problem using git or similar tool?


I develop my site locally before transferring the changes to the production version. This local version is followed with Git.

What happens to the UUID?
To be clearer:

  • I have updated my local site with Kirby 3.8.0
  • I tested the site
  • I note with Git that the UUID field has been added and filled in automatically

My site in production is still under Kirby < 3.8. When I upgrade to Kirby 3.8 then the UUID fields will be added automatically to the content as the site is visited.
So, for a given piece of content, will the UUID field be the same in local and in production?

If the answer is no then this is a bit of a disaster as the local version is made different from the production version!


Ok, I found this topic:

Given the same Kirby installation, I can confirm that UUIDs generated in production are different than those generated locally.

Ok, thank you.
So I can’t update my production website and have to wait 3.8.1 :frowning_face:

In my understanding and opinion UUID is a Meta information that should not be mixed with the content. It should be contained in a separate file, as is done with images.

This separation would have avoided this problem between development and production environments.

The UUIDs are a fundamental piece of the content as they are used for references. So they absolutely need to match between different environments.

This should be done by generating all UUIDs in one go during the migration. Please see our migration guide:

The point is not about importance but about implementation: editorial content is thus mixed with technical information. In other words, information created by the author is mixed with information created by the CMS.

Before this, the content could be created directly by the author only from a text editor. Now it has to be processed by the CMS.

This has not been done before for important information, for example the date of creation of a content, its last modification date… Yet this information can be very useful

I understand your point and I agree with you in general. If you manage your content by hand and don’t use the Panel, UUIDs are a technical feature that may get in the way (depending on your site’s structure and the way you manage the content). This is the reason why we will add the option to disable UUIDs.

However please note that this has nothing to do with Git. UUIDs are intended to be checked in to version control (like Git). Otherwise references would break. So storing them in a separate file wouldn’t have any actual use beyond theoretical semantics. But on the other hand, a separate file would dramatically lower the system performance (because two files need to be opened and read for every page). This is why we decided to store UUIDs in the same content file.

This means you have the choice to either:

  • use the UUID feature (which means that you should migrate your existing content and then generate a UUID for every new page and file) or
  • disable the UUID feature entirely (possible with Kirby 3.8.1, which will be released this week).

Please note that you don’t have to let Kirby generate the UUIDs automatically. You can use whichever UUID string you like, but then you are responsible that this string is only used once throughout the site.

1 Like

Ok, thanks for the clarifications!

I misunderstood: it is obvious that this has nothing to do with Git which in this case is a revelator of what the content files have modified automatically.


One solution to consider is to store the information in the file name itself and not in the content.

And then the expected performance gains or rather the reduction of performance losses from the use of UUIDs instead of URIs must not be put before respecting the rule that separates the user’s content from that of the CMS.

To violate this rule is to open Pandora’s box.

The file name is already reserved for the template name. And the directory name is the URL path.

It’s not “content of the CMS”. Because the UUIDs are used as references from your own content (e.g. from a pages field or a select field), they also belong to the site’s content.

That sounds to me as if a database wouldn’t automatically store ids, because they are not user-defined content.

I was referring to a second file whose name was the ID. Automatically this file is linked to the template file.

No, no and no. The facts show that the user content files are modified by the CMS to implement this new functionality. This UUID is used by the CMS for functionality and is not user content.

A reference is not a content. Including it in a content-only file is an error.

Except when the reference is used as content by the user. In development, this is found in certain algorithmic structures such as lists, stacks, graphs… But that’s for computer development. Here we are talking about editorial content.

The beauty and strength of Kirby was that it did not mix editorial content, “content” and CMS operational data.

The id used by a database is indeed a technical information of the database and not a ‘redactional’ information provided by the user.

In the case of a database the user does not know how the content is structured behind the curtain: it is part of the internal kitchen that is hidden from the user. Whereas in Kirby the content is structured in the form of a file that the user can create and manipulate as he wishes: it is his content that is inside and not that of the CMS. This structuring is transparent and allows the incredible flexibility of Kirby.

In my humble opinion, it is a mistake to do this because a strong separation rule between user content and technical content has been broken and, as I said above, it is opening a Pandora’s box. And I suspect that this will, in the long run, cause a lot of trouble.

This UUID should never have been embedded in the user supplied content but in a file linked to the content file. For example, for a poem there would be:

  • poem.txt for the content, this does not change
  • poem.meta for the meta information including the UUID

I see your point to some extent, but must say that I don’t agree. Where exactly do you draw the line between user content and technical content. Is a non-default language slug still content? What about settings that are used for styling? What about a uuid that you add manually, as I have often done in the past?

An additional meta file imo would add additional overhead. For media files, there is no other option, because we cannot write to the files.

But as already written above, you can disable this feature from tomorrow. And its just my personal opionion.

With Kirby the site developer places this boundary between technical content and user content wherever he wishes, as he sees fit. For some, there will be no limit at all, as anything that can be written in the content file is de facto content. For others the CMS does not have to automatically add internal information such as a reference.
In the end, it remains the choice of the site developer.

In the case of the UUID it is Kirby that imposes this boundary and not the developer. Whether or not this feature is disengageable does not change this fact.
And it is likely that in the near future it will become essential for the implementation of new features.

Adding an additional meta file is indeed a tricky thing. But the experience gained with media files would have been very useful for this very purpose.

This choice, which in my opinion is the easy way out, really shocks me, I assure you, and I feel that it is an open door to future problems.

I think the issue is ideological purity (content file must only contain user content) clashing against practical reality (the only sensible way to store UUID in a flat file CMS is in the content file).

Reason 1) performance, 2) data integrity (keep UUID and content together).

This is how Statamic implemented their UUID, and as far as I see there’s no way to avoid it due to the above two reasons.

I disagree this is a open door (slippery slope), UUID is special. It’s so extremely useful, and is integral to the content data (act a unique identifier), that I think should be allowed as a special case.

Purity is the word. But purity only. Not purity with the ideological qualifier.

The only practical side I see is the immediacy of the solution: it is done immediately and without any technical or time overhead.
But this is done at the expense of the separation between user content and technical content: content integrity has been broken for technical integrity. And that is the choice I regret.

Your entire premise goes a bit out the window considering the fact Kirby was already using the content txt file to store non user generated content (or editorial content) for things like slug translations. A url is not content, it is part of the way the cms operates and yet it was stored alongside the rest of the content.

You also have the files’ txt that stores both user content, for example a caption, as well as more technical content, like the alt tag, and also quite possibly even more technical data like file size, orientation etc.

As much as I like your fight to preserve purity, I’d personally absolutely hate to see your idea of a separate file for UUID implemented. It would mean hundred of thousand more files on my server for no real benefit.

The best solution is for you to simply disable the UUID using the config and call it a day.

Before UUIDs Kirby didn’t impose any fields on my content: I was free to do what I wanted. Now it’s gone.

This is the cost of having this functionality, nothing else. This feature has a certain technical cost: it’s up to the developer to know how to manage the cost balance.

This is a cheap solution as in the future more and more Kirby features and plugins will require the use of the UUID. And it is likely that some plugins used now will become incompatible. What’s going to happen when the upcoming killer feature relies on these UUIDs and I’ll have no choice but to use it or leave Kirby?