p4 reconcile: bring offline and unchecked-out work back into Perforce
Sooner or later everyone edits a file without checking it out: in the Unreal Editor with "Make Writable", in an external tool, on a train with no connection to the server. Perforce does not see those changes until someone reconciles the workspace. This article explains what p4 reconcile does, why unreconciled files cause silent sync problems, and how Gameheim scans your workspace, filters the noise Unreal generates and lets you track everything in one pass.
Why files edited without checkout are a problem in Perforce
Perforce tracks your work through the server, not through your disk. A checkout (p4 edit) records on the server that you are changing a file and makes it writable. Anything you do to files without telling the server stays invisible to Perforce:
- Edited without checkout. You cleared the read-only flag (Unreal's "Make Writable", or the file properties in Explorer) and saved. The file differs from your have revision, but it is in no changelist.
- New files. You copied textures into
Content/, or the editor created new assets. Perforce does not know they exist until they are added. - Deleted or renamed files. You deleted or moved files on disk. The server still thinks they are there, under their old names.
The consequences are worse than a forgotten file. With the default noclobber workspace option, a sync does not overwrite a writable file that is not checked out. It prints Can't clobber writable file for that file, updates everything else and finishes, so on a sync of thousands of files the message is easy to miss and the file stays behind the depot. If nobody has submitted a newer revision of the file yet, there is no message at all: the sync has nothing to do for it. Meanwhile, if the asset is locked by type, a teammate can check it out and submit, because you never took the lock.
Perforce's answer is p4 reconcile. It compares the workspace with the have list and opens each difference in a changelist: edited files for edit, new files for add, missing files for delete. With -n it only previews what it would do. It is thorough, and on a large Unreal workspace with hundreds of thousands of files it is also slow, because it examines every file.
How Gameheim finds and tracks offline work
Gameheim shows every change Perforce does not know about in the Workspace Changes panel of the P4 Workspace page. It uses two kinds of scan, both read-only previews that list changes and modify nothing:
| Smart scan | Full scan | |
|---|---|---|
| How it works | Walks your workspace folder and compares each file's modification time and size with a local cache on your machine. Perforce is asked only about the folders where something changed, and not at all when nothing did | A server-side reconcile preview that asks Perforce about every tracked file |
| Speed | Typically 5 to 30 seconds | Minutes on large workspaces |
| Catches | Every edit saved by the Unreal Editor, an IDE or any tool that writes files | Also the cases a smart scan cannot see: cache drift, files moved while the agent was offline, partial syncs, cache corruption |
| Started by | The automatic schedule, or the first visit of the day | Scan Now, the automatic full schedule, or the first visit of the day if you choose it |
Results are grouped by folder into Modified (not checked out), New Files (untracked), Missing Locally and Possible Renames, with one action per group and Track All to handle every relevant change at once.
Less noise from Unreal
- For Unreal projects, the scan excludes the
Intermediate,SavedandDerivedDataCachefolders by default, because the engine rebuilds them on every machine. Unity projects excludeLibrary,Tempandobj. - Folders that are almost always generated, such as
Binaries,Build,Logs,.vsand.idea, are collapsed and counted as excludable. The panel header shows how many changes are relevant and how many are excludable, and Track All skips the excludable ones. - Folders that usually matter, such as
Content,SourceandConfig, are expanded by default. __ExternalActors__and__ExternalObjects__are never treated as noise: with One File Per Actor they hold real level content.
A check before every sync
Separately from reconcile, Gameheim runs a Local changes check in the background: it looks for files that the next sync would skip because they are writable, behind the depot and not checked out. They appear in the Local changes (no checkout) panel, and the sync dialog lets you decide what to do with each one before anything is overwritten.
How to reconcile offline work in Gameheim
- The Gameheim Agent is running and connected; scans run on your machine.
- Your role includes
p4_workspace:checkout, needed to run a scan and to check out, add or delete the files it finds. - Close the Unreal Editor, or at least save everything, before a full scan, so the files on disk are final.
Choose your reconcile settings
In the Workspace Changes panel, click Reconcile settings. The settings are yours alone and apply to this project only. A reasonable start for an Unreal workspace: Auto smart reconcile every 5 to 10 minutes, Auto full reconcile OFF or every 4 hours or more, and First reconcile of the day set to Smart. See the reference table below for every option.
Run a full scan when you need certainty
Click Scan Now after a period offline, after copying files into the project by hand, or before an important submit. It is slower but authoritative. While it runs, other Perforce actions on your workspace, such as creating a changelist or checking out, can slow down or wait briefly.
Review what the scan found
Expand the folder groups. Use the search box to find a file, and open the diff of a modified file to compare your local copy with the revision you have. Check that new files are really yours before adding them: an unexpected file in
Content/may be an asset the editor created in an earlier session.Track each kind of change
- Modified (not checked out): Checkout opens the file for edit with your changes; Revert local discards them.
- New Files (untracked): Add opens them for add; Hide removes them from the list for now.
- Missing Locally: Mark for Delete deletes them in the depot at your next submit; Restore downloads them again.
- Possible Renames: Confirm records a move from the old name to the new one; Split treats it as a separate add and delete.
Or track everything at once
Click Track All to check out every modified file, add every new file and delete every missing file in the relevant groups. Gameheim asks which changelist to use: the Default changelist, an existing one, or Create new changelist.
Decide on files a sync would skip
If the Local changes (no checkout) panel lists files, click Open Sync Dialog. For each file choose Skip (keep your copy, it stays behind the depot), Open for edit (turn your edit into a pending change), Open + resolve (check out, sync and merge safely; conflicts go to Conflicts to Resolve) or Force sync (take the depot version and lose your edit). The default is Skip.
Submit the result
The tracked files are now in a changelist like any other. Submit it as described in Submit and shelve changelists.
How to reconcile offline work by hand with p4 and P4V
Reconciling is a Perforce operation, so it works the same from the command line, from P4V or through Gameheim. This is the manual procedure. Close the Unreal Editor first, or at least save everything, so the files on disk are final.
1. Preview what changed
Always start with a preview. -n lists what reconcile would open without opening anything. Scope it to the folders you actually worked in: reconciling the whole depot path of a large Unreal project reads every file.
p4 reconcile -n //depot/MyGame/Content/...
p4 reconcile -n -e -m //depot/MyGame/Content/...
p4 diff -se //depot/MyGame/Content/...
p4 diff -sd //depot/MyGame/Content/...-e,-aand-dlimit the preview to edited, added or deleted files.-mtogether with-echecks modification times before computing file digests, which is much faster on large binary assets.p4 diff -selists files that are not open and differ from the revision you have (edited without checkout).p4 diff -sdlists files that are not open and are missing from disk.- In P4V, right-click a folder in the workspace tree and choose Reconcile Offline Work. P4V shows the same three lists and lets you pick the files and the changelist.
2. Open the changes in a changelist
When the preview looks right, run the same command without -n, into a numbered changelist so the work stays separate from anything else you have open. Files matching your .p4ignore are not added, provided P4IGNORE is set in your environment.
p4 change
p4 reconcile -c 1234 //depot/MyGame/Content/...
p4 opened -c 1234p4 change opens the changelist form in your editor and prints the new number when you save it. p4 opened -c lists what ended up in the changelist; revert anything that does not belong there before you submit.
3. Deal with files a sync would skip
A file that is writable and not open stays behind on every sync until you decide what it is. To keep your edit, check the file out, sync and resolve. To throw your edit away, force the sync of that one file.
Keep the local edit, or take the depot versionp4 edit //depot/MyGame/Config/DefaultGame.ini
p4 sync //depot/MyGame/Config/DefaultGame.ini
p4 resolve -am //depot/MyGame/Config/DefaultGame.ini
p4 sync -f //depot/MyGame/Content/Props/Crate.uassetp4 sync -f overwrites the local file with the depot version. Run it only on files whose local edit you really want to lose, never on a whole folder you have not previewed.By hand and in Gameheim
| Step | By hand | In Gameheim |
|---|---|---|
| Preview offline work | p4 reconcile -n on the folders you worked in, or Reconcile Offline Work in P4V | Smart scan or Scan Now, grouped by folder |
| Filter generated files | .p4ignore plus careful scoping of each command | Intermediate, Saved and DerivedDataCache excluded by default for Unreal; other generated folders collapsed as excludable |
| Open the changes | p4 reconcile -c <changelist> | Per-group actions or Track All, with a changelist picker |
| Remember to check | Your own habit | Optional automatic scans, and a smart scan on the first visit of the day |
| Files a sync would skip | p4 diff -se, then p4 edit and p4 resolve, or p4 sync -f | Local changes (no checkout) panel and a choice per file in the sync dialog |
Reconcile settings reference
| Setting | Options | Default | What it does |
|---|---|---|---|
| Auto smart reconcile | OFF, every 5, 10, 15, 20 or 30 min | OFF | Background interval for the smart scan. Adaptive: it doubles while you are idle and returns to the base interval when you are active |
| Auto full reconcile | OFF, every 30 min, 1h, 2h, 4h, 8h, 12h, 16h or 24h | OFF | Periodic full scan as a safety net. Heavy on very large workspaces (more than a million files can take 10 to 15 minutes or more) |
| Local changes check | OFF, every 5, 10, 15, 30 or 60 min | Every 10 min | Looks for files a sync would skip. Runs a server-side check, so a longer interval is lighter. OFF also hides the Local changes panel |
| First reconcile of the day | Smart, Full, Ask me | Smart | What happens the first time you open the workspace each day. Ask me shows a prompt with an estimate of how long a full scan takes on your workspace |
| Cache invalidation threshold (under Advanced) | OFF, 4h, 8h, 12h, 24h, 48h, 7 days | 24h | When the smart-scan reference point is older than this, the panel shows Full scan recommended, so a full scan can re-establish it after a night or weekend away. Smart scans keep running meanwhile |
Automatic smart scans and the local changes check are scheduled by the P4 Workspace page: they run while the page is open in a browser tab you are viewing, and pause when the tab is hidden. When Auto full reconcile is on, Gameheim also starts the full scan itself while your agent is online, even with the page closed. Both automatic scans are off until you turn them on, so nothing runs against your workspace without your consent.
.p4ignore versus scan exclusions
Two different filters decide what you see, and they work at different levels:
- `.p4ignore` works at the Perforce level. Files matching it are never added to the depot by
p4 addorp4 reconcile. Leads and administrators edit the project.p4ignorefrom the .p4ignore button in the workspace bar. Save & Push to Agents submits the file in its own changelist and writes the same content to every teammate's workspace root. Each person needsP4IGNORE=.p4ignoreset in their Perforce environment for it to take effect. - Scan exclusions and noise groups work at the Gameheim display level. They hide generated folders from the Workspace Changes panel, including files Perforce already tracks, but they do not change what Perforce accepts.
When an untracked noise folder keeps appearing, a lead or administrator can click the .p4ignore? suggestion next to it to add that folder to .p4ignore. The example .p4ignore shown in the editor for Unreal excludes Intermediate/, DerivedDataCache/, Saved/ and project-level Binaries/, and deliberately does not exclude Plugins/**/Binaries/, because binary-only vendor plugins ship their DLLs precompiled and need them in the depot.
Troubleshooting reconcile and scan banners
| Message | Meaning | What to do |
|---|---|---|
| Smart reconcile paused | The agent restarted, its cache is cold, and auto full reconcile is OFF | Click Scan now once; smart scans resume afterwards |
| Full scan recommended | The reference point is older than your cache invalidation threshold | Click Scan now. Smart scans keep running meanwhile |
| Skip check postponed | A workspace scan is running, and Perforce runs one scan at a time on a workspace | Nothing: the check runs again when the scan finishes |
| Perforce is not configured for user-side stop | Stopping a reconcile leaves the Perforce server working until it finishes | Ask your Perforce administrator to enable it; see Perforce server administration |
- A file you edited does not appear. The smart scan relies on modification time and size. A tool that rewrites a file with the same size and time can slip past it. Run Scan Now.
- Thousands of new files after opening a level. Unreal may have created One File Per Actor files for actors in the level. They are real content: review and add them with the map, do not hide them.
- Files on disk that Perforce never knew about. If they are leftovers rather than work, use Clean Untracked in the Sync Status panel to review and delete them. See Perforce workspace setup for Unreal Engine.
Frequently asked questions
What does p4 reconcile do?
p4 reconcile compares your workspace with the files Perforce thinks you have, and opens every difference in a changelist: modified files for edit, new files for add and missing files for delete. Run with -n it only lists what it would do. It is the standard way to bring work done without checkout, or while disconnected from the server, back under Perforce control.
How do I work offline with Perforce?
Edit files by making them writable, add new files and delete old ones as usual. When you reconnect, run a reconcile to open all those changes in a changelist, then submit. For binary assets that are locked by type, remember that working offline means you do not hold the lock, so a teammate may change the same asset in the meantime.
Why is p4 reconcile slow on Unreal projects?
A full reconcile examines every file in the workspace and compares it with the server record, and Unreal workspaces often hold hundreds of thousands of files. Excluding generated folders with .p4ignore helps, and so does scanning less often. Gameheim adds a smart scan that checks only modification time and size locally, and keeps the full scan for when you need certainty.
What is the difference between .p4ignore and a reconcile exclusion?
.p4ignore tells Perforce which files may never be added to the depot, and it applies to anyone who has P4IGNORE set. A reconcile exclusion in Gameheim only hides files from the Workspace Changes list, including files already in the depot, without changing what Perforce accepts. The two are complementary, not alternatives.
Does Gameheim reconcile my workspace automatically?
Only if you ask it to. Automatic smart and full reconciles are OFF until you set an interval in Reconcile settings, and every scan is a read-only preview. Opening files for edit, add or delete always happens when you click an action, never on its own. By default Gameheim only runs a smart scan the first time you open the workspace each day and the local changes check every 10 minutes; both can be changed.