A practical guide to working with Lore repositories in ugit — from putting an existing game project under version control, through day-to-day work, to a team collaborating on it. Lore is a centralized, Perforce-style VCS built for large game projects: a server is the source of truth, big binary assets are first-class, and files can be exclusively locked while you edit them.
ugit shows a Lore repository in its own Lore panel (a tab tinted violet). The panel is GUI-first; the one place you still touch the command line is running/standing up the Lore server, covered below.
Status: experimental. Everything here works against a local dev server. The auth/login flow is wired to Lore’s documented JWT/OIDC contract but not verified against a secured server (the dev server runs with auth disabled).
lore://host:port/name..lore/ directory).
It can be a sparse subset of a huge repo; assets are fetched lazily.The mental model is Perforce, not git: you’re always working against a central server, and for unmergeable binary assets you lock before you edit so two people can’t clobber each other.
ugit drives the lore CLI (and, for a local server, loreserver). Get them either way:
curl -fsSL https://raw.githubusercontent.com/EpicGames/lore/main/scripts/install.sh | bashirm https://raw.githubusercontent.com/EpicGames/lore/main/scripts/install.ps1 | iexThe installer downloads lore (and loreserver) and adds them to your PATH. Verify with
lore --version.
Where ugit looks for the binaries: the Lore Executable Path / Lore Server Path in
Settings first, then the LORE_BIN / LORE_SERVER_BIN environment variables, then ~/bin, then
PATH. Set the Settings path if your install lives somewhere non-standard.
You need a server before you can create or clone a repo. For a real team this is shared, durable, authenticated infrastructure; for trying things out you run a local one.
loreserver against that folder, shows a live health status,
and offers Stop. The repo URL is lore://127.0.0.1:41337/.LORE_DEMO=1 on Windows, --demo on macOS/Linux), or run loreserver directly.Either way the server listens on 41337 (QUIC + gRPC) and 41339 (HTTP). Check it any time:
curl -i http://127.0.0.1:41339/health_check # healthy → HTTP 200, empty body
A local server runs single-node with an ephemeral self-signed cert and auth disabled — fine
for localhost. ugit’s server keeps your data durable under the data folder’s store/, so repos
survive restarts.
For a team, the server is shared infrastructure (a durable store, real TLS cert, auth enabled).
Everyone points their clones at the same lore:// URL. Auth uses JWT/OIDC — authenticate the CLI
once with lore login (browser, or --token-type … --token …); ugit then reuses that identity
(there is no separate login form in the GUI yet).
Say you have D:\games\MyGame full of source and assets and no version control yet.
D:\games\MyGame.lore://127.0.0.1:41337/MyGame (the dialog shows the full lore://…/MyGame it will create).lore/ in your folder, then opens it as a violet
Lore tab. Your existing files show up as untracked.Now teammates can clone lore://<server>/MyGame and you’re all working against the same repo.
Large/binary assets (textures, geometry, etc.) are committed like anything else — Lore chunks them content-addressably. You don’t need LFS or special config.
Toolbar: Refresh · Sync · Push · Branch · and three view toggles — Changes, Files,
Graph (the active one is highlighted). On the right, the sync gauge shows
local rev ⇄ remote rev, colored green when in sync, amber when ahead/behind — your at-a-glance
“am I up to date with the server?” indicator.
.lore/view filter (see below).The working set as a sparse tree of the repo (like a Perforce depot/workspace tree):
A lane-based revision graph across branches, with merges shown, and HEAD / remote markers so you can see exactly what’s local-only (unpushed) versus on the server.
Open/copy paths, Repository Metadata…, Find Revision… (by number or metadata key/
key=value — jumps to the match), Repository Info…, Verify Repository (consistency check),
Run Garbage Collection, List Instances, Clean Working Directory, and Watch Events…
(subscribe to repository events for a bounded window — handy to see pushes/locks from others land in
real time).
A typical loop:
For larger work, create a branch, commit there, and Merge it back — resolving any text conflicts with the resolver (Part 7).
This is where Lore’s centralized, lock-oriented model matters. From Lore’s perspective:
The server is the single source of truth. Everyone clones the same lore:// repo and
reconciles through it — there is no peer-to-peer sharing. Your local commits aren’t visible to
anyone until you Push; you see others’ work when you Sync.
Lock unmergeable assets before editing. Two people can’t meaningfully merge a binary
file or a texture. The Lore workflow is exclusive locking: before editing such a file,
select it and click Lock. Everyone else sees 🔒 <your name> on that file in the Files
tree and Changes list, so they know not to touch it. Commit, push, then Unlock. (On the
auth-disabled dev server the owner shows as <unknown>; a real server shows real identities.)
Text can branch and merge. Source code and other text can be worked on in parallel branches and merged; conflicts are resolved per-hunk (Part 7).
Stay in sync. The sync gauge tells each person whether they’re behind the server. Sync often; push when you’ve committed something others need. If you try to push and you’re behind, sync first.
Sparse clones for big projects. Nobody needs the whole multi-hundred-GB project on disk. Use a sparse view so each person clones only their area (see Part 8). Lazy fetch pulls assets on demand.
Concrete example — an artist and a programmer share MyGame:
Content/Meshes/hero.glb, edits it in their DCC tool, commits, pushes,
unlocks. The programmer saw the lock the whole time and left it alone.Source/*.cpp on a feature/ai branch, commits, pushes the branch,
then merges to main — resolving any .cpp conflicts in the resolver.When you Merge a branch and text files conflict, the panel enters a merge state:
(Binary conflicts shouldn’t happen if you locked the asset — that’s the point of locking.)
A Lore working copy can hold just a subset of a huge repository — you don’t need the whole
multi-hundred-GB project on disk. Which files get materialized is controlled by a view filter:
a gitignore-style file stored at .lore/view.
The filter reads top-down:
** — exclude everything.!pattern — re-include matching paths.So you typically start by excluding everything, then add back the areas you want:
**
!Content/*.ts
!Content/*.material
That checks out only the .ts scripts and .material files under Content/. (Cloning the
56-file TPS_Demo with that filter materializes just the 10 matching files.) Anything excluded
is simply absent — and because Lore knows it’s outside your view, those files do not show
up as changes. A blank filter means a full checkout.
This is the normal way to get a partial checkout:
lore://).
lore://127.0.0.1:41337/TPS_Demo** / !pattern filter (leave it
blank for a full clone).From the CLI this is lore repository clone <url> <path> --view <file> (the file must be
BOM-free; ugit handles that for you).
Open the repo, go to the Changes view’s Sparse view section, and click Edit. Set the
same gitignore-style filter and save. Editing the view governs future syncs — it does not
retroactively re-materialize the current checkout. To pull in newly-included files (or drop
newly-excluded ones), Sync afterward. From the CLI that reconciliation is
lore sync --reset.
D on everythingThe Clone dialog also offers a Metadata only (bare) option. A bare clone fetches the latest revision tree but zero files — it’s for inspecting history or tooling, not day-to-day editing. Every path still appears in the Files tree (it’s read from the revision tree, not from disk), each dimmed and tagged ☁ not fetched; clicking one previews its content streamed from the store.
To turn a bare clone into a working one, give it a view (Changes → Sparse view → Edit —
empty for everything, or a **/! filter for a subset) and then Sync (CLI: lore sync
--reset) to materialize the files. For normal work, prefer a full or sparse clone over
bare.
In any sparse or bare clone, files that live in the repository but aren’t checked out on disk show up dimmed with a ☁ not fetched tag in the Files tree. You can still select one to preview it — ugit streams that single file’s content from the store at the current revision without materializing it.
To actually pull a file onto disk, right-click it in the Files tree → Check out (fetch to
disk) (or Check out folder… on a directory). ugit adds the path to your sparse view and
syncs, materializing just that file — it won’t drop anything already checked out (the underlying
sync --reset is additive). The row loses its ☁ not fetched tag once it’s on disk. You can
also widen the Sparse view filter directly and Sync to pull a whole set at once.
Some files can’t be merged — a binary data file, a texture, a packed mesh. Lore’s answer is the same as Perforce’s: lock the file before you edit it so nobody else can commit a conflicting change. Part 6 covers why this matters for a team; this section is the how in ugit.
Locking and unlocking. Select a file (in either the Changes list or the Files tree)
and use Lock / Unlock — both are on each row’s controls and on the right-click menu (you
can multi-select in the Files tree to lock several at once). Under the hood ugit runs
lore lock acquire <paths> / lore lock release <paths>.
Seeing who holds what. Locked files show a 🔒 with the owner’s name wherever they appear
— the Changes list, the Files tree, and a dedicated Locks section in the Changes sidebar that
lists every lock in the repo. The Locks section is your “what’s checked out right now” board;
release a lock from there too. (ugit reads this from lore lock query.)
The flow. Lock → edit → Stage → Commit → Push → Unlock. Hold the lock only while you’re actively changing the file, and release it as soon as you’ve pushed so teammates can take their turn.
On the auth-disabled dev server the owner shows as
<unknown>(there’s no identity to attribute the lock to). A real, authenticated server shows real names.
Big projects are rarely one repository. Lore composes them two ways — both surfaced in the Changes sidebar, each with a + Link / + Layer form and a list with Remove.
A link mounts a subtree of another Lore repo at a path inside this one, pinned to a branch or a specific revision. It’s part of your repository’s committed structure, so everyone who clones gets the same composition at the same pin — the Lore equivalent of a git submodule.
In the Links section click + Link and fill in:
vendor/SharedArt.lore://host:port/SharedArt./, the whole thing).ugit runs lore link add <mount> <url> <source> (pin defaults to the latest revision on the
linked repo’s main branch). Use a link when you want a stable, shared dependency — a common
asset library, an engine module — that updates only when you deliberately re-pin it: each link row
has a Re-pin… button (prompt for a branch or revision; blank = latest on the current branch).
A layer overlays another repository’s content on top of yours at a path, resolved locally rather than pinned into the committed tree. Layers can be matched to revisions by a metadata key, which makes them useful for variant/stream-style composition (overlay the matching slice of another repo).
In the Layers section click + Layer and fill in:
/).ugit runs lore layer add <path> <repository> <source> [--metadata <key>].
Rule of thumb: reach for a link when the dependency should be pinned and shared with everyone (committed composition); reach for a layer when you want a local overlay, optionally matched by metadata. Both are advanced features — most day-to-day work touches neither.
If you keep several worktrees of the same project on one machine, each clone normally stores its
own copy of the content under .lore/. A shared store is a single on-disk content store that
many worktrees draw from, so they don’t each duplicate it. Because Lore deduplicates fragments,
even similar files share the parts they have in common — not just byte-for-byte duplicates.
Manage stores from File → Lore Shared Stores…:
lore shared-store info.lore://host:port) and optionally a location, and
whether to make it the default for that server. Runs lore shared-store create.lore shared-store
set-use-automatically; when on, clones use the default store without any extra option.Then, when cloning a Lore repo (File → Clone…), tick Use shared store to clone against the
default store (clone --use-shared-store) instead of duplicating its content. Create the store
first if you haven’t — the option needs a default store to draw from.
When something broke but you don’t know which revision introduced it, bisect binary-searches
the history for you. Lore’s bisect is a step search: it syncs your working tree to the midpoint
between a known-good and known-bad revision, you test it and say which side it’s on, and it
narrows — log₂(n) steps instead of checking every revision.
In the Changes sidebar’s Bisect section:
Each step changes what’s checked out (it syncs to the revision under test), so the sync gauge and Files view follow along. Finish or Reset the bisect to return to normal work.
Lore has no native stash, so ugit emulates one locally: a stash captures the bytes of selected
(or all) changed files and rolls those files back, giving you a clean tree to do something else;
later you restore them. Stashes live under .lore/stashes/ — they’re local-only (never pushed)
and invisible to Lore’s own operations.
Because stashes are a ugit-side convenience (not a Lore feature), they don’t sync between machines — they’re for parking local work in progress.
.loreignore (keeping files out of the repo).loreignore is Lore’s outbound filter — gitignore-style patterns for files that should never
be committed/pushed (build output, local caches, secrets). It’s the complement of the sparse
view (Part 8), which is the inbound filter for what you check out.
In the Files tree or the Changes list, right-click a file or folder → Ignore:
Ignore file, Ignore *.ext, Ignore folder, or Ignore custom pattern…. ugit appends
the pattern to .loreignore (BOM-free). .loreignore itself is tracked, so committing it shares
the ignore rules with the team.
| Symptom | Fix |
|---|---|
| Panel shows a connection error | Server not running — start one via File → Local Lore Server (Part 2). |
| Tab opens the git view, not Lore | The folder has no .lore/ (wrong folder, or not created yet). |
| “lore not recognized” / spawn error | Set the Lore Executable Path in Settings, or set $env:LORE_BIN / put lore on PATH. |
Stage did nothing from the CLI |
The CLI resolves paths against the current directory; the GUI handles this for you. |
Lock owner shows <unknown> |
Expected on the auth-disabled dev server. |
Files view shows D on every file |
You did a bare clone (no files on disk). Set a view and Sync, or re-clone full/sparse — see Part 8. |
| Sparse clone fetched everything | The view filter was empty or didn’t start with **. Excludes-then-!re-includes; a blank box = full checkout. |
Not yet in the GUI (Lore capabilities ugit doesn’t surface):
lore login and ugit reuses it.--root-file, --dependency-tag) and other advanced clone modes
(--virtual, --prefetch) aren’t exposed.service — service start/stop exit 1 with no output on the dev setup; non-functional here.repository delete, file obliterate, file hash,
branch latest, and revision restore (which errors on a basic test) are left out.