ugit

Using Lore in ugit

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


1. How the pieces fit

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.


2. Installing Lore and running a server

Install the Lore tools

ugit drives the lore CLI (and, for a local server, loreserver). Get them either way:

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.

Run a local server

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.

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


3. Put an existing game project under Lore

Say you have D:\games\MyGame full of source and assets and no version control yet.

  1. Make sure the server is running (Part 2).
  2. In ugit: File → Init New Repository…, then pick the folder D:\games\MyGame.
  3. In the dialog, choose Lore (the type radio at the top):
    • Server URL: lore://127.0.0.1:41337/
    • Repository Name: MyGame (the dialog shows the full lore://…/MyGame it will create)
    • Click Create.
  4. ugit creates the repo on the server and a .lore/ in your folder, then opens it as a violet Lore tab. Your existing files show up as untracked.
  5. In the Changes view, click Stage all, type a message (“Import existing project”), and Commit. Then Push to publish it to the server.

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.


4. Tour of the Lore panel

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.

Changes view (the commit flow)

Files view (the repository tree) — the default

The working set as a sparse tree of the repo (like a Perforce depot/workspace tree):

Graph view

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.

Repository menu (the … by the repo name)

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


5. Working day to day

A typical loop:

  1. Sync to get the latest from the server (the gauge turns green / “in-sync”).
  2. Make changes. For binary assets you’ll edit, lock them first (see Part 6).
  3. In Changes, Stage the files and Commit with a message (this is local).
  4. Push to publish your revision to the server. The sync gauge returns to in-sync.

For larger work, create a branch, commit there, and Merge it back — resolving any text conflicts with the resolver (Part 7).


6. Multiple people on one project (the Lore way)

This is where Lore’s centralized, lock-oriented model matters. From Lore’s perspective:

Concrete example — an artist and a programmer share MyGame:


7. Resolving merge conflicts

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


8. Sparse clones & views (checking out part of a big repo)

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:

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.

Clone sparsely from the start

This is the normal way to get a partial checkout:

  1. File → Clone…
  2. Pick Lore (auto-selected once the URL starts with lore://).
    • Repository URL: lore://127.0.0.1:41337/TPS_Demo
    • Parent Folder / Name: where to put the local folder.
  3. In the Sparse view filter (optional) box, paste your ** / !pattern filter (leave it blank for a full clone).
  4. Clone. Only the matching files are fetched and written.

From the CLI this is lore repository clone <url> <path> --view <file> (the file must be BOM-free; ugit handles that for you).

Change the view later

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.

“Bare” clones, and why the Files view shows D on everything

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

Browsing and checking out un-fetched files

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.


9. Locks (Perforce-style exclusive checkout)

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:

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

Layers — local overlays

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.


11. Shared store (one content store for many worktrees)

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…:

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.


12. Finding when a change appeared (bisect)

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:

  1. Pick Good — the latest revision you know doesn’t have the problem.
  2. Pick Bad — the earliest revision you know does.
  3. Click Start bisect. ugit syncs the working tree to the midpoint and asks “Does this revision contain the change?”
  4. Test the working tree, then click Contains it (bad) or Clean (good). ugit re-bisects the narrower range and repeats.
  5. When the range collapses to one revision, the panel reports the first revision with the change. Click Reset (or Done) to stop.

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.


13. Stash (set work aside)

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.


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


15. Troubleshooting & known limits

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):