Version control for Shopify themes

If you're using the Shopify GitHub integration to develop your theme, then consider connecting your main or master branch to your store and then publishing the resulting theme. This ensures that the published theme is always up to date with features as they are merged to the main or master branch.

For events like sales, consider using non-main branches to customize your theme. Themes connected to these branches can be published temporarily. After the event is over, you can republish the theme that's connected to your main branch.

If you use a build pipeline to transform your code, then you should create a specific deploy branch that acts as your main production code branch, and then deploy the code that you compile off of master to this branch. To learn more, read about managing source and compiled code in the next section.

You might use a build pipeline to transform your theme's source code into compiled code that's optimized for browser runtime. Because the Shopify GitHub integration supports only branches that match the default Shopify theme folder structure, you need to organize your code so that a branch that's connected to Shopify matches this structure. For example, a branch that's connected to Shopify can't contain src and dist folders.

You can choose from several strategies to manage both your source and compiled code in version control:

• Use separate repositories for source code and compiled code
• Separate source code and compiled code using branches (recommended)
• Mix source code and compiled code
• If you don't want to track your theme code using the Shopify GitHub integration, then you can also choose to manage only your source code in version control.

Managing your source and compiled code using version control has the following advantages:

• You can leverage common build tools such as Webpack, Rollup, and PostCSS.
• Files can be incrementally built on the developer's machine, which allows for live previews of changes made to source code.
• Changes to compiled code via Shopify can be easily identified.
• You can push changes to compiled code to the store using the Shopify GitHub integration.

However, using this model, changes made to compiled code need to be manually backfilled into the source code.

A developer can have one repository that contains their source code and build tools, and another repository that contains a versioned representation of their compiled code.

• Using separate repositories is easy to adopt when moving from a source-only versioning model. You can continue to push compiled code directly to a store, and then use the Shopify GitHub integration to track changes to your compiled code over time.

• You need to work across two repositories for a single theme, which can make backfilling source code more complex.
• Static files that aren't impacted by file transformations are copied between repositories, resulting in extra maintenance and backfilling.

You can publish the compiled code for a theme in a separate branch from the source code. The contents of this branch are compatible with the Shopify theme platform and Theme Check.

One way to accomplish this is by using git subtree. Using the subtree command, you can extract your compiled code to a branch that can then be safely connected to a theme.

• There is a distinct location within your repository for your production code.
• The commit history of the branch is clean. The only commits in the production branches are updates to production code. Changes to source code stay in their own branches.

• Previewing the contents of a working branch requires another branch that contains the "preview" production code. Managing branches might become cumbersome.
• Static files that aren't impacted by file transformations reside in separate branches, resulting in extra maintenance and backfilling.

You can mix compiled code files within the same folder structure as the source code. For example, inside of an assets folder, you can add a main.js source file and a compiled main.min.js.

• Mixing source and compiled code minimizes the number of compiled files to only those that need to be compiled. This means that a merchant's changes to non-compiled files don't need to be backfilled or backported to your source code.

• Compiled code might be hard to identify, and merchants might edit it directly.
• If edits are made to compiled code, then they need to be backfilled to avoid being lost the next time the code is compiled from its source.

You can choose to commit only your source code to version control, and then deploy compiled code directly to a store when you want to create a release. Deployment can be done manually from a developer's machine using Shopify CLI, or automated using continuous integration.

• This approach is well supported in the Shopify theme developer community.
• It can leverage common build tools such as Webpack, Rollup, and PostCSS.
• Files can be incrementally built on the developer's machine, which allows for live previews of changes made to source code.

• Because the repo only contains source code that isn't compatible with the Shopify theme platform, this method isn't compatible with the Shopify GitHub integration.
• Compiled code isn't version controlled, which makes tracking changes difficult. You need to manually identify changes to the compiled code, and then backfill your source code so that changes persist the next time the code is compiled and the theme is overwritten.