Thoughts on Version Control for Block Themes

How do we handle version control for ongoing development of a block-based website? I’m not actually sure, but I’m outlining a few thoughts/goals as I think about the workflow here. My hope is to get some feedback from the wider developer community, to find out what’s been working and what tools are missing.

Keeping Templates in the Theme

Obviously the goal of Full Site Editing is to be able to edit the markup of your site in the site editor – but what if I want those changes tracked in a git repository (rather than relying on the revisions feature in WordPress)? Traditionally, we tracked layout and design updates in the theme.

For example, if I update my header or an archive layout, can those updates be stored in the theme so that I can commit them via git, track them visually, sync them between environments, deploy them and revert them quickly? And is this even the most desirable approach?

I understand that the editor’s Revisions feature is getting more robust, but I’m probably not alone in preferring to have a git-based version control workflow as well. The area where we’re seeing the most traction towards this is in the create-block-theme plugin, a tool that can manually export your templates and theme.json into a theme folder for distribution (though with a few caveats).

But.. in the era of block themes, what even are templates, layouts, patterns, etc? Why are they even different things?

Everything is a Pattern

From what I can tell, the trajectory that the site editor is taking is that everything can be a pattern. Reusable blocks became patterns. Template parts are becoming patterns. Partially-synced patterns are becoming a reality. Even create-block-theme turns the templates you built in the editor into patterns in your theme folder.

Think about that: create-block-theme converts templates you make in the editor (like your single.html) into a separate block pattern, then imports that pattern into the HTML template file via the Pattern block. Which is great! I like that a lot. But if you make actual patterns in the editor, for some reason they don’t get exported into your theme.

Pattern Manager from WP Engine handled this really well. You would build patterns in the editor, and they get stored in your theme as PHP files. Pattern Manager was even smart enough to let you edit patterns that you added to your theme manually: it was not storing even these patterns in the database, it was storing them in the theme. The theme becomes the one source of truth. Why is this important?

If you’ve ever used Advanced Custom Fields with multiple environments and multiple developers, you know that it can get tricky really fast. You’re constantly making sure everything is synced properly before making any edits because there might be two sources of truth: the filesystem and the database. ACF-JSON is great at attempting to solve that problem, but there are always some weird edge cases.

I believe the site editor needs to solve this problem by offering a comprehensive solution for managing template files in your theme, while still being able to edit them in the block editor. It needs to be intuitive and simple, reliable and well-supported.

My ideal approach (and should I work on making this a reality?)

I want the best of all worlds. In broad strokes

  • I want the ability to store as much as possible as a pattern and use the (partially?) synced pattern block where ever appropriate. The general flow for design should be blocks 👉 patterns 👉 templates. Put individual blocks together to make a pattern, put a few patterns together to make the full page template. In that sense, the “pattern” as a concept should basically replace template_parts in WordPress.
  • I want the ability to use the filesystem as the primary source of truth for block patterns, templates, and theme.json. Currently patterns added to a theme are not editable in the site editor. And patterns added via the site editor are not added to your theme with create-block-theme.
  • When I save a change to a pattern or template (assuming I have ‘theme’ development mode enabled) that change is immediately reflected in my theme’s filesystem, not the database. No need to run a separate manual export process, I just want changes to what I consider the ‘theme’ to be saved in the ‘theme’ when my development mode is set to ‘theme’. Then I could use git to manage and deploy those theme changes across multiple environments.

I’m not saying I want this for everybody, but I feel like it would drastically improve the developer experience for block themes, especially in managed sites with a lot of ongoing development. I’m currently getting close to this by mixing create-block-theme and Pattern Manager, but it feels like we could get completely there with one solid tool. I’ve even considered pulling the best parts of those two tools and putting them together for this very specific use case.

If this were combined with partially-synced patterns and the Block Binding API, I think we’d have a really solid answer to the concerns around building your site completely in the site editor.

What are your thoughts? Would you want to be able to have all of your patterns, templates, and theme.json changes automatically synced to your filesystem so you could manage it with Git? Is there a better way?

Update: There’s now an official discussion on the Gutenberg repository for this: 59480

Update 2: Here’s another post worth checking out, Git going with FSE and Block Theme Development, by Claudio Rimann.

Learn Modern WordPress Development

I’m sharing the best resources and tutorials for developers building in and on the block editor.

7 responses to “Thoughts on Version Control for Block Themes”

  1. Steve Dufresne Avatar
    Steve Dufresne

    We should be able to save changes to disk in development mode.

    Opening a tickets in the repo would be a great start:

    1. Brian Coords Avatar
      Brian Coords

      Agreed. It seems like all the work related to this is happening in the create-block-theme repo, rather than in Gutenberg: https://github.com/WordPress/create-block-theme/issues/431

  2. Lukasz Avatar

    Thank you for writing this! – the site editor professional DEV workflow is broken. Was FSE never meant for the pros?

    Here’s a reddit thread showing how confusing the current workflow is:


    1. Brian Coords Avatar
      Brian Coords

      Interesting – thanks for bringing this thread to my attention. I think they’re expecting the developer/agency/freelancer communities to establish some best practices here.

  3. Cullen Whitmore Avatar

    This is a great post, Brian. It encompasses the same issues (and expectations) my team is encountering.

    The third bullet in your ideal approach is key. If something like this were to happen, I think a hosting platform like Pantheon would have an advantage. With file edits being disabled for production environments, the changes are made in dev and immediately written to the theme folder. This forces the developer to commit the changes before being deployed to production.

    Another critical feature for version control and protecting a production environment is a method to lock down the editor or surface the changes made so they can be committed to the repo. I’ve worked on a proof of concept that adds a new “developer” role to WP and looks for a constant in wp-config.php. Using these, we’re able to disable the site editor for other users. It’s rough, but works.

    1. Brian Coords Avatar
      Brian Coords

      Glad to know we’re all thinking the same. That’s a good sign IMO.

      I think if I were to boil down the major process gaps underneath this, I would have to say:

      – version control broadly (getting templates/patterns into your theme more seamlessly, keeping them locked their)
      – navigation block bringing back menu locations that aren’t tied to a post type
      – content/access locking (more granular controls for both block locking as well as feature locking)
      – truly synced patterns, where you can actually lock/control them in your theme but allow users to change minor aspects of content/design

      Were you the one on the outreach call who brought up the whole “code goes up, content comes down”? That’s really the central goal here.

  4. Jeff Brand Avatar
    Jeff Brand

    This captures much of my current frustration with the new full site editor. I need to strike a balance with a wide variety of clients, some who NEED a tested, refined theme change deployed quickly and precisely, and others who want to tweak their own live site’s design. Storing layouts in the filesystem would give both clients a method to capture incremental changes with a “tangible” self-contained file snapshot, not a database export.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.