lore: Handle nested repositories as working-tree scan boundaries

A child directory that carries its own `.lore/` control directory is a
nested repository — its contents belong to it, not the parent. The parent's
working-tree scan (from `status --scan` or `stage --scan`) must treat it as
an implicit boundary: do not descend into or index it, just as git treats a
nested `.git` directory as a submodule boundary.

When scanning the filesystem, skip any child directory that is itself a Lore
working copy. A node previously indexed for such a directory (from before the
boundary check existed) falls through to the delete pass, where it is cleared
as a reverted uncommitted directory add on the next scan.

Add a new optional-paths argument struct (FileOptionalPathsTargetsArgs) to
support `lore stage --scan` with no path, which reconciles and stages the
entire working tree from the repository root. Without `--scan`, a path
remains required.

Includes: a Rust test covering the nested-repository boundary (with
state-based setup), plus a CLI smoke test for both nested-repository handling
and `stage --scan` with no path.

Signed-off-by: Huân Lê-Vương <65440815+lehuan5062@users.noreply.github.com>

Author: lehuan5062

docs/reference/lore-cli-commands.md

@@ -1696,7 +1696,7 @@ Specific file paths are checked against the filesystem and staged if content dif
 
 `--scan` walks the filesystem under the given paths, marks every detected modification/add/delete dirty, and stages them in one step.
 
-**Usage:** `lore file stage [OPTIONS] <paths|--targets <file>>
+**Usage:** `lore file stage [OPTIONS] [paths|--targets <file>]
        stage [OPTIONS] <COMMAND>`
 
 ###### **Subcommands:**
@@ -1725,6 +1725,8 @@ Specific file paths are checked against the filesystem and staged if content dif
    Detected changes are marked dirty and staged in a single pass. Use this when changes were made externally (without going through `lore dirty`), or to recover after losing track of dirty state. Equivalent in effect to running `lore status --scan` followed by `lore stage`, but performed in one traversal.
 
    Without `--scan`, directory staging stages only files already marked dirty under that directory — mark them first with `lore dirty <paths>`, 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.
+
+   With `--scan` and no path, `lore` reconciles and stages the entire working tree from the repository root, matching the bulk reconciliation `lore dirty` recommends.
 * `--targets <file>` — Path to a targets file containing all the paths to all files
 
 
@@ -2261,7 +2263,7 @@ Specific file path: checked against the filesystem and staged if its on-disk con
 
 `--scan`: forces a filesystem walk under the given paths, marks modified, added, and deleted files dirty, and stages them in one step. Use this when changes were made externally without going through `lore dirty`, or to recover after losing track of dirty state.
 
-**Usage:** `lore stage [OPTIONS] <paths|--targets <file>>
+**Usage:** `lore stage [OPTIONS] [paths|--targets <file>]
        stage [OPTIONS] <COMMAND>`
 
 ###### **Subcommands:**
@@ -2290,6 +2292,8 @@ Specific file path: checked against the filesystem and staged if its on-disk con
    Detected changes are marked dirty and staged in a single pass. Use this when changes were made externally (without going through `lore dirty`), or to recover after losing track of dirty state. Equivalent in effect to running `lore status --scan` followed by `lore stage`, but performed in one traversal.
 
    Without `--scan`, directory staging stages only files already marked dirty under that directory — mark them first with `lore dirty <paths>`, 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.
+
+   With `--scan` and no path, `lore` reconciles and stages the entire working tree from the repository root, matching the bulk reconciliation `lore dirty` recommends.
 * `--targets <file>` — Path to a targets file containing all the paths to all files
 
 

lore-client/src/cli/commands/file.rs

