> For the complete documentation index, see [llms.txt](https://staylime.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://staylime.com/docs/theme-companion/theme-updates/how-theme-updates-work.md).
# How theme updates work
An update in Theme Companion is a guided process: the app does the merging, you make the decisions, and nothing reaches your live store until you publish it.
### The update, step by step
{% stepper %}
{% step %}
#### Start an update
Pick the theme you want to update and the version to update to.
{% endstep %}
{% step %}
#### Review the update summary
You see what the update will touch: files carried over automatically, files with conflicts to resolve, and files that need a closer look. See [Understanding your update summary](/docs/theme-companion/theme-updates/understanding-your-update-summary.md).
{% endstep %}
{% step %}
#### Resolve conflicts
Where your customizations and the new version changed the same code, the app shows both sides and asks you to decide. See [Resolving conflicts](/docs/theme-companion/theme-updates/resolving-conflicts.md).
{% endstep %}
{% step %}
#### Preview and finish
Preview the updated theme on your storefront before committing to anything. When you finish the update, the updated theme stays in your theme library as a draft.
{% endstep %}
{% step %}
#### Publish when you're ready
Publishing is always a manual step you take in your Shopify Online Store. The app never publishes anything for you.
{% endstep %}
{% endstepper %}
### Your live theme is never touched
The whole update happens in a separate theme that the app adds to your theme library. Your live theme keeps running unchanged the entire time.
* Preview the updated theme at any point.
* Cancel the update at any point — your store stays exactly as it was.
* Publish the result only when you're happy with it.
{% hint style="warning" %}
While an update is in progress, avoid deleting the theme the app added to your theme library. If it does get deleted, your work is not lost — the app will offer to recreate it, and you can continue where you left off.
{% endhint %}
### One update at a time, 30 days to complete it
You can run one update per store at a time, and you have 30 days to complete it — pause and come back whenever it suits you. Most updates are finished in a single sitting.
### How your customizations are carried over
For every file, the app compares three versions: the original file as the theme vendor shipped it, your file with your customizations, and the file from the new version.
* Where only you changed the code, your change is carried over.
* Where only the new version changed the code, the new code is used.
* Where both changed the same code, that's a conflict — and it's shown to you to resolve.
Nothing is dropped silently: every customization the update touches is either carried over or shown to you as a conflict, and you confirm the final result.
{% hint style="info" %}
Updates never rewrite your templates, section groups, or theme settings — your layouts and choices stay exactly as you built them. New sections, blocks, and settings from the new version still become available in the Theme Editor; they just don't switch themselves on, so it's worth a look around the editor after updating.
{% endhint %}
### The longer you wait, the harder the update
Two things determine how hard an update is: how much you've customized your theme, and how many versions behind it is. The first is just your store being yours; the second is the one you can keep small.
* **A short jump** (one or two versions) usually means most files carry over automatically, and the few conflicts resolve with a click.
* **A long jump** means your theme and the vendor's version have each evolved a lot independently. Expect more conflicts, and some customizations may need to be re-applied by hand, because the code they modified has moved or no longer exists in the new version.
The takeaway: **update when a new version comes out — don't let versions pile up.** Regular updates stay routine; skipping many versions turns an update into a project. And if your theme is already heavily customized and several versions behind, consider [Get expert help](/docs/theme-companion/theme-updates/get-expert-help.md) — a fixed-price service where Staylime experts complete the whole update for you.
***
Wondering how this compares to Shopify's built-in theme updates — or what changes after your first update with the app? See [Theme Companion and Shopify's built-in updates](/docs/theme-companion/theme-updates/shopify-built-in-updates.md).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://staylime.com/docs/theme-companion/theme-updates/how-theme-updates-work.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
