# Update customized QBCore resources safely

Never overwrite a customized resource with a fresh download. Treat an update as a specific transition from a recorded deployed state to a reviewed target state, including callers, configuration and database changes.

This guide uses `qb-target` as the concrete resource example. Its `config.lua`, registrations and dependencies must be reviewed together. The accompanying Git exercise is a **synthetic training fixture**, not a real upstream release history or a FiveM runtime test.

![QBCore staging rollout and rollback checklist](/diagrams/rollout.svg)

*Conceptual diagram; verify the behavior against your installed resource version.*

## Inventory

For each resource, record upstream URL, deployed commit or release archive, local branch, uncommitted files, configuration owner, schema files and dependent resources. Pin the target before beginning; `main` can change during the review.

```bash
# Run inside the individual resource repository, not the server data root.
git remote -v
git status --short
git rev-parse HEAD
git log --oneline --decorate -10
```

Stop when the working tree contains unexplained changes. Save reviewed customization in a local branch/commit and preserve untracked files separately. Do not commit credentials or backup dumps. A Git tag does not capture uncommitted files, and a code backup is not a database backup.

## Compare without changing production

Work in a staging copy. Verify the actual default branch and remote instead of assuming every resource uses `main`. The example below assumes you have verified `origin` and its `main` branch:

```bash
git fetch origin main
git rev-parse HEAD
git rev-parse origin/main
git diff --stat HEAD..origin/main
git diff HEAD..origin/main -- fxmanifest.lua config.lua registration.lua client.lua
```

Read the release notes and changed code before merging. For the [documented qb-target baseline](/docs/resources/qb-target), inspect `PolyZone`, `config.lua`, `registration.lua` and `data/` as well as callers. For inventory, review [API and storage migration](/docs/troubleshooting/inventory-updates) separately.

## Worked update: retain a custom targeting distance

Assume the operator has deliberately customized `Config.MaxDistance` to `2.0`, and an incoming change touches the same line. Those numbers are training values, not recommended defaults or claims about an upstream release.

### Record a recoverable baseline

With a clean, reviewed staging working tree:

```bash
git tag docs-before-target-update
git switch -c docs/update-target
TARGET_COMMIT=$(git rev-parse origin/main)
printf 'Review target: %s\n' "$TARGET_COMMIT"
git merge --no-commit --no-ff "$TARGET_COMMIT"
```

Use a unique tag/branch name if these already exist. The tag points to the customized deployed baseline, not merely the original vendor commit. Keep the target SHA in the update record. If Git reports a conflict, the merge stopping is expected; do not run unrelated restore/reset commands.

### Resolve a config conflict deliberately

A representative conflict might look like this:

```text
<<<<<<< HEAD
Config.MaxDistance = 2.0
=======
Config.MaxDistance = 5.0
>>>>>>> incoming-update
```

Read why the incoming value changed. If the local `2.0` remains compatible with the new implementation, resolve that line to `2.0` while retaining other reviewed incoming changes. Do **not** accept the entire file with `--ours`: that can silently discard new settings or fixes. Do not accept it wholesale with `--theirs` and lose your local requirements either.

```bash
git diff --name-only --diff-filter=U
# Edit each conflicted file, removing all conflict markers.
git add config.lua
git diff --cached --check
git diff --cached -- config.lua fxmanifest.lua registration.lua client.lua
git status --short
```

If the change cannot be reconciled, `git merge --abort` returns to the clean pre-merge state. This is why recording a clean baseline matters. If it can, commit the reviewed merge on staging and record its resulting SHA; a successful merge is not permission to deploy it.

### Run the reproducible Git exercise

From the documentation repository, run:

```bash
bash scripts/examples/resource-update-fixture.sh
```

The script creates an isolated temporary Git repository, introduces a real same-line config conflict, verifies abort, resolves the conflict while retaining another incoming setting, and verifies a baseline rollback. It uses no network, no production directory and no player database. It prints stage results and removes only its own temporary directory.

This tests the Git mechanics described here. It does not prove that changing a targeting distance is correct for your server. The fixture is also exercised by the documentation regression tests.

## Staging acceptance tests

For a `qb-target` update, keep a small known fixture: one BoxZone, one NPC interaction, an allowed/denied job condition and a server-authorized action. The [target guide](/docs/resources/qb-target) supplies the registration patterns.

| Check | Pass evidence | Rollback trigger |
| --- | --- | --- |
| Startup | Required resources start; no new error before registration | Missing export, dependency or syntax error |
| Zone geometry | Known outline and action at measured position/height | Zone missing or interaction reach changed unexpectedly |
| Job/item restrictions | Allowed player sees option; denied player does not | Filter regression |
| Server authorization | Wrong job or remote request is rejected | Any unauthorized operation succeeds |
| Resource lifecycle | Registrations disappear/reappear as designed during coordinated restart | Duplicate or missing registrations |
| Integration | Existing menu/stash action and reconnect still work | Caller mismatch or persistent state regression |

These are manual FiveM acceptance checks. Record actual results, resource SHAs and tested scenarios; do not label them passed merely because a documentation build or Git fixture passed.

## Rollout

Back up files and the database, prove restoration in staging, resolve the reviewed update, and run the acceptance matrix. Then schedule an approved maintenance window, pause relevant writes, deploy the exact reviewed commit set and perform the same smoke checks. Record the deployed SHAs and rollback triggers.

Do not hot-restart qb-core underneath players as a general update method. A standalone UI resource, an inventory migration and a coordinated core update have different lifecycle requirements. Use your existing [compatibility checklist](/docs/migration/tools/compatibility-checker) and [backup guide](/docs/migration/tools/backup-restore).

## Rollback

Before production deployment, prepare a rollback artifact from the known baseline rather than an emergency `git reset --hard` in a directory containing untracked customization:

```bash
# In the reviewed repository; code only, not assets outside Git or the database.
git archive --format=tar docs-before-target-update > ../qb-target-before-update.tar
```

Keep that archive and required external assets in a private backup location. During recovery, stop the affected coordinated resource set, restore the previous artifact/configuration and restart through the established deployment process. Verify the restored SHA and smoke tests.

For a schema/data migration, restoring files is insufficient. Restore the matched database snapshot or execute a previously tested reverse migration. Decide how to reconcile legitimate transactions made after the backup; silently discarding those writes is not a safe rollback.

## Sources

- [qb-target pinned resource](https://github.com/qbcore-fivem/qb-target/tree/a3ea78b283421336e28198fb6f2142119f1b8f0a).
- [Git merge documentation](https://git-scm.com/docs/git-merge): conflicts, `--no-commit`, `--no-ff` and abort behavior.
- [Git archive documentation](https://git-scm.com/docs/git-archive): archive a named tree.
- [Inventory migrations](/docs/troubleshooting/inventory-updates) and [update conflicts](/docs/troubleshooting/resource-update-conflicts).