@@ -317,11 +317,15 @@ pub struct FileStageArgs {
     /// `lore dirty <paths>`, 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.
+    ///
+    /// With `--scan` and no path, `lore` reconciles and stages the entire
+    /// working tree from the repository root, matching the bulk reconciliation
+    /// `lore dirty` recommends.
     #[clap(long, action)]
     scan: bool,
 
     #[clap(flatten)]
-    paths: FilePathsTargetsArgs,
+    paths: FileOptionalPathsTargetsArgs,
 
     #[clap(flatten)]
     stage: FileStageCommandArgs,
@@ -1146,7 +1150,22 @@ pub fn handle_file_stage(globals: LoreGlobalArgs, args: &FileStageArgs) -> u8 {
 
     // Standard stage
     if args.stage.subcommand.is_none() {
-        let paths = convert_paths_and_targets(&args.paths.paths, &args.paths.targets);
+        let mut paths = convert_paths_and_targets(&args.paths.paths, &args.paths.targets);
+
+        // `lore stage --scan` with no path reconciles and stages the whole
+        // working tree, defaulting to the repository root. Without `--scan` a
+        // path is still required, since directory staging without a scan only
+        // picks up already-dirty entries and an empty path set has nothing to do.
+        if paths.is_empty() {
+            if args.scan {
+                paths = LoreArray::from_vec(vec![LoreString::from(".")]);
+            } else {
+                println!(
+                    "error: a path is required; pass one or more paths, or use --scan to stage the whole tree"
+                );
+                return 1;
+            }
+        }
 
         let stage_args = LoreFileStageArgs {
             paths,

lore-revision/src/state.rs

@@ -5630,6 +5630,23 @@ async fn emit_filesystem_subtree_deletes(
     Ok(false)
 }
 
+/// Returns whether the on-disk directory at `relative_path` (resolved under
+/// `repository_root`) is itself a Lore working copy — it contains its own
+/// `.lore/` (or legacy `.urc/`) control directory.
+///
+/// Such a nested repository is an implicit boundary for the parent's
+/// working-tree scan: its contents belong to the nested repository, not the
+/// parent, so the parent neither descends into nor indexes it. This mirrors the
+/// way git treats a nested `.git` directory as a submodule boundary rather than
+/// pulling its files into the outer repository.
+fn is_nested_repository_root(
+    repository_root: &std::path::Path,
+    relative_path: &RelativePath,
+) -> bool {
+    let absolute_path = relative_path.to_absolute_path(repository_root);
+    absolute_path.join(DOT_LORE).is_dir() || absolute_path.join(DOT_URC).is_dir()
+}
+
 #[allow(clippy::too_many_arguments)]
 async fn diff_filesystem_directory_walk(
     ctx: &DiffFilesystemContext,
@@ -5654,6 +5671,21 @@ async fn diff_filesystem_directory_walk(
             .push_into_buf(item.name.as_str())
             .freeze();
 
+        // A child directory that is itself a Lore working copy (it contains its
+        // own `.lore`/`.urc` control directory) is an implicit boundary: do not
+        // descend into or index it, mirroring how git ignores nested `.git`
+        // directories. Skipping it keeps the nested repository's contents out of
+        // the parent's tree. A node previously indexed for it (from before this
+        // boundary check existed) is left unmatched and so falls through to the
+        // delete pass below, where an empty never-committed entry is discarded —
+        // clearing a pre-existing stale "zombie" entry on the next scan.
+        if item.metadata.is_dir()
+            && is_nested_repository_root(ctx.from.repository.require_path()?, &item_path)
+        {
+            lore_trace!("Skipping nested repository root {item_path}");
+            continue;
+        }
+
         if ctx.from.repository.filter.emit_excludes(
             &item_path,
             item.metadata.is_dir(),
@@ -5962,13 +5994,14 @@ async fn diff_filesystem_directory_walk(
         };
 
         // A directory node that exists in state_from but neither in state_current
-        // (never committed) nor on disk is a reverted, uncommitted add: the
-        // directory was staged and then removed from disk before any commit,
-        // together with whatever of its contents had been staged under it.
-        // Reporting it as a `Delete` is meaningless because there is no committed
-        // base to delete from, and no mutation verb can clear it (the "zombie"
-        // entry). Discard the whole subtree so state_staged matches the filesystem
-        // instead, the same way a reverted single-file add is discarded below.
+        // (never committed) nor on disk is a reverted, uncommitted add — for
+        // example a nested repository root that was indexed before the boundary
+        // check above existed and has since been removed, together with whatever
+        // of its contents had been pulled into the parent tree. Reporting it as a
+        // `Delete` is meaningless because there is no committed base to delete
+        // from, and no mutation verb can clear it (the "zombie" entry). Discard
+        // the whole subtree so state_staged matches the filesystem instead, the
+        // same way a reverted single-file add is discarded below.
         if ctx.scan_dirty && from_node.node.is_directory() {
             let in_current = current_node_list
                 .children

lore-revision/tests/nested_repository.rs

@@ -0,0 +1,184 @@
+// SPDX-FileCopyrightText: 2026 Epic Games, Inc.
+// SPDX-License-Identifier: MIT
+
+//! Working-tree scan handling of a nested repository — a child directory that
+//! is itself a Lore working copy (it carries its own `.lore/`).
+//!
+//! A nested repository must be treated as an implicit boundary: its contents
+//! belong to the nested repository, not the parent, so the parent scan neither
+//! descends into nor indexes it. A child directory that was indexed before the
+//! boundary existed and is then removed must not leave an unremovable delete
+//! entry behind (the "zombie" entry) — the parent has no committed base it
+//! could be a deletion of, so the stale node is discarded on the next scan.
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::disallowed_methods)] // Test fixture writes; not subject to repository write-token discipline.
+
+    use std::fs::File;
+    use std::io::Write;
+    use std::path::Path;
+    use std::sync::Arc;
+
+    use lore_base::error::NoRemote;
+    use lore_base::runtime::LORE_CONTEXT;
+    use lore_base::runtime::runtime;
+    use lore_base::types::Context;
+    use lore_revision::branch;
+    use lore_revision::filter::FilterMode;
+    use lore_revision::lore::RepositoryId;
+    use lore_revision::repository;
+    use lore_revision::repository::DOT_LORE;
+    use lore_revision::repository::RepositoryContext;
+    use lore_revision::repository::RepositoryFormat;
+    use lore_revision::repository::load_filter;
+    use lore_revision::state;
+    use lore_transport::ProtocolError;
+
+    include!("helper.rs");
+
+    /// Create (or truncate) a read/write file at `path` and write `contents` to
+    /// it, returning the open handle. Panics if the file cannot be created or
+    /// written, since a failed fixture setup invalidates the test.
+    fn create_file(path: &Path, contents: &[u8]) -> File {
+        let mut file = File::options()
+            .create(true)
+            .truncate(true)
+            .read(true)
+            .write(true)
+            .open(path)
+            .unwrap_or_else(|_| panic!("Failed to create test file at {}", path.display()));
+        file.write_all(contents)
+            .unwrap_or_else(|_| panic!("Failed to write test file at {}", path.display()));
+        file
+    }
+
+    /// Build a fresh on-disk repository at `path` with no commits (revision 0)
+    /// and return a write-capable [`RepositoryContext`] for it.
+    async fn create_repository(
+        path: &Path,
+        repository_id: RepositoryId,
+        immutable_store: Arc<dyn lore_storage::ImmutableStore>,
+        mutable_store: Arc<dyn lore_storage::MutableStore>,
+    ) -> Arc<RepositoryContext> {
+        std::fs::create_dir_all(path).expect("Create repository directory failed");
+        let default_branch = Context::from(uuid::Uuid::now_v7());
+        let write_token = repository::RepositoryWriteToken::acquire(path).await;
+        let created_repo = repository::create_local(
+            path,
+            &write_token,
+            repository_id,
+            default_branch,
+            branch::DEFAULT_DEFAULT_NAME.to_string(),
+            repository::RepositoryConfig::default(),
+            false,
+        )
+        .await
+        .expect("Failed to create repository");
+
+        let repository = Arc::new(
+            RepositoryContext::new(
+                Some(path.to_path_buf()),
+                immutable_store,
+                mutable_store,
+                repository_id,
+                created_repo.instance_id,
+                Err(ProtocolError::from(NoRemote)),
+                load_filter(path).expect("Failed to load filter"),
+                RepositoryFormat::Lore,
+            )
+            .with_write_token(write_token.share()),
+        );
+        lore_revision::instance::store_current_anchor_branch(&repository, default_branch)
+            .await
+            .expect("Failed to store anchor branch");
+        repository
+    }
+
+    /// Reconcile the working tree against the staged state, mutating `state_staged`
+    /// in place exactly as `lore status --scan` does, and return the detected
+    /// changes.
+    async fn scan(
+        repository: Arc<RepositoryContext>,
+        state_staged: Arc<state::State>,
+        state_current: Arc<state::State>,
+    ) -> Vec<lore_revision::change::NodeChange> {
+        let (changes, _stats) = state::diff_filesystem_ex(
+            repository.clone(),
+            state_staged,
+            repository,
+            state_current,
+            None, /* full tree */
+            FilterMode::Full,
+            true, /* scan_dirty */
+            Arc::new(Vec::new()),
+        )
+        .await
+        .expect("Failed to diff filesystem");
+        changes
+    }
+
+    /// A child directory carrying its own `.lore/` is a nested repository: the
+    /// parent scan must not index it or pull its contents into the parent tree.
+    #[tokio::test]
+    async fn nested_repository_is_not_indexed() {
+        let (immutable_store, mutable_store, execution) =
+            test_store_create().await.expect("Failed to create stores");
+        let repository_id = RepositoryId::from(uuid::Uuid::now_v7());
+
+        runtime()
+            .spawn(LORE_CONTEXT.scope(execution.clone(), async move {
+                let tempdir = generate_tempdir();
+                let path = tempdir.to_path_buf();
+                let repository = create_repository(
+                    path.as_path(),
+                    repository_id,
+                    immutable_store.clone(),
+                    mutable_store.clone(),
+                )
+                .await;
+
+                // A tracked file in the parent so the scan has real work to do.
+                let _ = create_file(path.join("parent_file.txt").as_path(), &[0, 1, 2, 3]);
+
+                // A nested repository: a child directory with its own `.lore/`
+                // control directory and content that belongs to it, not the parent.
+                std::fs::create_dir(path.join("nested").as_path())
+                    .expect("Create nested directory failed");
+                std::fs::create_dir(path.join("nested").join(DOT_LORE).as_path())
+                    .expect("Create nested/.lore directory failed");
+                let _ = create_file(path.join("nested").join("inner.txt").as_path(), &[9, 9, 9]);
+
+                let (current_revision, _branch) =
+                    lore_revision::instance::load_current_anchor(&repository)
+                        .await
+                        .expect("Failed to load current anchor");
+                let state_current = state::State::deserialize(repository.clone(), current_revision)
+                    .await
+                    .expect("Failed to deserialize current state");
+                let state_staged = state::State::deserialize(repository.clone(), current_revision)
+                    .await
+                    .expect("Failed to deserialize staged state");
+
+                let changes = scan(repository.clone(), state_staged, state_current).await;
+
+                // The parent file is indexed; nothing under the nested repository is.
+                assert!(
+                    changes.iter().any(|c| c.path.as_str() == "parent_file.txt"),
+                    "expected the parent's own file to be indexed"
+                );
+                assert!(
+                    changes
+                        .iter()
+                        .all(|c| !c.path.as_str().starts_with("nested")),
+                    "nested repository contents must not be indexed, found: {:?}",
+                    changes
+                        .iter()
+                        .map(|c| c.path.as_str().to_string())
+                        .collect::<Vec<_>>()
+                );
+            }))
+            .await
+            .expect("Test task panicked");
+    }
+}