Docs · Maintenance

Keeping your app up to date with the org build

How to pull the latest official LeadStack build into your own customised version of the app — without losing the changes you've made.

The mental model

There are three things in play:

Name	What it is	Git term
Org repo	The official LeadStack build. A read-only snapshot you don't push to.	`upstream`
Your fork	Your personal copy on GitHub, where your work lives.	`origin`
Your customisations	The edits you make on your `main` branch.	your commits

The org repo is published as a single snapshot commit that gets replaced each release. It has no shared history with your fork, so you cannot just git pull from it. The steps below give git the shared reference point it needs to merge cleanly.

One-time setup (do this once per machine)

# 1. Add the org repo as a second remote called "upstream"
git remote add upstream https://github.com/Claude-Code-Pro-Camp/leadstack-agency.git

# 2. Fetch its current snapshot
git fetch upstream

# 3. Create a local "vendor" branch that mirrors the org snapshot.
#    This branch is the shared reference point for future merges.
git branch vendor upstream/main

You now have:

origin → your fork (where you push)
upstream → the org repo (read-only)
a vendor branch tracking the org snapshots

Each time you want the latest org build

Always start from a clean working tree — commit or stash your work first.

# 1. Get the newest org snapshot
git fetch upstream

# 2. Move the vendor branch up to the new snapshot's contents
git checkout vendor
git read-tree -u --reset upstream/main
git commit -m "vendor: latest org snapshot"

# 3. Merge it into your own branch (this preserves YOUR changes)
git checkout main
git merge vendor

# 4. Refresh dependencies in case they changed
pnpm install

That's it. Your customisations and the new org code are now combined.

If you see merge conflicts

A conflict only happens where you and the org edited the same lines. Git marks them like this:

<<<<<<< HEAD
your version
=======
org version
>>>>>>> vendor

To resolve:

Open each conflicted file and edit it to the version you want (delete the <<<<<<<, =======, >>>>>>> markers).
Then finish the merge:

git add -A
git commit

Tip: git status always lists which files still need attention.

After updating — don't forget

pnpm install — pulls any new dependencies the update added.
Check .env.example — new features sometimes add new environment variables. Compare it against your real .env and fill in anything new.
Test the app (pnpm dev) before pushing.
Push to your fork when happy: git push origin main
(This goes to YOUR repo, never the org repo.)

Quick reference

I want to…	Command
See my branches and where they point	`git branch -vv`
See which remotes I have	`git remote -v`
Check for uncommitted work	`git status`
Get the latest org build	the 4 steps above
Preview what a push would send	`git push --dry-run origin main`

Common questions

Does pushing send my code to the org repo?

No. git push goes to origin — your personal fork. The org repo is upstream and is read-only to you.

What if I haven't customised anything yet?

The merge still works; there just won't be any conflicts.

I messed up a merge — how do I bail out?

Before committing: git merge --abort returns you to where you started.