> For the complete documentation index, see [llms.txt](https://studio-docs.sandbox.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.sandbox.game/source-control/daily-git-workflow.md).

# Daily Git workflow

## Opening: The Problem or Principle

Git works best as a daily habit, not an emergency backup. When creators save small, understandable checkpoints throughout the day, project history becomes useful instead of stressful.

A daily Git workflow is not about memorizing every command. It is about knowing when to check what changed, when to save a checkpoint, and when to sync with the rest of the project.

## The Core Explanation

### Start by Knowing the Project State

Before making changes, check the project state. This tells you whether the project already has unfinished work, whether files were changed by another tool, and whether your branch is ready for new work.

This matters because Git records differences. If you do not know what was different before you started, it becomes harder to explain what your work changed later.

For Sandbox Studio projects, this is especially important because generated files, assets, and editor changes can appear alongside code changes. Review the state before assuming every changed file belongs to the feature.

### Sync Before You Build

If the project is shared, bring in the latest remote work before starting a task. This reduces the chance of building on old files or discovering conflicts after you finish.

Syncing first is a small habit that prevents larger interruptions. It gives you a current starting point and makes later changes easier to compare.

### Make Small Checkpoints

A good checkpoint captures one meaningful change. It might be a finished documentation section, a working feature slice, a configuration update, or a bug fix.

Small checkpoints are easier to review, explain, revert, and share. Large checkpoints hide unrelated changes together, which makes collaboration slower and mistakes harder to find.

Think of each checkpoint as a note to your future self: what changed, why it changed, and where the project was stable.

### Review Before You Save History

Before creating a checkpoint, review the changed files. Confirm that the files match the task and that unrelated changes are not being included by accident.

This is where visual tools such as Fork can help. A visual diff makes it easier to notice generated files, accidental edits, or old experiments that do not belong in the current work.

### Sync After Useful Work

After a useful checkpoint is made, push or sync it to the remote repository when collaboration or backup matters. A local checkpoint protects work on your computer. A remote checkpoint protects it beyond your computer and makes it available to the team.

Do not wait until the end of a large feature to share progress if other people depend on it. Smaller synced checkpoints create a clearer project history.

## The daily command sequence

Run these from the project root. Scene files and generated `src/auto-imports.ts` / `src/game-data.ts` showing up in `git status` is normal — commit them. Do not edit those generated files; see [Project code fundamentals](/best-practices/project-code-fundamentals.md).

```bash
git pull                      # start of session: get teammates' work
# ... work in the editor and Cursor ...
git status                    # see what changed
git add .
git commit -m "Add health pickups to level 2"
git push                      # end of session: share your work
```

Replace the commit message with what this checkpoint actually did.

## If someone else already pushed

Your computer can be behind the GitHub copy even when your editor looks fine. `git status` will say the branch is behind `origin`, or `git push` will refuse with a non-fast-forward error. That means GitHub has commits you do not have yet.

### Bring in their work

Save your own work first (`Ctrl+S` / `Cmd+S` in the editor). Then from the project root:

```bash
git status
git pull
```

If `git pull` completes with no conflict messages, run `git status` again. You are current. If teammates changed TypeScript, run `pnpm build` from the project root, then **Build Project** (`Ctrl+B` / `Cmd+B`) so the editor matches the files you just pulled. See [Project code fundamentals](/best-practices/project-code-fundamentals.md).

If `git push` was the command that failed, pull as above, confirm the project still runs, then:

```bash
git push
```

Do not use force push (`git push --force`) to get past a rejected push. That overwrites the remote history other people already pulled.

### If Git refuses to pull because you have uncommitted files

Commit your checkpoint (the daily sequence above), or stash only if you know how to restore it. Then `git pull`. Pulling on top of mixed unsaved editor files and uncommitted Git files is how you lose track of which copy is newest.

### If `git pull` reports merge conflicts

Git lists the files. Open those files and finish the merge, then:

```bash
git add .
git commit -m "Merge remote changes"
git push
```

**TypeScript and other `src/` files:** paste the `git pull` output into Cursor and ask it to resolve the conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) for a named file. Review the result, then run `pnpm build`.

**Scene files (`*.genesys-scene`) and prefabs:** do not ask the agent to open or patch those files in Cursor. The editor owns them. After a conflicted pull, pick a side with Git (yours or theirs), then reopen the project in Sandbox Studio and rebuild the scene there if something is missing. If both of you edited the same scene, reconstruct the missing pieces in the editor rather than hand-merging the JSON.

**`.cursor/mcp.json`:** should never be in the repo. If it appears in a conflict, keep it out of the commit.

{% hint style="info" %}
*TIP: A prompt that works: "We ran `git pull` and got conflicts. Resolve only the conflict markers in `src/Gameplay/HealthPickup.ts`. Do not touch `.genesys-scene` files."*
{% endhint %}

## Practical Guidance

* Check project status before starting work.
* Pull or sync before building on a shared project.
* Work on one feature, fix, or documentation task at a time.
* Review changed files before creating a checkpoint.
* Keep checkpoints small and meaningful.
* Write messages that explain the purpose of the change.
* Push or sync useful work so it is backed up and shareable.
* Pause before saving generated, secret, or unrelated files to project history.

## Common Mistakes

| Mistake                             | What to do instead                                                                 |
| ----------------------------------- | ---------------------------------------------------------------------------------- |
| Waiting all day to save work        | Create small checkpoints after meaningful progress.                                |
| Saving unrelated changes together   | Review changed files and keep each checkpoint focused.                             |
| Forgetting to sync before work      | Pull or sync first when working with a shared repository.                          |
| Pushing while behind GitHub         | Run `git pull`, fix any conflicts, then `git push`. Do not force-push.             |
| Asking the AI to merge a scene file | Resolve `src/` conflicts in Cursor; rebuild scene changes in Sandbox Studio.       |
| Trusting every changed file         | Check whether files are generated, local, secret, or unrelated before saving them. |
| Writing vague messages              | Use messages that explain what changed and why it matters.                         |

## The Takeaway

Daily Git work is project memory built in small pieces. Check the state, make focused checkpoints, review what changed, and sync useful work before moving on.


---

# 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://studio-docs.sandbox.game/source-control/daily-git-workflow.md?ask=<question>&goal=<endgoal>
```

`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.