Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .claude/skills/sc-cli-reference/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -234,7 +234,9 @@ bash demo/run_merge_ergonomics_demo.sh # sc conflicts/sc resolve proof (P
# conflict both resolved end-to-end with no
# hand-edited markers
cargo run --bin sc -- sparse set <prefix…> [--identity <key>] # narrow the working tree to
# these path prefixes; re-lays disk now (P24)
# these path prefixes; re-lays disk now (P24). Warns per
# prefix that matches no tracked path; at least one
# prefix is required (`sparse disable` is the full view)
cargo run --bin sc -- sparse show [--json] # list the active sparse prefixes ("disabled" if
# the spec is empty/absent) (P24)
cargo run --bin sc -- sparse disable [--identity <key>] # clear the spec and rematerialize
Expand Down
11 changes: 6 additions & 5 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -743,11 +743,12 @@ scale-&-reach horizon):
not a disclosure (an authorized identity produced it), documented in
ADR-0034 — but the sparse view is briefly wider than advertised. Extend
the gate to those write loops.
- **Sparse ergonomics (P24 final-review Minors).** A bogus/no-match
`sc sparse set <prefix>` empties the working tree with no warning
(recoverable via disable); a zero-arg `sc sparse set` silently equals
`disable`; blank lines in a hand-edited `.sc/sparse` want tolerant
parsing. Small usability hardening.
- **Sparse ergonomics (P24 final-review Minors) — shipped.** `sc sparse set`
warns for each prefix that matches no tracked path at HEAD (the tree is still
laid out, empty, and `sc sparse disable` is named as the way back); a bare
`sc sparse set` on a full clone is refused with a pointer to `sc sparse
disable` (a partial clone keeps its `sc backfill` refusal); and `.sc/sparse`
parsing ignores blank lines.
- **Transparent lazy-fetch for partial clones (P27).** `sc backfill` is
explicit-only by design (ADR-0037's "no network in read paths" choice);
the identical filtered-walk/gap infra could instead dial the promisor
Expand Down
24 changes: 24 additions & 0 deletions crates/cli/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1088,9 +1088,33 @@ fn run_sparse(op: SparseOp) -> Result<()> {
}
SparseOp::Set { prefixes, identity } => {
let repo = open_repo()?;
// No prefix is a full checkout, which is what `sparse disable`
// says. A partial clone still reaches the library, whose refusal
// names `sc backfill`.
if prefixes.is_empty() && repo.promisor()?.is_none() {
Comment thread
tonibergholm marked this conversation as resolved.
Resolved
anyhow::bail!(
"no prefix given: `sc sparse set` needs at least one path prefix; \
use `sc sparse disable` for a full checkout"
);
}
let sk = resolve_identity_opt(identity)?;
let skipped = repo.set_sparse(&prefixes, sk.as_ref())?;
println!("sparse set: {} prefix(es)", prefixes.len());
// After the set: a lazy partial clone fills the new view during
// it, so a check before would warn about paths that then arrive.
let partial = repo.promisor()?.is_some();
for p in repo.sparse_prefixes_matching_nothing(&prefixes)? {
let way_back = if partial {
"this is a partial clone: choose a prefix inside what was fetched, or run \
`sc backfill --all` first and then `sc sparse disable`"
} else {
"`sc sparse disable` restores the full checkout"
};
eprintln!(
"warning: prefix {p:?} matches no tracked path at HEAD, so none of it is on \
disk; {way_back}"
);
}
for path in &skipped {
eprintln!("skipped (no key): {path}");
}
Expand Down
74 changes: 74 additions & 0 deletions crates/cli/tests/sparse_ergonomics.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
//! `sc sparse set` usability guards (P24 follow-ons): a prefix that matches
//! nothing is warned about, and a bare `sparse set` points at `sparse disable`.

use std::process::Command;

fn sc(dir: &std::path::Path, args: &[&str]) -> std::process::Output {
Command::new(env!("CARGO_BIN_EXE_sc"))
.args(args)
.current_dir(dir)
.output()
.expect("sc runs")
}

fn stderr(out: &std::process::Output) -> String {
String::from_utf8_lossy(&out.stderr).into_owned()
}

fn repo(tag: &str) -> std::path::PathBuf {
let root =
std::env::temp_dir().join(format!("scl-cli-sparse-ergo-{tag}-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&root);
std::fs::create_dir_all(root.join("src")).unwrap();
std::fs::create_dir_all(root.join("docs")).unwrap();
assert!(sc(&root, &["init"]).status.success());
std::fs::write(root.join("src/a.txt"), "a\n").unwrap();
std::fs::write(root.join("docs/b.txt"), "b\n").unwrap();
assert!(sc(&root, &["commit", "-m", "c1"]).status.success());
root
}

/// A prefix naming nothing empties the tree; the command still succeeds, but
/// says so, and names the way back.
#[test]
fn a_prefix_matching_no_tracked_path_is_warned_about() {
let root = repo("nomatch");
let out = sc(&root, &["sparse", "set", "sorc/"]);
assert!(out.status.success(), "{}", stderr(&out));
let err = stderr(&out);
assert!(err.contains("matches no tracked path"), "{err}");
assert!(err.contains("sc sparse disable"), "{err}");
assert!(!root.join("src/a.txt").exists(), "the view really is empty");

// A real prefix draws no warning, and a mixed set warns only for the miss.
assert!(sc(&root, &["sparse", "disable"]).status.success());
let ok = sc(&root, &["sparse", "set", "src/"]);
assert!(ok.status.success());
assert!(
!stderr(&ok).contains("matches no tracked path"),
"{}",
stderr(&ok)
);
let mixed = sc(&root, &["sparse", "set", "src/", "nope/"]);
assert!(mixed.status.success());
let err = stderr(&mixed);
assert!(err.contains("\"nope/\""), "{err}");
assert!(!err.contains("\"src/\""), "{err}");
std::fs::remove_dir_all(&root).unwrap();
assert!(!root.exists());
}

/// With no prefix `sparse set` was a silent `sparse disable`; it now refuses
/// and says which command means that.
#[test]
fn a_bare_sparse_set_points_at_disable() {
let root = repo("bare");
assert!(sc(&root, &["sparse", "set", "src/"]).status.success());
let out = sc(&root, &["sparse", "set"]);
assert!(!out.status.success(), "a bare `sparse set` must be refused");
let err = stderr(&out);
assert!(err.contains("sc sparse disable"), "{err}");
assert!(!root.join("docs/b.txt").exists(), "nothing was re-laid");
std::fs::remove_dir_all(&root).unwrap();
assert!(!root.exists());
}
188 changes: 187 additions & 1 deletion crates/repo/src/sparse.rs
Original file line number Diff line number Diff line change
Expand Up @@ -89,18 +89,42 @@ fn remove_if_exists(path: &std::path::Path) -> Result<()> {
pub fn load(layout: &Layout) -> Result<Sparse> {
match std::fs::read_to_string(layout.sparse_path()) {
Ok(text) => {
let prefixes = text.lines().map(|l| l.to_string()).collect();
// Blank lines (a hand edit, a trailing newline doubled) name no
// prefix; keep them out of the spec.
// `trim` only decides what is blank: a prefix keeps its bytes.
let prefixes = text
.lines()
.filter(|l| !l.trim().is_empty())
Comment thread
tonibergholm marked this conversation as resolved.
Resolved
.map(String::from)
.collect();
Ok(Sparse { prefixes })
}
Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(Sparse::default()),
Err(e) => Err(e.into()),
}
}

/// Refuse a blank prefix (empty or whitespace-only). It would be persisted as a
/// blank line, which `load` reads back as no prefix at all: a laid-out empty
/// view would turn into a full checkout on the next process, and every absent
/// file would then read as a deletion. No prefix at all (an empty list) is the
/// one spelling of a full view and is accepted.
pub(crate) fn validate_prefixes(prefixes: &[String]) -> Result<()> {
match prefixes.iter().find(|p| p.trim().is_empty()) {
Some(p) => Err(crate::error::Error::InvalidArgument(format!(
"empty sparse prefix {p:?}; name a path, or use `sc sparse disable` for a full checkout"
))),
None => Ok(()),
}
}

/// Persist the repo's sparse spec, atomically. An empty spec removes the
/// file entirely rather than writing an empty one, so `load` sees the same
/// "no sparseness" state whether the file was never written or was cleared.
pub fn store(layout: &Layout, s: &Sparse) -> Result<()> {
// The shared persistence boundary: a blank prefix would become a blank
// line that `load` reads back as no prefix.
validate_prefixes(&s.prefixes)?;
if s.prefixes.is_empty() {
return remove_if_exists(&layout.sparse_path());
}
Expand Down Expand Up @@ -158,6 +182,35 @@ pub fn clear(layout: &Layout) -> Result<()> {
remove_if_exists(&layout.sparse_path())
}

/// Whether the path `bare` (no trailing slash) exists in the tree at `root`,
/// as a file or a directory: `Some(true)`/`Some(false)`, or `None` when a tree
/// on the way is not held (a partial clone's gap), which is not an answer.
fn prefix_present(
store: &mut scl_core::Store,
root: scl_core::ObjectId,
bare: &str,
) -> Option<bool> {
// Literal components, as `Sparse::matches` reads the prefix: a leading
// slash or a doubled one names nothing, it is not skipped.
let comps: Vec<&str> = bare.split('/').collect();
let mut cur = root;
for (i, comp) in comps.iter().enumerate() {
if !store.contains(&cur) {
return None;
}
let tree = store.get_tree(&cur).ok()?;
let Some(e) = tree.get(comp) else {
return Some(false);
};
let last = i + 1 == comps.len();
match e.kind {
scl_core::EntryKind::Tree if !last => cur = e.id,
_ => return Some(last),
}
}
Some(true)
}

impl Repo {
/// The repo's current sparse-checkout spec (thin wrapper over `load`).
pub fn sparse_spec(&self) -> Result<Sparse> {
Expand Down Expand Up @@ -188,6 +241,8 @@ impl Repo {
identity: Option<&scl_crypto::SecretKey>,
) -> Result<Vec<String>> {
self.refuse_on_private("sc sparse set")?;
// Before any side effect (the shared `store` checks again).
validate_prefixes(prefixes)?;
if crate::merge_state::in_progress(&self.layout) {
return Err(Error::MergeInProgress);
}
Expand Down Expand Up @@ -303,6 +358,28 @@ impl Repo {
Ok(skipped)
}

/// The prefixes in `prefixes` that match no tracked path at HEAD, so a
/// typo or a path that does not exist is not silently taken for a narrow
/// view that happens to be empty. Each prefix is one path-directed lookup
/// (depth, not tree size). A prefix whose answer needs an object this
/// partial clone does not hold is left out: the report is advice, never a
/// refusal, and never a guess. An unborn HEAD has no paths and reports
/// nothing; a private branch refuses, as `sparse set` does.
pub fn sparse_prefixes_matching_nothing(&self, prefixes: &[String]) -> Result<Vec<String>> {
self.refuse_on_private("sc sparse set")?;
let Some(tip) = self.head_tip()? else {
return Ok(Vec::new());
};
let root = self.snapshot(&tip)?.root;
Comment thread
tonibergholm marked this conversation as resolved.
Resolved
let store_arc = self.vfs().store();
let mut store = store_arc.lock().unwrap();
Ok(prefixes
.iter()
.filter(|p| prefix_present(&mut store, root, p.trim_end_matches('/')) == Some(false))
.cloned()
.collect())
}

/// Disable sparse checkout: clear the persisted spec and re-materialize
/// HEAD's tree in full, restoring every previously-excluded file to disk.
/// An unborn HEAD has no working tree to re-lay; the spec is still
Expand Down Expand Up @@ -698,4 +775,113 @@ mod tests {
std::fs::remove_dir_all(&src_root).unwrap();
std::fs::remove_dir_all(&dst_root).unwrap();
}

#[test]
fn load_ignores_blank_lines_in_a_hand_edited_spec() {
let layout = tmp_layout("blank-lines");
std::fs::write(layout.sparse_path(), "src/\n\n \ndocs/\n\n").unwrap();
let spec = load(&layout).unwrap();
assert_eq!(spec.prefixes(), ["src/", "docs/"]);
assert!(
!spec.matches("lib/x.txt"),
"a blank line must not widen the view"
);

// A nonblank prefix is kept byte for byte, significant whitespace
// included, across a store/load round trip.
let odd = Sparse::new(vec![" lead/".to_string(), "trail /".to_string()]);
store(&layout, &odd).unwrap();
assert_eq!(load(&layout).unwrap().prefixes(), odd.prefixes());
std::fs::remove_dir_all(&layout.root).unwrap();
}

#[test]
fn set_sparse_refuses_a_blank_prefix_and_leaves_the_tree_alone() {
let root =
std::env::temp_dir().join(format!("scl-sparse-blank-prefix-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&root);
std::fs::create_dir_all(root.join("src")).unwrap();
let repo = Repo::init(&root).unwrap();
std::fs::write(root.join("src/a.txt"), b"a\n").unwrap();
repo.commit("t", "c1").unwrap();
for bad in ["", " "] {
let err = repo.set_sparse(&[bad.to_string()], None).unwrap_err();
assert!(
matches!(&err, Error::InvalidArgument(m) if m.contains("empty sparse prefix")),
"got {err:?}"
);
}
assert!(root.join("src/a.txt").exists(), "nothing was removed");
assert!(
repo.sparse_spec().unwrap().is_full(),
"the spec is untouched"
);
drop(repo);
std::fs::remove_dir_all(&root).unwrap();
assert!(!root.exists());
}

#[test]
fn prefixes_matching_nothing_is_a_path_lookup() {
let root = std::env::temp_dir().join(format!("scl-sparse-nomatch-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&root);
std::fs::create_dir_all(root.join("src/deep")).unwrap();
let repo = Repo::init(&root).unwrap();
std::fs::write(root.join("src/deep/a.txt"), b"a\n").unwrap();
std::fs::write(root.join("top.txt"), b"t\n").unwrap();
repo.commit("t", "c1").unwrap();
let ask = |ps: &[&str]| {
let ps: Vec<String> = ps.iter().map(|p| p.to_string()).collect();
repo.sparse_prefixes_matching_nothing(&ps).unwrap()
};
assert!(ask(&["src/", "src/deep", "top.txt", "src/deep/a.txt"]).is_empty());
assert_eq!(
ask(&["sorc/", "src/nope", "top.txt/x", "src/deep/a.txt/y"]).len(),
4
);
// Literal, like `Sparse::matches`: a leading or doubled slash names
// nothing, so these are reported rather than read as `src/`.
let odd = ask(&["/src/", "src//deep", "/"]);
assert_eq!(odd.len(), 3, "got {odd:?}");
drop(repo);
std::fs::remove_dir_all(&root).unwrap();
assert!(!root.exists());
}

#[test]
fn a_blank_clone_filter_is_refused_before_anything_is_created() {
let src = std::env::temp_dir().join(format!("scl-blank-filter-src-{}", std::process::id()));
let dst = std::env::temp_dir().join(format!("scl-blank-filter-dst-{}", std::process::id()));
for r in [&src, &dst] {
let _ = std::fs::remove_dir_all(r);
}
std::fs::create_dir_all(&src).unwrap();
let origin = Repo::init(&src).unwrap();
std::fs::write(src.join("a.txt"), b"a\n").unwrap();
origin.commit("t", "c1").unwrap();
for bad in ["", " "] {
let Err(err) =
Repo::clone_url_filtered(src.to_str().unwrap(), &dst, Some(&[bad.to_string()]))
else {
panic!("a blank clone filter must be refused");
};
assert!(
matches!(&err, Error::InvalidArgument(m) if m.contains("empty sparse prefix")),
"got {err:?}"
);
assert!(!dst.exists(), "no clone directory may be left behind");
}
drop(origin);
std::fs::remove_dir_all(&src).unwrap();
assert!(!src.exists());
}

#[test]
fn store_refuses_a_blank_prefix() {
let layout = tmp_layout("store-blank");
let err = store(&layout, &Sparse::new(vec!["src/".into(), " ".into()])).unwrap_err();
assert!(matches!(&err, Error::InvalidArgument(_)), "got {err:?}");
assert!(!layout.sparse_path().exists(), "nothing was written");
std::fs::remove_dir_all(&layout.root).unwrap();
}
}
5 changes: 5 additions & 0 deletions crates/repo/src/sync.rs
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,11 @@ impl Repo {
dst: impl AsRef<Path>,
filter: Option<&[String]>,
) -> Result<Repo> {
// Before the network or the destination directory: a blank prefix
// would be persisted as a sparse line that reloads as a full view.
if let Some(f) = filter {
crate::sparse::validate_prefixes(f)?;
}
let transport = open_transport(src_url)?;
let remote_refs = transport.list_refs()?;
let head_branch = transport.head_branch()?;
Expand Down
Loading