Move a game project from Perforce to Git with a guided transition
For LEADs and ADMINs who want a Perforce project to continue on Git. The guided transition keeps the project, its tasks, bugs and history in Gameheim, checks that nobody leaves work behind, maps the roles and moves the whole team on the same day. The same transition brings a project back from Git to Perforce. This guide walks through the three phases and what changes for everyone.
Why changing version control in a live production needs a plan
A studio changes version control for good reasons: a new publisher setup, a hosting choice, a team that already lives on Git. The files are the easy part. The hard part is the work in flight on the day of the switch, spread over every workstation of the team.
- Work that is not submitted yet. Pending changelists, files opened for edit and shelved changes live in each person's workspace or on the server. A move that does not wait for them leaves them on a workspace nobody will open again.
- Permissions. The roles that let people check out and submit do not give them the right to commit and push. Without a plan, the people who work on the project find themselves locked out on the first morning.
- Tools that keep running. Background checks, agents and scripts that still point at the old workspaces keep working on folders that are no longer the project.
- People who find out late. A switch that only the lead knows about turns into refused submits and confused messages.
How the guided transition works in Gameheim
In Gameheim a project changes version control through a transition with three phases. The project stays the same: tasks, bugs, crashes, builds, wiki and chat stay where they are, and their links to changelists keep working.
| Phase | What happens | What the team sees |
|---|---|---|
| Preparation | A checklist collects what has to be true before the move: no work left on Perforce, the new remote reachable with the content in it, roles mapped, every agent up to date. | A banner on every page of the project says the move is coming, what holds it back and what waits on each person. |
| Cutover | One action, when every blocking item is green. The project moves to Git and the roles receive their Git permissions. | The Git workspace appears in the sidebar. Perforce stays there as a read-only archive. |
| Closure | Every agent confirms it retired the old workspace, and the old server is archived. | The Perforce entries leave the sidebar. References on bugs and builds keep their Perforce label. |
How to move a Perforce project to Git in Gameheim
- The LEAD or ADMIN role in the organization.
- A Git remote for the project, with the content imported from the head of your Perforce stream.
- The Gameheim agent version 1.1.0 or later on every computer that works on the project.
- Git available on your Gameheim server (the Git option appears when you create a project).
Start the transition
Open the project settings and choose Move this project to Git…, then Start moving to Git. The checklist opens. Nothing changes for the team yet: everyone keeps working on Perforce, and the transition can be cancelled with a reason until the cutover.
Map the connection and the roles
Open Rules and permissions from the checklist. In 1. Connection enter the remote URL and the branch. In 2. Permissions choose, for every role that grants the Perforce workspace, what it becomes at the cutover:
- Git and Perforce: adds the Git workspace, keeps Perforce. Safe for people who also work on other Perforce projects.
- Git only: adds Git and removes Perforce from the role, in every project of the organization.
- Do not carry over: the role stays as it is.
Roles belong to the whole organization, so Gameheim lists by name who would lose or gain access, here and on the other projects, before you confirm in 4. Confirm. 3. What stays behind offers your
.p4ignoreas a starting.gitignoreto review.Let the team get ready
Every member now sees the banner. Whoever works on the workspace saves their Git token from it with Save your Git token and can test it with Test Connection: the first test that reaches the new remote turns The new remote is reachable green.
The banner also tells each person what waits on them, for example a changelist to submit or an agent to update. Ask everyone to submit or revert their work, unshelve or delete shelved changes and release their locks.
Clear the checklist
Use Ask agents for fresh news to have every agent report its workspace now. Confirm the manual items with a note, for example how the content reached the new remote.
Someone who left the studio and whose agent will never report again would keep the work items open for good. Choose Leave out of the checks next to their name and write why: everyone else stays checked, and the note stays with the transition.
Make the cutover
When every blocking item is green, click Move to Git, read what happens and type the project name to confirm. Gameheim checks the checklist and the roles once more, applies the role choices and moves the project. It cannot be undone.
Each agent receives the project on Git at its next sync and retires its Perforce workspace: the files stay on the disk and the Perforce client stays on the server. Everyone then clones the repository from Git Workspace, in a folder they choose.
Close the transition
Click Ask the agents to retire Perforce until every agent has confirmed, archive the old server or make it read-only, and confirm that item. Then Close the transition: the Perforce entries leave the sidebar and the project works on Git only.
What happens to bugs, crashes and builds after the move
Every reference carries its own version control. A bug fixed in changelist 4521 keeps «CL 4521 (Perforce)»; a bug fixed after the move links a commit. Builds show what they contain: a changelist for the old ones, a commit for the new ones.
- Fix present in. A build made after a move contains every fix made before it, because the new repository or depot starts from the old content: a fix made on Perforce is in every Git build, and a fix made on Git is in every build of the way back to Perforce. Within one version control the usual comparison answers: changelist numbers on Perforce, an agent that has the clone on Git. Changelist numbers of two Perforce periods are never compared, since the way back may be on another server.
- Regressions. A crash from a build made after a move reopens a bug fixed before it, in either direction, as it would have before the move.
- File history on a bug. A file of the Git repository shows its commits and authors, read from your clone. A Perforce file written before the move shows a notice instead: its history is on the archived Perforce server, and you read it there.
Going back from Git to Perforce
If Git does not work out for the team, the same guided transition brings the project back. On a Git project, open the project settings and choose Move this project to Perforce…, then Start moving to Perforce. The three phases are the same; what changes is what is checked and what is set up.
- Work in the clones. Instead of changelists and shelves, the checklist waits for No uncommitted changes, No commits left unpushed (on every local branch, not only the current one) and No stashed work. The agents report these counts with every Git command and when you ask them for fresh news.
- Connection. In 1. Connection enter the Perforce server (
host:port, withssl:in front for an encrypted server) and the depot, the stream or both. If the project was on Perforce before, they are filled in from that period. - Reachable server. The item turns green after a connection test reaches that server: anyone who saves their Perforce password from the banner runs one.
- What stays behind. Perforce protections and the typemap are set on the server, not by Gameheim. Set the typemap (for example
binary+lfor files that must be locked) before submitting the content: it does not apply to files already submitted. The.p4ignoreof the last period on Perforce is offered for you to copy and submit. - Content. Submit the content of the repository to the depot with your own tools, then confirm the item.
After the cutover everyone gets a new Perforce workspace, in a new folder, even on the same server as before. A project that was on Perforce before uses a new client name for the new period (for example GF-anna-OFT-2), so the old client, which remembers its files as already synced, is never reused. Git stays readable as an archive until the closure; then Ask the agents to retire Git, archive the repository or make it read-only on its hosting, and close the transition.
Perforce between the cutover and the closure
Until the transition is closed, P4 Workspace (archive) and Lock Dashboard (archive) stay in the sidebar under a read-only notice. You can still look at the last changelists and files your agents reported. Anything that would change Perforce is refused.
Frequently asked questions
Does Gameheim import the Perforce history into Git?
No. Gameheim moves the project, its people and its rules. The content of the Git repository comes from your own import of the head of your Perforce stream, and the Perforce server stays available, archived or read-only, for the history.
Can a project go back to Perforce after the cutover?
Yes, with a new transition in the other direction, with its own checklist. The cutover itself cannot be undone; before it, a transition can be cancelled at any time with a reason, and nothing has changed for the team.
What happens to work that was not submitted?
The cutover waits for it. The checklist stays open while anyone has pending, opened or shelved work, or while an agent has not reported recently. Only a person whose agent will never report again can be left out of the checks, with a note.
Are the Perforce files deleted from our computers?
No. After the cutover each agent stops working on its Perforce workspace and keeps a record of it, but the files stay on the disk and the client stays on the Perforce server. The Git clone goes to a different folder.
Which agent version is needed?
Gameheim Agent 1.1.0 or later on every computer that receives the project. The checklist names whoever still has an older one; an agent on a machine that is gone can be revoked from the agent settings.