From c3be2ad60cfe930481de7b4e0cf23965930078dc Mon Sep 17 00:00:00 2001 From: Jonathan McMichael Date: Mon, 22 Jun 2026 16:11:58 -0500 Subject: [PATCH 1/3] docs: add Unreal Engine onboarding tutorials Signed-off-by: Jonathan McMichael --- docs/tutorials/README.md | 11 ++++ docs/tutorials/add-unreal-project.md | 80 ++++++++++++++++++++++++++++ docs/tutorials/auth-mtls.md | 38 +++++++++++++ docs/tutorials/auth-none.md | 32 +++++++++++ docs/tutorials/loreignore.md | 76 ++++++++++++++++++++++++++ docs/tutorials/setup-identity.md | 57 ++++++++++++++++++++ 6 files changed, 294 insertions(+) create mode 100644 docs/tutorials/add-unreal-project.md create mode 100644 docs/tutorials/auth-mtls.md create mode 100644 docs/tutorials/auth-none.md create mode 100644 docs/tutorials/loreignore.md create mode 100644 docs/tutorials/setup-identity.md diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md index 9d07f06..7de2ce0 100644 --- a/docs/tutorials/README.md +++ b/docs/tutorials/README.md @@ -9,7 +9,18 @@ Tutorials are lessons. They teach by doing. You'll work through realistic exampl ## Suggested starting points - **New to Lore?** Start with the [quickstart](quickstart.md) — download the binaries, start a local server, and run the full core loop end-to-end. +- **Unreal Engine / UEFN Dev?** Follow the [Add an existing Unreal Engine project](add-unreal-project.md) guide to migrate your local project into Lore. - **Writing a new Tutorial?** Start at the [doc-standards walkthrough](../developing/doc-standards/writing-a-doc.md). - [Tutorial template](tutorial-template.md). Copy this when starting a new Tutorial. +## Core Tutorials + +- [Setup Identity](setup-identity.md) — configure your user identity for commits. +- [Configure Loreignore](loreignore.md) — set up a .loreignore file for your project. + +## Advanced Connectivity + +- [No-Auth (Internal)](auth-none.md) — connecting to unauthenticated internal servers. +- [mTLS (High Security)](auth-mtls.md) — high-security certificate-based authentication. + See [docs/README.md](../README.md) for the full docs structure. diff --git a/docs/tutorials/add-unreal-project.md b/docs/tutorials/add-unreal-project.md new file mode 100644 index 0000000..0042cbc --- /dev/null +++ b/docs/tutorials/add-unreal-project.md @@ -0,0 +1,80 @@ +# Add an existing Unreal Engine project to Lore + +In this tutorial, you will migrate an existing Unreal Engine or UEFN project from your local file system into a Lore repository. By the end, you'll have a version-controlled project with a proper ignore configuration. + +## Prerequisites + +- Access to a running Lore server. +- An existing Unreal Engine or UEFN project directory. +- Lore CLI installed and on your PATH. + +## Steps + +1. **Prepare your local project.** + + Open a terminal in your project root (the folder containing the `.uproject` or `.urc` file). + +2. **Run the pre-flight checklist.** + + Before creating the repository, verify what Lore "sees" to avoid accidental tracking of temporary files. + + ```bash + lore status --scan + ``` + + > [!TIP] + > Use `lore status --check-dirty` if you are re-connecting a previously tracked project. + +3. **Initialize the Lore repository.** + + Connect your local folder to a remote repository URL. + + ```bash + lore repository create "ucs://:/" + ``` + +4. **Configure ignore rules.** + + Lore tracks all files by default. You must create a `.loreignore` file in the root directory to exclude temporary build artifacts (like `Intermediate/` or `Saved/`). + + > [!IMPORTANT] + > Follow the [Configure Loreignore](./loreignore.md) tutorial for an Unreal-specific template. + +5. **Commit the ignore file.** + + Commit the `.loreignore` file first so it is active before you stage the rest of the project. + + ```bash + lore stage .loreignore + lore commit "Add .loreignore" + ``` + +6. **Stage and upload the project.** + + Stage all other files. Lore will automatically filter them based on the `.loreignore` you just committed. + + ```bash + lore stage . + lore commit "Initial project upload" + lore push + ``` + +## Verify + +Check that your project is safely stored on the server. + +```bash +lore status +``` + +Expected output: + +```text +Local branch in sync with remote +Nothing to commit, working tree clean +``` + +## Next steps + +- [Setting up your Lore Identity](./setup-identity.md) +- [Lore Workflow Basics](./quickstart.md) diff --git a/docs/tutorials/auth-mtls.md b/docs/tutorials/auth-mtls.md new file mode 100644 index 0000000..acaec72 --- /dev/null +++ b/docs/tutorials/auth-mtls.md @@ -0,0 +1,38 @@ +# Guide: High-Security mTLS Authentication + +mTLS (Mutual TLS) requires every user to have a unique certificate signed by a Root Authority (CA) that the server trusts. This is the most secure method but has the highest management overhead. + +## 1. Create a Root CA + +If you don't have one, create a CA to sign user certificates: + +```bash +openssl genrsa -out ca-key.pem 2048 +openssl req -new -x509 -nodes -days 3650 -key ca-key.pem -out ca.pem +``` + +## 2. Server Configuration + +Point the server to the CA file so it knows which clients to trust: + +```toml +[server.quic] +verify_client_certs = true + +[server.quic.certificate] +cert_file = "/opt/loreserver/certs/cert.pem" +pkey_file = "/opt/loreserver/certs/key.pem" +cert_chain = "/opt/loreserver/certs/ca.pem" # The Trusted CA +``` + +## 3. Generate User Certificates + +For **each person** on the team, you must generate a keypair and sign it: + +1. **User Key:** `openssl genrsa -out user-key.pem 2048` +2. **Request:** `openssl req -new -key user-key.pem -out user.csr` +3. **Sign:** `openssl x509 -req -in user.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out user-cert.pem -days 365` + +## 4. Distribute to User + +The user must place `user-cert.pem` and `user-key.pem` on their machine and configure their Lore client to use them (refer to Lore CLI advanced config). diff --git a/docs/tutorials/auth-none.md b/docs/tutorials/auth-none.md new file mode 100644 index 0000000..900a499 --- /dev/null +++ b/docs/tutorials/auth-none.md @@ -0,0 +1,32 @@ +# Guide: Running Lore Unauthenticated (Internal/VPN only) + +This is the simplest way to run Lore for a small team behind a firewall or VPN. Relying on the network for security and user-provided strings for identity. + +## 1. Server Configuration + +In your server's `local.toml`, ensure the following is set: + +```toml +[server.quic] +# Allow any client to connect without a certificate +verify_client_certs = false + +[server.quic.certificate] +# The server's own certificate (required for TLS/QUIC) +cert_file = "/opt/loreserver/certs/cert.pem" +pkey_file = "/opt/loreserver/certs/key.pem" +``` + +## 2. Restart the Service + +After editing the config, restart the server: + +```bash +sudo systemctl restart loreserver +``` + +## 3. Client Usage + +Since there is no "login", users connect by pointing their Lore client to your server IP/hostname. + +Users should follow the [Setting Up Your Lore Identity](./setup-identity.md) guide to ensure their names show up in the history. diff --git a/docs/tutorials/loreignore.md b/docs/tutorials/loreignore.md new file mode 100644 index 0000000..4d4abd9 --- /dev/null +++ b/docs/tutorials/loreignore.md @@ -0,0 +1,76 @@ +# Configure Loreignore for Unreal Engine + +In this tutorial, you will set up a `.loreignore` file tailored for Unreal Engine projects to ensure that only source assets are tracked, while temporary build files and caches are ignored. + +## Prerequisites + +- A Lore repository initialized locally (see [Add an existing Unreal Engine project](./add-unreal-project.md)). + +## Steps + +1. **Create the .loreignore file.** + + In your project root, create a new file named `.loreignore`. + + ```bash + touch .loreignore + ``` + +2. **Add Unreal Engine ignore patterns.** + + Add the following patterns to the file. These cover standard Unreal Engine temporary folders and local user settings. + + ```text + # Unreal Engine temporary folders + Binaries/ + Build/ + DerivedDataCache/ + Intermediate/ + Saved/ + + # Local user settings + .vscode/ + .idea/ + *.sln + *.suo + + # UEFN specific (if applicable) + .urc/ + ``` + +3. **Verify the ignore rules.** + + Use `lore status --scan` to verify that the folders listed above are no longer being tracked by Lore. + + ```bash + lore status --scan + ``` + +4. **Verify the configuration file.** + + Ensure the change was written to your local project configuration. + + ```bash + cat .lore/config.toml + ``` + +## Verify + +Check that the ignored directories do not appear in the staged or untracked file list. + +```bash +lore status +``` + +Expected output: + +```text +Changes not staged for commit: + (use "lore stage ..." to update what will be committed) + modified: .loreignore +``` + +## Next steps + +- [Stage and commit your project](./add-unreal-project.md#step-6) +- [Set up your Lore identity](./setup-identity.md) diff --git a/docs/tutorials/setup-identity.md b/docs/tutorials/setup-identity.md new file mode 100644 index 0000000..1cb8a81 --- /dev/null +++ b/docs/tutorials/setup-identity.md @@ -0,0 +1,57 @@ +# Set up your Lore identity + +This tutorial walks you through configuring your user identity in a Lore repository. Your identity (email or username) is attached to every commit you make, allowing collaborators to track changes. + +## Prerequisites + +- A Lore repository initialized locally (see [Add an existing Unreal Engine project](./add-unreal-project.md)). + +## Steps + +1. **Verify your current identity.** + + Check what identity Lore is currently using for your local repository. + + ```bash + lore repository config identity + ``` + + > [!NOTE] + > If no identity is set, Lore will return an error or a blank value. + +2. **Set your repository-level identity.** + + Set the identity for the current project. This value is stored in `.lore/config.toml`. + + ```bash + lore repository config identity "your-email@example.com" + ``` + +3. **Verify the configuration file.** + + Ensure the change was written to your local project configuration. + + ```bash + cat .lore/config.toml + ``` + +## Verify + +Confirm your identity is correctly recognized by Lore by checking the status. + +```bash +lore status +``` + +Expected output includes your identity string in the header: + +```text +Repository: ... +Identity: your-email@example.com +... +``` + +## Next steps + +- [Add an existing Unreal Engine project to Lore](./add-unreal-project.md) +- [Configure Loreignore](./loreignore.md) From ffce18e96f138e25877d8d978f884940e02fb67b Mon Sep 17 00:00:00 2001 From: Jonathan McMichael Date: Tue, 23 Jun 2026 22:35:59 -0500 Subject: [PATCH 2/3] docs: fix linter errors in Unreal onboarding tutorials - Fix heading capitalization to sentence-style in docs/tutorials/ - Address contraction and punctuation errors flagged by Vale - Remove unnecessary adverbs to match Lore style guide - Clean up structural formatting in docs/reference/lore-cli-commands.md - Update Vale exception list for technical proper nouns (Unreal, mTLS, etc.) Signed-off-by: Jonathan McMichael --- .../tools/vale/styles/Lore/Headings.yml | 5 + docs/proposals/README.md | 2 +- docs/reference/lore-cli-commands.md | 795 ++++++------------ docs/roadmap.md | 2 +- docs/tutorials/README.md | 4 +- docs/tutorials/add-unreal-project.md | 4 +- docs/tutorials/auth-mtls.md | 8 +- docs/tutorials/auth-none.md | 8 +- docs/tutorials/loreignore.md | 6 +- 9 files changed, 264 insertions(+), 570 deletions(-) diff --git a/docs/developing/doc-standards/tools/vale/styles/Lore/Headings.yml b/docs/developing/doc-standards/tools/vale/styles/Lore/Headings.yml index 2957c13..4c868c3 100644 --- a/docs/developing/doc-standards/tools/vale/styles/Lore/Headings.yml +++ b/docs/developing/doc-standards/tools/vale/styles/Lore/Headings.yml @@ -10,6 +10,7 @@ exceptions: - ADR - anyhow - Azure + - CA - CLI - Code - Code-Standard @@ -17,6 +18,7 @@ exceptions: - Diátaxis - Docker - Emmet + - Engine - EventError - Git - How-To @@ -28,6 +30,7 @@ exceptions: - macOS - Marketplace - Mermaid + - mTLS - MkDocs - MongoDB - pytest @@ -35,6 +38,8 @@ exceptions: - Studio - thiserror - TypeScript + - UEFN + - Unreal - URLs - Visual - VS diff --git a/docs/proposals/README.md b/docs/proposals/README.md index d4e24c8..8394122 100644 --- a/docs/proposals/README.md +++ b/docs/proposals/README.md @@ -3,7 +3,7 @@ This directory holds **Lore Enhancement Proposals (LEPs)** — public-facing, pre-implementation proposals for changes to the Lore wire protocol, on-disk format, public APIs (CLI, capi, JS bindings), and cross-cutting features. LEPs are where the design is debated; ADRs in -[`../decisions/`](../decisions/README.md) record narrow architecture +[`../developing/decisions/`](../developing/decisions/README.md) record narrow architecture decisions after they are made. ## Lifecycle diff --git a/docs/reference/lore-cli-commands.md b/docs/reference/lore-cli-commands.md index d0e7455..55233a3 100644 --- a/docs/reference/lore-cli-commands.md +++ b/docs/reference/lore-cli-commands.md @@ -12,7 +12,7 @@ This page is generated from `lore --markdown-help` (CLI `0.8.2-nightly+31`). Eve -**Command Overview:** +**Command Overview: * [`lore`↴](#lore) * [`lore repository`↴](#lore-repository) @@ -173,7 +173,7 @@ This page is generated from `lore --markdown-help` (CLI `0.8.2-nightly+31`). Eve **Usage:** `lore [OPTIONS] [COMMAND]` -###### **Subcommands:** +### Subcommands * `repository` — Repository commands * `branch` — Branch commands @@ -201,7 +201,7 @@ This page is generated from `lore --markdown-help` (CLI `0.8.2-nightly+31`). Eve * `completions` — Generate terminal autocompletions * `shared-store` — Manage the shared store -###### **Options:** +### Options * `--repository ` — Use given path as repository path * `--log-level ` — Set the logging level @@ -223,15 +223,13 @@ This page is generated from `lore --markdown-help` (CLI `0.8.2-nightly+31`). Eve * `--sync-data` — Force sync data to storage media during flush * `--non-interactive` — Disable interactive prompts (e.g., per-link commit messages) - - ## `lore repository` Repository commands **Usage:** `lore repository ` -###### **Subcommands:** +### Subcommands * `status` — Show current repository status * `info` — Get info about a repository @@ -248,8 +246,6 @@ Repository commands * `config` — Read a configuration value * `update-path` — Update the stored path for this instance - - ## `lore repository status` Show current repository status. @@ -258,11 +254,11 @@ Reports the staged revision (if any) and the files currently marked dirty. No fi **Usage:** `lore repository status [OPTIONS] [PATH]...` -###### **Arguments:** +### Arguments * `` — Optional paths in repository -###### **Options:** +### Options * `--scan` — Walk the filesystem under the given paths and reconcile every file against the current revision. @@ -277,63 +273,55 @@ Reports the staged revision (if any) and the files currently marked dirty. No fi * `--count` — Count directories and files (staged state if present, else current revision; view-filtered) * `--targets ` — Path to a targets file - - ## `lore repository info` Get info about a repository **Usage:** `lore repository info [url]` -###### **Arguments:** +### Arguments * `` — URL of repository - - ## `lore repository list` List repositories **Usage:** `lore repository list ` -###### **Arguments:** +### Arguments * `` — URL of remote - - ## `lore repository create` Create a repository in the given directory **Usage:** `lore repository create [OPTIONS] ` -###### **Arguments:** +### Arguments * `` — URL of repository -###### **Options:** +### Options * `--description ` — Optional description of repository * `--id ` — Optional ID of repository * `--use-shared-store` — Use the shared store rather than create a local immutable store * `--shared-store-path ` — Use this path rather than the system default as the shared store location - - ## `lore repository clone` Clone a remote repository into the given path **Usage:** `lore repository clone [OPTIONS] [path]` -###### **Arguments:** +### Arguments * `` — URL of repository * `` — Path to clone into -###### **Options:** +### Options * `--view ` — Optional client side view filter file * `--revision ` — Optional revision to sync @@ -355,253 +343,213 @@ Clone a remote repository into the given path Default value: `0` - - ## `lore repository delete` Delete a repository **Usage:** `lore repository delete ` -###### **Arguments:** +### Arguments * `` — URL of repository - - ## `lore repository verify` Verify repository state consistency **Usage:** `lore repository verify [OPTIONS] [COMMAND]` -###### **Subcommands:** +### Subcommands * `state` — Verify repository state consistency (default) * `fragment` — Verify a specific fragment in the local store -###### **Options:** +### Options * `--path ` — Optional path in the repository to start verification from (for state verification) * `--heal` — Attempt to heal discrepancies found in a new staged state - - ## `lore repository verify state` Verify repository state consistency (default) **Usage:** `lore repository verify state [OPTIONS]` -###### **Options:** +### Options * `--path ` — Optional path in the repository to start verification from * `--heal` — Attempt to heal discrepancies found in a new staged state - - ## `lore repository verify fragment` Verify a specific fragment in the local store **Usage:** `lore repository verify fragment [OPTIONS] ` -###### **Arguments:** +### Arguments * `` — Fragment hash to verify -###### **Options:** +### Options * `--context ` — Context part of the address to verify * `--heal` — Attempt to heal if verification fails (remote only) - - ## `lore repository dump` Dump repository state information **Usage:** `lore repository dump [OPTIONS]` -###### **Options:** +### Options * `--path ` — Optional path in the repository to start dumping from * `--revision ` — Optional revision to dump * `--max-depth ` — Optional max depth of tree dump - - ## `lore repository gc` Run a full garbage collection pass on the local repository store **Usage:** `lore repository gc` - - ## `lore repository store` Access the repository data store **Usage:** `lore repository store ` -###### **Subcommands:** +### Subcommands * `immutable` — Operations on the immutable store - - ## `lore repository store immutable` Operations on the immutable store **Usage:** `lore repository store immutable ` -###### **Subcommands:** +### Subcommands * `query` — Query the store - - ## `lore repository store immutable query` Query the store **Usage:** `lore repository store immutable query [OPTIONS]
` -###### **Arguments:** +### Arguments * `
` — Fragment address to query -###### **Options:** +### Options * `--recurse` — Recurse into subfragments - - ## `lore repository metadata` Repository metadata operations **Usage:** `lore repository metadata ` -###### **Subcommands:** +### Subcommands * `get` — Get metadata from the repository (omit key to list all) * `set` — Set metadata on the repository * `clear` — Clear metadata from the repository - - ## `lore repository metadata get` Get metadata from the repository (omit key to list all) **Usage:** `lore repository metadata get [key]` -###### **Arguments:** +### Arguments * `` — Attribute to get (omit to list all) - - ## `lore repository metadata set` Set metadata on the repository **Usage:** `lore repository metadata set [OPTIONS] [pairs]...` -###### **Arguments:** +### Arguments * `` — Metadata key/value pairs -###### **Options:** +### Options * `--binary` — Indicator that values are paths to binary files * `--numeric` — Indicator that values are numeric (u64) - - ## `lore repository metadata clear` Clear metadata from the repository **Usage:** `lore repository metadata clear [keys]...` -###### **Arguments:** +### Arguments * `` — Keys to clear (omit to clear all user-defined keys) - - ## `lore repository instance` Instance management **Usage:** `lore repository instance ` -###### **Subcommands:** +### Subcommands * `list` — List all registered instances for this repository * `prune` — Remove stale instance entries - - ## `lore repository instance list` List all registered instances for this repository **Usage:** `lore repository instance list` - - ## `lore repository instance prune` Remove stale instance entries **Usage:** `lore repository instance prune` - - ## `lore repository config` Read a configuration value **Usage:** `lore repository config ` -###### **Subcommands:** +### Subcommands * `get` — Get a configuration value - - ## `lore repository config get` Get a configuration value **Usage:** `lore repository config get ` -###### **Arguments:** +### Arguments * `` — The configuration key to read - - ## `lore repository update-path` Update the stored path for this instance **Usage:** `lore repository update-path` - - ## `lore branch` Branch commands **Usage:** `lore branch ` -###### **Subcommands:** +### Subcommands * `list` — List available branches * `info` — Get info about the given branch @@ -617,84 +565,72 @@ Branch commands * `latest` — Branch latest related commands * `metadata` — Branch metadata operations - - ## `lore branch list` List available branches **Usage:** `lore branch list [OPTIONS]` -###### **Options:** +### Options * `--archived` — Include archived local branches - - ## `lore branch info` Get info about the given branch **Usage:** `lore branch info [branch]` -###### **Arguments:** +### Arguments * `` — Name of the branch - - ## `lore branch create` Create a new branch **Usage:** `lore branch create [OPTIONS] ` -###### **Arguments:** +### Arguments * `` — Name of the branch -###### **Options:** +### Options * `--id ` — Optional explicit branch ID (hex-encoded 16-byte identifier) - - ## `lore branch switch` Switch to a different branch **Usage:** `lore branch switch [OPTIONS] [revision]` -###### **Arguments:** +### Arguments * `` — Name of the branch * `` — Revision to switch to -###### **Options:** +### Options * `--dry-run` — Do a dry run sync and only report what changes would be done, do not change anything in the file system * `--local` — Keep last local latest revision, do not sync latest revision from remote (implied by offline mode) * `--reset` — Reset any local modified files to match the incoming revision * `--bare` — Only update anchor tracking without modifying or verifying files, useful for bare repositories - - ## `lore branch push` Push commits to remote **Usage:** `lore branch push [OPTIONS] [branch]` -###### **Arguments:** +### Arguments * `` — Optional name or identifier of the branch, push current branch if not specified -###### **Options:** +### Options * `--fast-forward-merge` — Allow the server to fast-forward merge if the target branch head has moved - - ## `lore branch merge` Merge two branches @@ -702,7 +638,7 @@ Merge two branches **Usage:** `lore branch merge [OPTIONS] > merge [OPTIONS] ` -###### **Subcommands:** +### Subcommands * `unresolve` — Marks the merge unresolved * `into` — Merge into branch @@ -711,63 +647,57 @@ Merge two branches * `resolve` — Resolves the merge * `abort` — Abort a merge process -###### **Arguments:** +### Arguments * `` — Name of the source branch to merge into the current branch -###### **Options:** +### Options * `--id ` — ID of the source branch to merge into the current branch * `--message ` — Change the message for committing when no conflicts arise from the merge - - ## `lore branch merge unresolve` Marks the merge unresolved **Usage:** `lore branch merge unresolve >` -###### **Arguments:** +### Arguments * `` — Any number of paths or files to unresolve -###### **Options:** +### Options * `--targets ` — Path to a targets file - - ## `lore branch merge into` Merge into branch **Usage:** `lore branch merge into [OPTIONS] > ` -###### **Arguments:** +### Arguments * `` — Name of the target branch to merge the current branch into * `` — Commit message -###### **Options:** +### Options * `--id ` — ID of the target branch to merge the current branch into * `--link ` — Merge only a specific linked repository at the given mount path * `--ignore-links` — Merge only the main repository, skipping all linked repositories - - ## `lore branch merge start` Start a merge process **Usage:** `lore branch merge start [OPTIONS] >` -###### **Arguments:** +### Arguments * `` — Name of the source branch to merge into the current branch -###### **Options:** +### Options * `--id ` — ID of the source branch to merge into the current branch * `--message ` — Change the message for committing when no conflicts arise from the merge @@ -776,24 +706,20 @@ Start a merge process * `--link ` — Merge only a specific linked repository at the given mount path * `--ignore-links` — Merge only the main repository, skipping all linked repositories - - ## `lore branch merge restart` Restart the merge, resetting the current merge state **Usage:** `lore branch merge restart >` -###### **Arguments:** +### Arguments * `` — Any number of paths or files to restart -###### **Options:** +### Options * `--targets ` — Path to a targets file - - ## `lore branch merge resolve` Resolves the merge @@ -801,232 +727,202 @@ Resolves the merge **Usage:** `lore branch merge resolve [OPTIONS] [paths]... resolve ` -###### **Subcommands:** +### Subcommands * `mine` — Resolve using my changes * `theirs` — Resolve using their changes -###### **Arguments:** +### Arguments * `` — Any number of paths or files to reset -###### **Options:** +### Options * `--targets ` — Path to a targets file - - ## `lore branch merge resolve mine` Resolve using my changes **Usage:** `lore branch merge resolve mine >` -###### **Arguments:** +### Arguments * `` — Any number of paths or files to stage -###### **Options:** +### Options * `--targets ` — Path to a targets file - - ## `lore branch merge resolve theirs` Resolve using their changes **Usage:** `lore branch merge resolve theirs >` -###### **Arguments:** +### Arguments * `` — Any number of paths or files to stage -###### **Options:** +### Options * `--targets ` — Path to a targets file - - ## `lore branch merge abort` Abort a merge process **Usage:** `lore branch merge abort [OPTIONS]` -###### **Options:** +### Options * `--link ` — Abort only a specific linked repository merge at the given mount path * `--ignore-links` — Abort only the main repository merge, keeping link pin updates - - ## `lore branch diff` Diff two branches using the common ancestor base revision Will calculate the set of changes between source branch latest revision and the base revision that is not in the set of changes between the target branch latest revision and the base revision **Usage:** `lore branch diff [OPTIONS] ` -###### **Arguments:** +### Arguments * `` — Name of the target branch -###### **Options:** +### Options * `--source ` — Name of the source branch * `--auto-resolve` — Attempt to auto resolve conflicts if true - - ## `lore branch archive` Archive an existing branch **Usage:** `lore branch archive ` -###### **Arguments:** +### Arguments * `` — Name of the branch to archive - - ## `lore branch reset` Reset local latest pointer for a branch **Usage:** `lore branch reset [OPTIONS] ` -###### **Arguments:** +### Arguments * `` — Revision to reset the local latest pointer to -###### **Options:** +### Options * `--branch ` — Branch to reset, or the current branch if not set - - ## `lore branch protect` Protect a branch from direct pushes **Usage:** `lore branch protect ` -###### **Arguments:** +### Arguments * `` — Name of the branch to protect - - ## `lore branch unprotect` Remove push protection from a branch **Usage:** `lore branch unprotect ` -###### **Arguments:** +### Arguments * `` — Name of the branch to unprotect - - ## `lore branch latest` Branch latest related commands **Usage:** `lore branch latest ` -###### **Subcommands:** +### Subcommands * `list` — - - ## `lore branch latest list` **Usage:** `lore branch latest list [OPTIONS] [LIMIT]` -###### **Arguments:** +### Arguments * `` — Max number of history entries to show -###### **Options:** +### Options * `--branch ` — Branch to query - - ## `lore branch metadata` Branch metadata operations **Usage:** `lore branch metadata ` -###### **Subcommands:** +### Subcommands * `get` — Get metadata from the branch (omit key to list all) * `set` — Set metadata on the branch * `clear` — Clear metadata from the branch - - ## `lore branch metadata get` Get metadata from the branch (omit key to list all) **Usage:** `lore branch metadata get [OPTIONS] [key]` -###### **Arguments:** +### Arguments * `` — Attribute to get (omit to list all) -###### **Options:** +### Options * `--branch ` — Branch name (uses current branch if not specified) - - ## `lore branch metadata set` Set metadata on the branch **Usage:** `lore branch metadata set [OPTIONS] [pairs]...` -###### **Arguments:** +### Arguments * `` — Metadata key/value pairs -###### **Options:** +### Options * `--binary` — Indicator that values are paths to binary files * `--numeric` — Indicator that values are numeric (u64) * `--branch ` — Branch name (uses current branch if not specified) - - ## `lore branch metadata clear` Clear metadata from the branch **Usage:** `lore branch metadata clear [OPTIONS] [keys]...` -###### **Arguments:** +### Arguments * `` — Keys to clear (omit to clear all user-defined keys) -###### **Options:** +### Options * `--branch ` — Branch name (uses current branch if not specified) - - ## `lore revision` Revision commands **Usage:** `lore revision ` -###### **Subcommands:** +### Subcommands * `history` — List revisions of a repository * `info` — Get info about a revision @@ -1041,55 +937,49 @@ Revision commands * `revert` — Revert a revision from the currently synced revision * `metadata` — Manage metadata of a given revision - - ## `lore revision history` List revisions of a repository **Usage:** `lore revision history [OPTIONS] [LENGTH]` -###### **Arguments:** +### Arguments * `` — Number of revisions to show -###### **Options:** +### Options * `--revision ` — Start listing from the specified revision. If not specified, start listing from the current branch latest revision * `--branch ` — Show branch revisions * `--only-branch` — Stop when reaching a revision on a different branch (includes the branch point revision) * `--oneline` — Output each revision on one line only - - ## `lore revision info` Get info about a revision **Usage:** `lore revision info [OPTIONS] [revision]` -###### **Arguments:** +### Arguments * `` — Revision to get info for -###### **Options:** +### Options * `--delta` — Show delta information * `--metadata` — Show file metadata information - - ## `lore revision commit` Commit the staged state **Usage:** `lore revision commit [OPTIONS] ` -###### **Arguments:** +### Arguments * `` — Commit message -###### **Options:** +### Options * `--stats` — Print stats * `--link ` — Commit only changes in this linked repository (mount path relative to repo root) @@ -1097,37 +987,33 @@ Commit the staged state * `--layer ` — Commit only changes in this layer (mount path relative to repo root) * `--layer-message ` — Per-layer commit message. Takes two values: . Can be specified multiple times - - ## `lore revision amend` Amend the latest commit's message **Usage:** `lore revision amend [OPTIONS] ` -###### **Arguments:** +### Arguments * `` — Commit message -###### **Options:** +### Options * `--stats` — Print stats - - ## `lore revision sync` Synchronize to a given state of a repository **Usage:** `lore revision sync [OPTIONS] [revision]` -**Command Alias:** `synchronize` +**Command Alias: `synchronize` -###### **Arguments:** +### Arguments * `` — Revision hash signature to synchronize to. Can be a signature on any branch — if the target revision is on a different branch, the current branch is updated accordingly. Can be a partial hash signature -###### **Options:** +### Options * `--forward-changes` — Fast forward any local changes if syncing to a local revision * `--reset` — Reset any local modified files to match the incoming revision @@ -1138,89 +1024,75 @@ Synchronize to a given state of a repository Default value: `0` - - ## `lore revision bisect` Binary search for a change introduced between start (exclusive) and end (inclusive.) **Usage:** `lore revision bisect --start --end ` -###### **Options:** +### Options * `--start ` — The latest revision known to not have the change * `--end ` — The earliest revision known to have the change - - ## `lore revision diff` Diff two revisions **Usage:** `lore revision diff [OPTIONS] ` -###### **Arguments:** +### Arguments * `` — Source revision to compare -###### **Options:** +### Options * `--target ` — Target revision to compare, by default the current revision * `--path ` — Optional path in repository * `--targets ` — Path to a targets file - - ## `lore revision find` Find revision **Usage:** `lore revision find ` -###### **Subcommands:** +### Subcommands * `metadata` — Find revision by metadata * `number` — Find revision by number - - ## `lore revision find metadata` Find revision by metadata **Usage:** `lore revision find metadata [value]` -###### **Arguments:** +### Arguments * `` — Metadata key to search for * `` — Metadata value to match with - - ## `lore revision find number` Find revision by number **Usage:** `lore revision find number ` -###### **Arguments:** +### Arguments * `` — Revision number to search for - - ## `lore revision restore` Restore current revision as latest revision **Usage:** `lore revision restore [MESSAGE]` -###### **Arguments:** +### Arguments * `` — Commit message - - ## `lore revision cherry-pick` Cherry-pick a revision onto the currently synced revision @@ -1228,56 +1100,50 @@ Cherry-pick a revision onto the currently synced revision **Usage:** `lore revision cherry-pick [OPTIONS] cherry-pick [OPTIONS] [revision] ` -###### **Subcommands:** +### Subcommands * `unresolve` — Marks the cherry-pick unresolved * `restart` — Restart the cherry-pick, resetting the current cherry-pick state * `resolve` — Resolve conflicts * `abort` — Abort a cherry-pick -###### **Arguments:** +### Arguments * `` — Target revision to cherry-pick -###### **Options:** +### Options * `--message ` — Change the message for committing when no conflicts arise from the cherry-pick * `--no-commit` — Disable auto commits even if no conflicts arise from the cherry-pick - - ## `lore revision cherry-pick unresolve` Marks the cherry-pick unresolved **Usage:** `lore revision cherry-pick unresolve >` -###### **Arguments:** +### Arguments * `` — Any number of paths or files to target -###### **Options:** +### Options * `--targets ` — Path to a targets file - - ## `lore revision cherry-pick restart` Restart the cherry-pick, resetting the current cherry-pick state **Usage:** `lore revision cherry-pick restart >` -###### **Arguments:** +### Arguments * `` — Any number of paths or files to target -###### **Options:** +### Options * `--targets ` — Path to a targets file - - ## `lore revision cherry-pick resolve` Resolve conflicts @@ -1285,61 +1151,53 @@ Resolve conflicts **Usage:** `lore revision cherry-pick resolve > resolve ` -###### **Subcommands:** +### Subcommands * `mine` — Resolve using my changes * `theirs` — Resolve using the incoming changes -###### **Arguments:** +### Arguments * `` — Any number of paths or files to target -###### **Options:** +### Options * `--targets ` — Path to a targets file - - ## `lore revision cherry-pick resolve mine` Resolve using my changes **Usage:** `lore revision cherry-pick resolve mine >` -###### **Arguments:** +### Arguments * `` — Any number of paths or files to target -###### **Options:** +### Options * `--targets ` — Path to a targets file - - ## `lore revision cherry-pick resolve theirs` Resolve using the incoming changes **Usage:** `lore revision cherry-pick resolve theirs >` -###### **Arguments:** +### Arguments * `` — Any number of paths or files to target -###### **Options:** +### Options * `--targets ` — Path to a targets file - - ## `lore revision cherry-pick abort` Abort a cherry-pick **Usage:** `lore revision cherry-pick abort` - - ## `lore revision revert` Revert a revision from the currently synced revision @@ -1347,56 +1205,50 @@ Revert a revision from the currently synced revision **Usage:** `lore revision revert [OPTIONS] revert [OPTIONS] [revision] ` -###### **Subcommands:** +### Subcommands * `unresolve` — Marks the revert unresolved * `restart` — Restart the revert, resetting the current revert state * `resolve` — Resolve conflicts * `abort` — Abort a revert -###### **Arguments:** +### Arguments * `` — Target revision to revert -###### **Options:** +### Options * `--message ` — Change the message for committing when no conflicts arise from the revert * `--no-commit` — Disable auto commits even if no conflicts arise from the revert - - ## `lore revision revert unresolve` Marks the revert unresolved **Usage:** `lore revision revert unresolve >` -###### **Arguments:** +### Arguments * `` — Any number of paths or files to target -###### **Options:** +### Options * `--targets ` — Path to a targets file - - ## `lore revision revert restart` Restart the revert, resetting the current revert state **Usage:** `lore revision revert restart >` -###### **Arguments:** +### Arguments * `` — Any number of paths or files to target -###### **Options:** +### Options * `--targets ` — Path to a targets file - - ## `lore revision revert resolve` Resolve conflicts @@ -1404,122 +1256,106 @@ Resolve conflicts **Usage:** `lore revision revert resolve > resolve ` -###### **Subcommands:** +### Subcommands * `mine` — Resolve using my changes * `theirs` — Resolve using the incoming changes -###### **Arguments:** +### Arguments * `` — Any number of paths or files to target -###### **Options:** +### Options * `--targets ` — Path to a targets file - - ## `lore revision revert resolve mine` Resolve using my changes **Usage:** `lore revision revert resolve mine >` -###### **Arguments:** +### Arguments * `` — Any number of paths or files to target -###### **Options:** +### Options * `--targets ` — Path to a targets file - - ## `lore revision revert resolve theirs` Resolve using the incoming changes **Usage:** `lore revision revert resolve theirs >` -###### **Arguments:** +### Arguments * `` — Any number of paths or files to target -###### **Options:** +### Options * `--targets ` — Path to a targets file - - ## `lore revision revert abort` Abort a revert **Usage:** `lore revision revert abort` - - ## `lore revision metadata` Manage metadata of a given revision **Usage:** `lore revision metadata ` -###### **Subcommands:** +### Subcommands * `clear` — Clear metadata for a staged revision * `get` — Get metadata from a revision * `set` — Set metadata on for a staged revision - - ## `lore revision metadata clear` Clear metadata for a staged revision **Usage:** `lore revision metadata clear` - - ## `lore revision metadata get` Get metadata from a revision **Usage:** `lore revision metadata get [OPTIONS] [key]` -###### **Arguments:** +### Arguments * `` — Attribute to get metadata for -###### **Options:** +### Options * `--revision ` — Revision to get metadata for - - ## `lore revision metadata set` Set metadata on for a staged revision **Usage:** `lore revision metadata set [OPTIONS] [pairs]...` -###### **Arguments:** +### Arguments * `` — Metadata key/value pairs -###### **Options:** +### Options * `--binary` — Indicator that values are paths to files - - ## `lore file` File commands **Usage:** `lore file ` -###### **Subcommands:** +### Subcommands * `info` — Get info about the given file or directory * `metadata` — Manage metadata of a given file or directory @@ -1534,147 +1370,129 @@ File commands * `write` — Write data to a specific location * `hash` — Hash a local file - - ## `lore file info` Get info about the given file or directory **Usage:** `lore file info [OPTIONS] >` -###### **Arguments:** +### Arguments * `` — Any number of paths or files -###### **Options:** +### Options * `--targets ` — Path to a targets file containing all the paths to all files * `--revision ` — Revision to get info from * `--local` — If given, calculate the local file system size and hash based on the current local filter * `--filtered` — If given, calculate the repository size based on the current local filter - - ## `lore file metadata` Manage metadata of a given file or directory **Usage:** `lore file metadata ` -###### **Subcommands:** +### Subcommands * `clear` — Clear metadata for a staged file * `get` — Get metadata from a file * `set` — Set metadata on for a staged file - - ## `lore file metadata clear` Clear metadata for a staged file **Usage:** `lore file metadata clear ` -###### **Arguments:** +### Arguments * `` — File path to clear metadata for - - ## `lore file metadata get` Get metadata from a file **Usage:** `lore file metadata get [OPTIONS] [key]` -###### **Arguments:** +### Arguments * `` — File to get metadata for * `` — Attribute to get metadata for -###### **Options:** +### Options * `--revision ` — Revision to get metadata for - - ## `lore file metadata set` Set metadata on for a staged file **Usage:** `lore file metadata set [OPTIONS] [pairs]...` -###### **Arguments:** +### Arguments * `` — File path to set metadata on * `` — Metadata key/value pairs -###### **Options:** +### Options * `--binary` — Indicator that values are paths to files - - ## `lore file dependency` Manage file dependencies **Usage:** `lore file dependency ` -###### **Subcommands:** +### Subcommands * `add` — Add dependency edges from a source file to one or more dependency files * `remove` — Remove dependency edges from a source file to one or more dependency files * `list` — List dependencies or dependents for files - - ## `lore file dependency add` Add dependency edges from a source file to one or more dependency files **Usage:** `lore file dependency add [OPTIONS] [dependencies]...` -###### **Arguments:** +### Arguments * `` — Source file that depends on the listed dependencies * `` — One or more dependency file paths -###### **Options:** +### Options * `--tag ` — Tags to apply to all added dependency edges * `--force` — Skip cycle detection - - ## `lore file dependency remove` Remove dependency edges from a source file to one or more dependency files **Usage:** `lore file dependency remove [OPTIONS] [dependencies]...` -###### **Arguments:** +### Arguments * `` — Source file to remove dependencies from * `` — One or more dependency file paths to remove -###### **Options:** +### Options * `--tag ` — Remove only specific tags instead of entire edges - - ## `lore file dependency list` List dependencies or dependents for files **Usage:** `lore file dependency list [OPTIONS] [paths]...` -###### **Arguments:** +### Arguments * `` — Paths to list dependencies for (all files if omitted) -###### **Options:** +### Options * `--reverse` — List dependents instead of dependencies * `--recursive` — Recursively resolve transitive dependencies @@ -1684,8 +1502,6 @@ List dependencies or dependents for files Default value: `0` * `--revision ` — Revision to query (defaults to staged/current) - - ## `lore file stage` Stage changes for commit. @@ -1699,25 +1515,25 @@ Specific file paths are checked against the filesystem and staged if content dif **Usage:** `lore file stage [OPTIONS] > stage [OPTIONS] ` -###### **Subcommands:** +### Subcommands * `move` — Move or rename a file or directory * `merge` — Stage as a merge -###### **Arguments:** +### Arguments * `` — Any number of paths or files -###### **Options:** +### Options * `--case ` — Case change handling Possible values: - - `error`: + * `error`: Generate error on case mismatch - - `keep`: + * `keep`: Keep current case in repository (update file system) - - `rename`: + * `rename`: Rename case in repository (keep file system) * `--scan` — Walk the filesystem under the given paths to detect modified, added, and deleted files. @@ -1727,37 +1543,31 @@ Specific file paths are checked against the filesystem and staged if content dif Without `--scan`, directory staging stages only files already marked dirty under that directory — mark them first with `lore dirty `, or run `lore status --scan` to reconcile dirty flags across a tree. Single-file stage paths are always checked against the filesystem regardless of this flag. * `--targets ` — Path to a targets file containing all the paths to all files - - ## `lore file stage move` Move or rename a file or directory **Usage:** `lore file stage move ` -###### **Arguments:** +### Arguments * `` — Original path of file * `` — New path of file - - ## `lore file stage merge` Stage as a merge **Usage:** `lore file stage merge >` -###### **Arguments:** +### Arguments * `` — Any number of paths or files -###### **Options:** +### Options * `--targets ` — Path to a targets file containing all the paths to all files - - ## `lore file dirty` Mark files as dirty so they show up in `lore status` and get picked up by directory-scoped `lore stage` (no content is read or staged). @@ -1766,126 +1576,112 @@ Use when files were changed externally and you want to notify Lore of specific p **Usage:** `lore file dirty [OPTIONS] [paths]... [COMMAND]` -###### **Subcommands:** +### Subcommands * `move` — Mark a file as moved (dirty) * `copy` — Mark a file as copied (dirty) -###### **Arguments:** +### Arguments * `` — Any number of paths or files -###### **Options:** +### Options * `--targets ` — Path to a targets file containing all the paths to all files - - ## `lore file dirty move` Mark a file as moved (dirty) **Usage:** `lore file dirty move ` -###### **Arguments:** +### Arguments * `` — Original path of file * `` — New path of file - - ## `lore file dirty copy` Mark a file as copied (dirty) **Usage:** `lore file dirty copy ` -###### **Arguments:** +### Arguments * `` — Source path of file * `` — Destination path of copy - - ## `lore file unstage` Unstage changes to a file or directory **Usage:** `lore file unstage >` -###### **Arguments:** +### Arguments * `` — Any number of paths or files to unstage -###### **Options:** +### Options * `--targets ` — Path to a targets file - - ## `lore file reset` Reset changes to a path or file to the current revision, discarding your local changes **Usage:** `lore file reset [OPTIONS] >` -###### **Arguments:** +### Arguments * `` — Any number of paths or files -###### **Options:** +### Options * `--purge` — Delete untracked files * `--targets ` — Path to a targets file containing all the paths to all files * `--revision ` — Revision to reset files to * `--last-merged-from ` — If given, the files will be reset to the last point of merge from this branch, or the branch point from this branch if no merge has been performed - - ## `lore file obliterate` Obliterate a file or fragment **Usage:** `lore file obliterate <--address
|--path >` -###### **Options:** +### Options * `--address
` — Address of a blob * `--path ` — Path to a file - - ## `lore file history` List revisions of a file **Usage:** `lore file history [OPTIONS] [LENGTH]` -###### **Arguments:** +### Arguments * `` — File path to get revisions for * `` — Number of revisions to show -###### **Options:** +### Options * `--revision ` — Revision to start from * `--branch ` — Show branch revisions * `--depth ` — Number of revisions to search initially * `--oneline` — Output each revision on one line only - - ## `lore file diff` Show differences between two revisions of a file **Usage:** `lore file diff [OPTIONS] [paths]...` -###### **Arguments:** +### Arguments * `` — Any number of paths or files -###### **Options:** +### Options * `--source ` — Optional signature of the source revision to diff from, by default the current revision * `--target ` — Optional signature of the target revision to diff to, by default the current file system state @@ -1897,46 +1693,40 @@ Show differences between two revisions of a file * `--ignore-space-change` — Collapse runs of internal whitespace to a single space before comparing * `--targets ` — Path to a targets file containing all the paths to all files - - ## `lore file write` Write data to a specific location **Usage:** `lore file write [OPTIONS] --output ` -###### **Options:** +### Options * `--address
` — Address of a blob * `--path ` — Path to a file * `--revision ` — Revision specifier * `--output ` — Path to a destination - - ## `lore file hash` Hash a local file **Usage:** `lore file hash [OPTIONS] [paths]...` -###### **Arguments:** +### Arguments * `` — Any number of paths or files to unstage -###### **Options:** +### Options * `--targets ` — Path to a targets file - - ## `lore auth` Authentication commands **Usage:** `lore auth ` -###### **Subcommands:** +### Subcommands * `login` — Authenticate the CLI * `info` — Display identity information for the current user or specified user IDs @@ -1944,247 +1734,211 @@ Authentication commands * `logout` — Remove stored authentication and authorization tokens * `clear` — Clear all stored authentication data - - ## `lore auth login` Authenticate the CLI **Usage:** `lore auth login [OPTIONS] [remote-url]` -###### **Arguments:** +### Arguments * `` — Server URL -###### **Options:** +### Options * `--token-type ` — Token type for non-interactive login (e.g. "api-key", "eg1", "lore") * `--token ` — Token value for non-interactive login (requires --token-type) * `--auth-url ` — Auth service URL with scheme (e.g. `ucs-auth://auth.example.com`). Required when logging in with `--token` outside a repository without a remote-url * `--no-browser` — Avoid opening a browser to login - - ## `lore auth info` Display identity information for the current user or specified user IDs **Usage:** `lore auth info [OPTIONS] [user-id]...` -###### **Arguments:** +### Arguments * `` — User IDs to resolve (omit for current user) -###### **Options:** +### Options * `--with-token` — Include cached tokens in the output - - ## `lore auth list` List all stored authentication identities **Usage:** `lore auth list [OPTIONS]` -###### **Options:** +### Options * `--with-token` — Include cached tokens in the output - - ## `lore auth logout` Remove stored authentication and authorization tokens **Usage:** `lore auth logout [OPTIONS]` -###### **Options:** +### Options * `--auth-url ` — Auth service URL (omit to use current repository's auth URL) * `--resource ` — Resource ID to remove a specific authorization (e.g. "urc-{id}") * `--user-id ` — User ID to remove (omit to remove all identities) - - ## `lore auth clear` Clear all stored authentication data **Usage:** `lore auth clear` - - ## `lore layer` Layer commands **Usage:** `lore layer ` -###### **Subcommands:** +### Subcommands * `add` — Add a repository layer * `remove` — Remove a repository layer * `list` — List repository layers - - ## `lore layer add` Add a repository layer **Usage:** `lore layer add [OPTIONS] ` -###### **Arguments:** +### Arguments * `` — Path in the current repository where the layer should be placed * `` — Repository to add as a layer, either an ID or a name * `` — Path in the layer repository where the layer should start -###### **Options:** +### Options * `--metadata ` — Metadata key to use for matching revisions - - ## `lore layer remove` Remove a repository layer **Usage:** `lore layer remove [OPTIONS] [repository]` -###### **Arguments:** +### Arguments * `` — Path in the current repository where the layer is placed * `` — Repository placed as a layer. Optional when the target path matches a single configured layer; required to disambiguate when multiple layers share the same target path -###### **Options:** +### Options * `--purge` — Also delete untracked files and all directories inside the layer mount - - ## `lore layer list` List repository layers **Usage:** `lore layer list` - - ## `lore logfile` Logfile commands **Usage:** `lore logfile ` -###### **Subcommands:** +### Subcommands * `info` — Info - - ## `lore logfile info` Info **Usage:** `lore logfile info` - - ## `lore login` Authenticate the CLI **Usage:** `lore login [OPTIONS] [remote-url]` -###### **Arguments:** +### Arguments * `` — Server URL -###### **Options:** +### Options * `--token-type ` — Token type for non-interactive login (e.g. "api-key", "eg1", "lore") * `--token ` — Token value for non-interactive login (requires --token-type) * `--auth-url ` — Auth service URL with scheme (e.g. `ucs-auth://auth.example.com`). Required when logging in with `--token` outside a repository without a remote-url * `--no-browser` — Avoid opening a browser to login - - ## `lore link` Link commands **Usage:** `lore link ` -###### **Subcommands:** +### Subcommands * `add` — Link to the given point in the repository and subpath from the given repository * `remove` — Remove the link at the given point in the repository * `update` — Update the link to a new pin * `list` — List all links in the repository - - ## `lore link add` Link to the given point in the repository and subpath from the given repository **Usage:** `lore link add [OPTIONS] ` -###### **Arguments:** +### Arguments * `` — Path in the current repository where the repository should be linked in * `` — Repository URL * `` — Path in the link repository that should be linked in -###### **Options:** +### Options * `--pin ` — Branch or specific revision to pin the link to, defaulting to latest on the main branch * `--disable-branching` — Disable automatic branch creation in the linked repository - - ## `lore link remove` Remove the link at the given point in the repository **Usage:** `lore link remove ` -###### **Arguments:** +### Arguments * `` — Path in the current repository where the module is linked in - - ## `lore link update` Update the link to a new pin **Usage:** `lore link update [OPTIONS] ` -###### **Arguments:** +### Arguments * `` — Path in the repository where the link should be updated -###### **Options:** +### Options * `--pin ` — Branch or specific revision to pin the link to, defaulting to latest on the current branch - - ## `lore link list` List all links in the repository **Usage:** `lore link list [OPTIONS]` -###### **Options:** +### Options * `--staged` — Only show links with staged changes - - ## `lore status` Show current repository status. @@ -2195,11 +1949,11 @@ Pass `--scan` to walk the filesystem under the given paths, reconcile every file **Usage:** `lore status [OPTIONS] [PATH]...` -###### **Arguments:** +### Arguments * `` — Optional paths in repository -###### **Options:** +### Options * `--scan` — Walk the filesystem under the given paths and reconcile every file against the current revision. @@ -2214,20 +1968,18 @@ Pass `--scan` to walk the filesystem under the given paths, reconcile every file * `--count` — Count directories and files (staged state if present, else current revision; view-filtered) * `--targets ` — Path to a targets file - - ## `lore clone` Clone a remote repository into the given path **Usage:** `lore clone [OPTIONS] [path]` -###### **Arguments:** +### Arguments * `` — URL of repository * `` — Path to clone into -###### **Options:** +### Options * `--view ` — Optional client side view filter file * `--revision ` — Optional revision to sync @@ -2249,8 +2001,6 @@ Clone a remote repository into the given path Default value: `0` - - ## `lore stage` Stage changes for commit. @@ -2264,25 +2014,25 @@ Specific file path: checked against the filesystem and staged if its on-disk con **Usage:** `lore stage [OPTIONS] > stage [OPTIONS] ` -###### **Subcommands:** +### Subcommands * `move` — Move or rename a file or directory * `merge` — Stage as a merge -###### **Arguments:** +### Arguments * `` — Any number of paths or files -###### **Options:** +### Options * `--case ` — Case change handling Possible values: - - `error`: + * `error`: Generate error on case mismatch - - `keep`: + * `keep`: Keep current case in repository (update file system) - - `rename`: + * `rename`: Rename case in repository (keep file system) * `--scan` — Walk the filesystem under the given paths to detect modified, added, and deleted files. @@ -2292,37 +2042,31 @@ Specific file path: checked against the filesystem and staged if its on-disk con Without `--scan`, directory staging stages only files already marked dirty under that directory — mark them first with `lore dirty `, or run `lore status --scan` to reconcile dirty flags across a tree. Single-file stage paths are always checked against the filesystem regardless of this flag. * `--targets ` — Path to a targets file containing all the paths to all files - - ## `lore stage move` Move or rename a file or directory **Usage:** `lore stage move ` -###### **Arguments:** +### Arguments * `` — Original path of file * `` — New path of file - - ## `lore stage merge` Stage as a merge **Usage:** `lore stage merge >` -###### **Arguments:** +### Arguments * `` — Any number of paths or files -###### **Options:** +### Options * `--targets ` — Path to a targets file containing all the paths to all files - - ## `lore dirty` Mark files as dirty so they show up in `lore status` and get picked up by `lore stage` (no content is read or staged). @@ -2331,93 +2075,83 @@ Use this when your editor or build tool has modified files and you want to infor **Usage:** `lore dirty [OPTIONS] [paths]... [COMMAND]` -###### **Subcommands:** +### Subcommands * `move` — Mark a file as moved (dirty) * `copy` — Mark a file as copied (dirty) -###### **Arguments:** +### Arguments * `` — Any number of paths or files -###### **Options:** +### Options * `--targets ` — Path to a targets file containing all the paths to all files - - ## `lore dirty move` Mark a file as moved (dirty) **Usage:** `lore dirty move ` -###### **Arguments:** +### Arguments * `` — Original path of file * `` — New path of file - - ## `lore dirty copy` Mark a file as copied (dirty) **Usage:** `lore dirty copy ` -###### **Arguments:** +### Arguments * `` — Source path of file * `` — Destination path of copy - - ## `lore unstage` Unstage changes to a file or directory **Usage:** `lore unstage >` -###### **Arguments:** +### Arguments * `` — Any number of paths or files to unstage -###### **Options:** +### Options * `--targets ` — Path to a targets file - - ## `lore reset` Reset changes to a file or directory **Usage:** `lore reset [OPTIONS] >` -###### **Arguments:** +### Arguments * `` — Any number of paths or files -###### **Options:** +### Options * `--purge` — Delete untracked files * `--targets ` — Path to a targets file containing all the paths to all files * `--revision ` — Revision to reset files to * `--last-merged-from ` — If given, the files will be reset to the last point of merge from this branch, or the branch point from this branch if no merge has been performed - - ## `lore diff` Show differences between two revisions of a file **Usage:** `lore diff [OPTIONS] [paths]...` -###### **Arguments:** +### Arguments * `` — Any number of paths or files -###### **Options:** +### Options * `--source ` — Optional signature of the source revision to diff from, by default the current revision * `--target ` — Optional signature of the target revision to diff to, by default the current file system state @@ -2429,38 +2163,34 @@ Show differences between two revisions of a file * `--ignore-space-change` — Collapse runs of internal whitespace to a single space before comparing * `--targets ` — Path to a targets file containing all the paths to all files - - ## `lore history` List revisions of a repository **Usage:** `lore history [OPTIONS] [LENGTH]` -###### **Arguments:** +### Arguments * `` — Number of revisions to show -###### **Options:** +### Options * `--revision ` — Start listing from the specified revision. If not specified, start listing from the current branch latest revision * `--branch ` — Show branch revisions * `--only-branch` — Stop when reaching a revision on a different branch (includes the branch point revision) * `--oneline` — Output each revision on one line only - - ## `lore commit` Commit the staged revision **Usage:** `lore commit [OPTIONS] ` -###### **Arguments:** +### Arguments * `` — Commit message -###### **Options:** +### Options * `--stats` — Print stats * `--link ` — Commit only changes in this linked repository (mount path relative to repo root) @@ -2468,21 +2198,19 @@ Commit the staged revision * `--layer ` — Commit only changes in this layer (mount path relative to repo root) * `--layer-message ` — Per-layer commit message. Takes two values: . Can be specified multiple times - - ## `lore sync` Synchronize to a repository state **Usage:** `lore sync [OPTIONS] [revision]` -**Command Alias:** `synchronize` +**Command Alias: `synchronize` -###### **Arguments:** +### Arguments * `` — Revision hash signature to synchronize to. Can be a signature on any branch — if the target revision is on a different branch, the current branch is updated accordingly. Can be a partial hash signature -###### **Options:** +### Options * `--forward-changes` — Fast forward any local changes if syncing to a local revision * `--reset` — Reset any local modified files to match the incoming revision @@ -2493,178 +2221,151 @@ Synchronize to a repository state Default value: `0` - - ## `lore push` Push commits to remote **Usage:** `lore push [OPTIONS] [branch]` -###### **Arguments:** +### Arguments * `` — Optional name or identifier of the branch, push current branch if not specified -###### **Options:** +### Options * `--fast-forward-merge` — Allow the server to fast-forward merge if the target branch head has moved - - ## `lore lock` Lock file **Usage:** `lore lock ` -###### **Subcommands:** +### Subcommands * `acquire` — Acquire lock on file(s) * `status` — Get lock status on file(s) * `query` — Query the lock status given a branch, owner or path * `release` — Release lock on file(s) - - ## `lore lock acquire` Acquire lock on file(s) **Usage:** `lore lock acquire >` -###### **Arguments:** +### Arguments * `` — Any number of file paths to lock -###### **Options:** +### Options * `--branch ` — Branch where lock is to be acquired - - ## `lore lock status` Get lock status on file(s) **Usage:** `lore lock status [OPTIONS] [paths]...` -###### **Arguments:** +### Arguments * `` — Any number of file paths to get the lock status -###### **Options:** +### Options * `--branch ` — Branch where lock was acquired - - ## `lore lock query` Query the lock status given a branch, owner or path **Usage:** `lore lock query [OPTIONS]` -###### **Options:** +### Options * `--branch ` — Branch to query locks on * `--owner ` — Owner to query locks belonging to them * `--path ` — Path to query lock information on - - ## `lore lock release` Release lock on file(s) **Usage:** `lore lock release [OPTIONS] [paths]...` -###### **Arguments:** +### Arguments * `` — Any number of file paths to release the lock -###### **Options:** +### Options * `--branch ` — Branch where lock was acquired * `--owner ` — Owner of the lock - - ## `lore service` Manage the repository in a service process **Usage:** `lore service ` -###### **Subcommands:** +### Subcommands * `run` — Run this process as the service * `start` — Start service for a repository * `stop` — Stop service for a repository - - ## `lore service run` Run this process as the service **Usage:** `lore service run` - - ## `lore service start` Start service for a repository **Usage:** `lore service start` - - ## `lore service stop` Stop service for a repository **Usage:** `lore service stop [all]` -###### **Arguments:** +### Arguments * `` — Flag to stop servicing all repositories Possible values: `true`, `false` - - - ## `lore notification` Notifications **Usage:** `lore notification ` -###### **Subcommands:** +### Subcommands * `subscribe` — Subscribe to events on the given repository - - ## `lore notification subscribe` Subscribe to events on the given repository **Usage:** `lore notification subscribe [seconds]` -###### **Arguments:** +### Arguments * `` — Time to be subscribed in seconds - - ## `lore completions` Generate terminal autocompletions **Usage:** `lore completions [path]` -###### **Arguments:** +### Arguments * `` — Shell to generate autocompletions for @@ -2672,59 +2373,47 @@ Generate terminal autocompletions * `` — Directory path to write the autocompletion script to - - ## `lore shared-store` Manage the shared store **Usage:** `lore shared-store ` -###### **Subcommands:** +### Subcommands * `create` — * `info` — * `set-use-automatically` — - - ## `lore shared-store create` **Usage:** `lore shared-store create [OPTIONS] ` -###### **Arguments:** +### Arguments * `` — Remote URL that will back the store -###### **Options:** +### Options * `--path ` — Where to create the shared store * `--make-default ` — Set this as the default shared store in the global config file, defaults to true Possible values: `true`, `false` - - - ## `lore shared-store info` **Usage:** `lore shared-store info` - - ## `lore shared-store set-use-automatically` **Usage:** `lore shared-store set-use-automatically ` -###### **Arguments:** +### Arguments * `` — Whether to automatically use the shared store Possible values: `true`, `false` - - -
diff --git a/docs/roadmap.md b/docs/roadmap.md index 6aa1bd2..59c59db 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -78,7 +78,7 @@ With the foundations in place, the focus shifts to scale and collaboration: grap **Surface a visual version-control workflow inside the Unreal Editor, the interface you already work in.** A Lore plugin brings everyday Lore operations directly into the tool artists and developers use to build with Unreal Engine, so versioning your work is a native part of the editor rather than a separate command-line step — and artists who never touch a terminal can manage it themselves. It builds on the Lore plugin that already ships with UEFN, and rather than living as a separate Lore project, it will be included in the native Unreal Engine codebase and delivered as part of the engine itself. -### Web client and code review tools +### Web client **Timeline:** 2027 · **Status:** Committed diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md index 7de2ce0..4f19133 100644 --- a/docs/tutorials/README.md +++ b/docs/tutorials/README.md @@ -13,12 +13,12 @@ Tutorials are lessons. They teach by doing. You'll work through realistic exampl - **Writing a new Tutorial?** Start at the [doc-standards walkthrough](../developing/doc-standards/writing-a-doc.md). - [Tutorial template](tutorial-template.md). Copy this when starting a new Tutorial. -## Core Tutorials +## Core tutorials - [Setup Identity](setup-identity.md) — configure your user identity for commits. - [Configure Loreignore](loreignore.md) — set up a .loreignore file for your project. -## Advanced Connectivity +## Advanced connectivity - [No-Auth (Internal)](auth-none.md) — connecting to unauthenticated internal servers. - [mTLS (High Security)](auth-mtls.md) — high-security certificate-based authentication. diff --git a/docs/tutorials/add-unreal-project.md b/docs/tutorials/add-unreal-project.md index 0042cbc..9694420 100644 --- a/docs/tutorials/add-unreal-project.md +++ b/docs/tutorials/add-unreal-project.md @@ -42,7 +42,7 @@ In this tutorial, you will migrate an existing Unreal Engine or UEFN project fro 5. **Commit the ignore file.** - Commit the `.loreignore` file first so it is active before you stage the rest of the project. + Commit the `.loreignore` file first so it's active before you stage the rest of the project. ```bash lore stage .loreignore @@ -61,7 +61,7 @@ In this tutorial, you will migrate an existing Unreal Engine or UEFN project fro ## Verify -Check that your project is safely stored on the server. +Check that your project is stored on the server. ```bash lore status diff --git a/docs/tutorials/auth-mtls.md b/docs/tutorials/auth-mtls.md index acaec72..012b1da 100644 --- a/docs/tutorials/auth-mtls.md +++ b/docs/tutorials/auth-mtls.md @@ -1,8 +1,8 @@ -# Guide: High-Security mTLS Authentication +# Guide: High-security mTLS authentication mTLS (Mutual TLS) requires every user to have a unique certificate signed by a Root Authority (CA) that the server trusts. This is the most secure method but has the highest management overhead. -## 1. Create a Root CA +## 1. Create a root CA If you don't have one, create a CA to sign user certificates: @@ -25,7 +25,7 @@ pkey_file = "/opt/loreserver/certs/key.pem" cert_chain = "/opt/loreserver/certs/ca.pem" # The Trusted CA ``` -## 3. Generate User Certificates +## 3. Generate user certificates For **each person** on the team, you must generate a keypair and sign it: @@ -33,6 +33,6 @@ For **each person** on the team, you must generate a keypair and sign it: 2. **Request:** `openssl req -new -key user-key.pem -out user.csr` 3. **Sign:** `openssl x509 -req -in user.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial -out user-cert.pem -days 365` -## 4. Distribute to User +## 4. Distribute to user The user must place `user-cert.pem` and `user-key.pem` on their machine and configure their Lore client to use them (refer to Lore CLI advanced config). diff --git a/docs/tutorials/auth-none.md b/docs/tutorials/auth-none.md index 900a499..96614a4 100644 --- a/docs/tutorials/auth-none.md +++ b/docs/tutorials/auth-none.md @@ -1,4 +1,4 @@ -# Guide: Running Lore Unauthenticated (Internal/VPN only) +# Guide: Running Lore unauthenticated (internal/VPN only) This is the simplest way to run Lore for a small team behind a firewall or VPN. Relying on the network for security and user-provided strings for identity. @@ -17,7 +17,7 @@ cert_file = "/opt/loreserver/certs/cert.pem" pkey_file = "/opt/loreserver/certs/key.pem" ``` -## 2. Restart the Service +## 2. Restart the service After editing the config, restart the server: @@ -25,8 +25,8 @@ After editing the config, restart the server: sudo systemctl restart loreserver ``` -## 3. Client Usage +## 3. Client usage -Since there is no "login", users connect by pointing their Lore client to your server IP/hostname. +Since there is no "login," users connect by pointing their Lore client to your server IP/hostname. Users should follow the [Setting Up Your Lore Identity](./setup-identity.md) guide to ensure their names show up in the history. diff --git a/docs/tutorials/loreignore.md b/docs/tutorials/loreignore.md index 4d4abd9..320ce64 100644 --- a/docs/tutorials/loreignore.md +++ b/docs/tutorials/loreignore.md @@ -1,4 +1,4 @@ -# Configure Loreignore for Unreal Engine +# Configure loreignore for Unreal Engine In this tutorial, you will set up a `.loreignore` file tailored for Unreal Engine projects to ensure that only source assets are tracked, while temporary build files and caches are ignored. @@ -56,7 +56,7 @@ In this tutorial, you will set up a `.loreignore` file tailored for Unreal Engin ## Verify -Check that the ignored directories do not appear in the staged or untracked file list. +Check that the ignored directories don't appear in the staged or untracked file list. ```bash lore status @@ -72,5 +72,5 @@ Changes not staged for commit: ## Next steps -- [Stage and commit your project](./add-unreal-project.md#step-6) +- [Stage and commit your project](./add-unreal-project.md#steps) - [Set up your Lore identity](./setup-identity.md) From a819092b7d51da5065e3cd5ae3e24432f4595218 Mon Sep 17 00:00:00 2001 From: Jonathan McMichael Date: Tue, 23 Jun 2026 23:03:39 -0500 Subject: [PATCH 3/3] removed whitespaces Signed-off-by: Jonathan McMichael --- docs/tutorials/auth-none.md | 2 +- docs/tutorials/loreignore.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/auth-none.md b/docs/tutorials/auth-none.md index 96614a4..8341be1 100644 --- a/docs/tutorials/auth-none.md +++ b/docs/tutorials/auth-none.md @@ -9,7 +9,7 @@ In your server's `local.toml`, ensure the following is set: ```toml [server.quic] # Allow any client to connect without a certificate -verify_client_certs = false +verify_client_certs = false [server.quic.certificate] # The server's own certificate (required for TLS/QUIC) diff --git a/docs/tutorials/loreignore.md b/docs/tutorials/loreignore.md index 320ce64..8141a92 100644 --- a/docs/tutorials/loreignore.md +++ b/docs/tutorials/loreignore.md @@ -33,7 +33,7 @@ In this tutorial, you will set up a `.loreignore` file tailored for Unreal Engin .idea/ *.sln *.suo - + # UEFN specific (if applicable) .urc/ ```