Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat: support ignoring certain files in the multi-version management function, similar to the git ignore feature (#2930)
Haoyu Zhang17631bd353ae
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rsindex 3efbd7c1d..c72be25c5 100644--- a/crates/ov_cli/src/client.rs+++ b/crates/ov_cli/src/client.rs@@ -1566,12 +1566,24 @@ impl HttpClient {self.get("/api/v1/snapshot/log", ¶ms).await}+ pub async fn snapshot_ignore_get(&self) -> Result<Value> {+ self.get("/api/v1/snapshot/ignore", &[]).await+ }++ pub async fn snapshot_ignore_set(&self, content: &str) -> Result<Value> {+ self.put("/api/v1/snapshot/ignore", &serde_json::json!({ "content": content }))+ .await+ }++ pub async fn snapshot_ignore_delete(&self) -> Result<Value> {+ self.delete("/api/v1/snapshot/ignore", &[]).await+ }+pub async fn snapshot_show(&self,target_ref: &str,path: Option<&str>,- ) -> Result<SnapshotShowResult> {- let url = format!("{}/api/v1/snapshot/show", self.base.base_url);+ ) -> Result<SnapshotShowResult> { let url = format!("{}/api/v1/snapshot/show", self.base.base_url);let mut query: Vec<(String, String)> = vec![("target_ref".to_string(), target_ref.to_string())];if let Some(p) = path {query.push(("path".to_string(), p.to_string()));diff --git a/crates/ov_cli/src/commands/snapshot.rs b/crates/ov_cli/src/commands/snapshot.rsindex 15297032b..fbb55da37 100644--- a/crates/ov_cli/src/commands/snapshot.rs+++ b/crates/ov_cli/src/commands/snapshot.rs@@ -68,7 +68,50 @@ pub async fn dispatch(print_log(&value, output_format, compact);Ok(())}+ SnapshotCmd::IgnoreGet => {+ let value = client.snapshot_ignore_get().await?;+ print_ignore_get(&value, output_format, compact);+ Ok(())+ }+ SnapshotCmd::IgnoreSet { content, file } => {+ let content = resolve_ignore_content(content.as_deref(), file.as_deref())?;+ client.snapshot_ignore_set(&content).await?;+ output_success(&json!({ "result": "set" }), output_format, compact);+ Ok(())+ }+ SnapshotCmd::IgnoreDelete => {+ client.snapshot_ignore_delete().await?;+ output_success(&json!({ "result": "deleted" }), output_format, compact);+ Ok(())+ }+ }+}++/// Resolve `.ovgitignore` content: `--file` takes precedence over `--content`;+/// if neither is given, the content is left empty (clears the rules).+fn resolve_ignore_content(+ content: Option<&str>,+ file: Option<&std::path::Path>,+) -> Result<String> {+ if let Some(path) = file {+ use std::io::Read;+ let mut buf = String::new();+ std::fs::File::open(path)?.read_to_string(&mut buf)?;+ return Ok(buf);+ }+ Ok(content.unwrap_or("").to_string())+}++fn print_ignore_get(value: &Value, output_format: OutputFormat, compact: bool) {+ if matches!(output_format, OutputFormat::Json) {+ output_success(value, output_format, compact);+ return;}+ // Plain mode: print the raw content verbatim so it can be redirected to a file.+ let content = value.as_str().unwrap_or("");+ let mut stdout = std::io::stdout();+ let _ = stdout.write_all(content.as_bytes());+ let _ = stdout.flush();}fn print_commit(value: &Value, output_format: OutputFormat, compact: bool) {diff --git a/crates/ov_cli/src/help_ui.rs b/crates/ov_cli/src/help_ui.rsindex a45f90594..0690672ae 100644--- a/crates/ov_cli/src/help_ui.rs+++ b/crates/ov_cli/src/help_ui.rs@@ -68,6 +68,7 @@ const CORE_WORKFLOW: &[HelpCommand] = help_commands!["read","write","add-memory",+ "set-tags",];const FILESYSTEM: &[HelpCommand] =@@ -412,6 +413,24 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[},],},+ CommandHelpSpec {+ path: &["set-tags"],+ purpose: "Update explicit retrieval tags for a file or directory.",+ examples: &[+ HelpItem {+ label: "ov set-tags viking://resources/proj --tags env=prod,team=search",+ description: "Replace tags on a directory.",+ },+ HelpItem {+ label: "ov set-tags viking://resources/proj --tags env=staging --mode append",+ description: "Append (merge) tags without dropping existing keys.",+ },+ ],+ next_steps: &[HelpItem {+ label: "ov find \"query\" -u <uri>",+ description: "Verify the tags influence retrieval.",+ }],+ },CommandHelpSpec {path: &["get"],purpose: "Download a file resource to a local path.",@@ -602,6 +621,54 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[description: "Inspect a commit from the log.",}],},+ CommandHelpSpec {+ path: &["snapshot", "ignore-get"],+ purpose: "Show the account-level .ovgitignore content.",+ examples: &[+ HelpItem {+ label: "ov snapshot ignore-get",+ description: "Print the .ovgitignore content to stdout.",+ },+ HelpItem {+ label: "ov snapshot ignore-get -o json",+ description: "Return the content wrapped in the standard JSON envelope.",+ },+ ],+ next_steps: &[HelpItem {+ label: "ov snapshot ignore-set --content \"*.log\"",+ description: "Update the ignore rules.",+ }],+ },+ CommandHelpSpec {+ path: &["snapshot", "ignore-set"],+ purpose: "Set the account-level .ovgitignore content (overwrites).",+ examples: &[+ HelpItem {+ label: "ov snapshot ignore-set --content \"*.log\"",+ description: "Ignore all .log files from future commits.",+ },+ HelpItem {+ label: "ov snapshot ignore-set --file ./my-rules",+ description: "Read the content from a file (--file takes precedence over --content).",+ },+ ],+ next_steps: &[HelpItem {+ label: "ov snapshot commit -m \"with ignore\"",+ description: "Commit; matching files are excluded (see the `ignored` count).",+ }],+ },+ CommandHelpSpec {+ path: &["snapshot", "ignore-delete"],+ purpose: "Delete the account-level .ovgitignore file (idempotent).",+ examples: &[HelpItem {+ label: "ov snapshot ignore-delete",+ description: "Remove the ignore rules; missing is success.",+ }],+ next_steps: &[HelpItem {+ label: "ov snapshot ignore-get",+ description: "Confirm the rules are gone (returns an empty string).",+ }],+ },CommandHelpSpec {path: &["add-memory"],purpose: "Add a memory directly from text or JSON messages.",diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rsindex 42d830bf4..36b9f9a16 100644--- a/crates/ov_cli/src/main.rs+++ b/crates/ov_cli/src/main.rs@@ -1109,6 +1109,19 @@ pub(crate) enum SnapshotCmd {#[arg(long, default_value_t = 20)]limit: u32,},+ /// Get the account .ovgitignore content+ IgnoreGet,+ /// Set the account .ovgitignore content+ IgnoreSet {+ /// .ovgitignore content passed inline+ #[arg(long = "content")]+ content: Option<String>,+ /// File to read the content from; takes precedence over --content+ #[arg(long = "file")]+ file: Option<std::path::PathBuf>,+ },+ /// Delete the account .ovgitignore+ IgnoreDelete,}#[derive(Subcommand)]diff --git a/crates/ragfs-python/src/git.rs b/crates/ragfs-python/src/git.rsindex 5c1ae32bd..b84095403 100644--- a/crates/ragfs-python/src/git.rs+++ b/crates/ragfs-python/src/git.rs@@ -178,6 +178,8 @@ pub fn map_git_error(py: Python<'_>, e: ragfs::git::GitError) -> PyErr {GitError::InvalidPath(_) => new_py_err_pub(py, "AGFSInvalidPathError", msg),GitError::BlobTooLarge { .. } => new_py_err_pub(py, "AGFSInvalidOperationError", msg),GitError::TooManyFiles { .. } => new_py_err_pub(py, "AGFSInvalidOperationError", msg),+ GitError::IgnoreFileTooLarge { .. } => new_py_err_pub(py, "AGFSInvalidOperationError", msg),+ GitError::InvalidIgnoreFile { .. } => new_py_err_pub(py, "AGFSInvalidOperationError", msg),GitError::CorruptedObject(_) => new_py_err_pub(py, "AGFSInternalError", msg),GitError::RefStore(RefStoreError::NotFound(_)) => {new_py_err_pub(py, "AGFSNotFoundError", msg)@@ -357,14 +359,20 @@ pub fn commit_response_to_pydict(py: Python<'_>, resp: CommitResponse) -> PyResuCommitResponse::Created {commit_oid,changed,+ ignored,} => {d.set_item("result", "created")?;d.set_item("commit_oid", oid_hex(&commit_oid))?;d.set_item("changed", changed)?;+ d.set_item("ignored", ignored)?;}- CommitResponse::Noop { commit_oid } => {+ CommitResponse::Noop {+ commit_oid,+ ignored,+ } => {d.set_item("result", "noop")?;d.set_item("commit_oid", oid_hex(&commit_oid))?;+ d.set_item("ignored", ignored)?;}}Ok(d.into_any().unbind())@@ -753,14 +761,15 @@ mod tests {let oid = gix_hash::ObjectId::null(gix_hash::Kind::Sha1);let resp = ragfs::git::CommitResponse::Created {commit_oid: oid,- changed: 3,+ changed: 2,+ ignored: 3,};let obj = commit_response_to_pydict(py, resp).expect("converts");- let d: &Bound<PyDict> = obj.bind(py).downcast().unwrap();- let result: String = d.get_item("result").unwrap().unwrap().extract().unwrap();- assert_eq!(result, "created");- let changed: usize = d.get_item("changed").unwrap().unwrap().extract().unwrap();- assert_eq!(changed, 3);+ let d = obj.bind(py).downcast::<PyDict>().unwrap();+ assert_eq!(d.get_item("result").unwrap().unwrap().extract::<String>().unwrap(), "created");+ assert_eq!(d.get_item("commit_oid").unwrap().unwrap().extract::<String>().unwrap(), oid.to_hex().to_string());+ assert_eq!(d.get_item("changed").unwrap().unwrap().extract::<usize>().unwrap(), 2);+ assert_eq!(d.get_item("ignored").unwrap().unwrap().extract::<usize>().unwrap(), 3);});}@@ -769,11 +778,15 @@ mod tests {pyo3::prepare_freethreaded_python();Python::attach(|py| {let oid = gix_hash::ObjectId::null(gix_hash::Kind::Sha1);- let resp = ragfs::git::CommitResponse::Noop { commit_oid: oid };+ let resp = ragfs::git::CommitResponse::Noop {+ commit_oid: oid,+ ignored: 4,+ };let obj = commit_response_to_pydict(py, resp).expect("converts");- let d: &Bound<PyDict> = obj.bind(py).downcast().unwrap();- let result: String = d.get_item("result").unwrap().unwrap().extract().unwrap();- assert_eq!(result, "noop");+ let d = obj.bind(py).downcast::<PyDict>().unwrap();+ assert_eq!(d.get_item("result").unwrap().unwrap().extract::<String>().unwrap(), "noop");+ assert_eq!(d.get_item("commit_oid").unwrap().unwrap().extract::<String>().unwrap(), oid.to_hex().to_string());+ assert_eq!(d.get_item("ignored").unwrap().unwrap().extract::<usize>().unwrap(), 4);});}diff --git a/crates/ragfs/src/git/error.rs b/crates/ragfs/src/git/error.rsindex 12bd8b8b2..a8895e472 100644--- a/crates/ragfs/src/git/error.rs+++ b/crates/ragfs/src/git/error.rs@@ -134,6 +134,26 @@ pub enum GitError {#[error("too many files: {count} exceeds limit {limit}")]TooManyFiles { count: usize, limit: usize },+ /// `.ovgitignore` exceeds the configured size limit.+ #[error("ignore file too large: {path} is {size} bytes, limit {max} bytes")]+ IgnoreFileTooLarge {+ /// Account-relative path of the offending file.+ path: String,+ /// Observed size in bytes.+ size: u64,+ /// Configured maximum size in bytes.+ max: u64,+ },++ /// `.ovgitignore` is syntactically invalid or cannot be decoded.+ #[error("invalid ignore file {path}: {reason}")]+ InvalidIgnoreFile {+ /// Account-relative path of the offending file.+ path: String,+ /// Human-readable explanation of why parsing failed.+ reason: String,+ },+/// Feature not enabled#[error("git feature not enabled")]FeatureDisabled,diff --git a/crates/ragfs/src/git/ignore.rs b/crates/ragfs/src/git/ignore.rsnew file mode 100644index 000000000..71dc68de0--- /dev/null+++ b/crates/ragfs/src/git/ignore.rs@@ -0,0 +1,251 @@+//! Account-level `.ovgitignore` parsing and matching.+//!+//! The syntax is a documented OpenViking subset of root `.gitignore` rules.+//! It intentionally rejects negation so callers do not assume full Git index+//! semantics.++use std::path::Path;++use ignore::gitignore::{Gitignore, GitignoreBuilder};++use crate::git::error::GitError;++/// Account-relative tree path of the control file.+pub const OVGITIGNORE_PATH: &str = ".ovgitignore";++/// Hard size cap on the ignore file, in bytes.+pub const OVGITIGNORE_MAX_BYTES: usize = 64 * 1024;++/// Compiled, account-level `.ovgitignore` rule set.+///+/// Holds `None` when the file is absent or contains no effective rules, in+/// which case [`IgnoreMatcher::is_ignored`] always returns `false`.+#[derive(Debug, Clone)]+pub struct IgnoreMatcher {+ inner: Option<Gitignore>,+}++impl Default for IgnoreMatcher {+ fn default() -> Self {+ Self::empty()+ }+}++impl IgnoreMatcher {+ /// Construct a matcher that ignores nothing.+ pub fn empty() -> Self {+ Self { inner: None }+ }++ /// Parse `.ovgitignore` bytes into a matcher.+ ///+ /// Enforces the documented subset: UTF-8 text within+ /// [`OVGITIGNORE_MAX_BYTES`], no `!` negation, and no Git-style escaping+ /// (a backslash is rejected rather than silently reinterpreted by the+ /// underlying matcher). Comments (`#`) and blank lines are skipped;+ /// leading/trailing whitespace is trimmed per the spec.+ pub fn parse(bytes: &[u8]) -> Result<Self, GitError> {+ if bytes.len() > OVGITIGNORE_MAX_BYTES {+ return Err(GitError::IgnoreFileTooLarge {+ path: OVGITIGNORE_PATH.to_string(),+ size: bytes.len() as u64,+ max: OVGITIGNORE_MAX_BYTES as u64,+ });+ }++ let text = std::str::from_utf8(bytes).map_err(|e| GitError::InvalidIgnoreFile {+ path: OVGITIGNORE_PATH.to_string(),+ reason: format!("must be UTF-8: {e}"),+ })?;++ let mut builder = GitignoreBuilder::new(Path::new(""));+ let mut added = false;+ for (idx, raw) in text.lines().enumerate() {+ let line = raw.trim();+ if line.is_empty() || line.starts_with('#') {+ continue;+ }+ if line.starts_with('!') {+ return Err(GitError::InvalidIgnoreFile {+ path: OVGITIGNORE_PATH.to_string(),+ reason: format!(+ "line {} uses unsupported negation: {}",+ idx + 1,+ line+ ),+ });+ }+ // Git-style escaping is unsupported by this subset. Reject it up+ // front with a clear error rather than letting the underlying+ // matcher silently reinterpret `\x` (e.g. `foo\bar` -> `foobar`)+ // or fail on an incomplete trailing escape (`foo\`).+ if line.contains('\\') {+ return Err(GitError::InvalidIgnoreFile {+ path: OVGITIGNORE_PATH.to_string(),+ reason: format!(+ "line {} uses unsupported escaping: {}",+ idx + 1,+ line+ ),+ });+ }+ builder.add_line(Some(OVGITIGNORE_PATH.into()), line).map_err(|e| {+ GitError::InvalidIgnoreFile {+ path: OVGITIGNORE_PATH.to_string(),+ reason: format!("line {} is invalid: {e}", idx + 1),+ }+ })?;+ added = true;+ }++ if !added {+ return Ok(Self::empty());+ }++ let inner = builder.build().map_err(|e| GitError::InvalidIgnoreFile {+ path: OVGITIGNORE_PATH.to_string(),+ reason: e.to_string(),+ })?;+ Ok(Self { inner: Some(inner) })+ }++ /// Whether `rel_path` (account-relative, `/`-separated) is excluded.+ ///+ /// `is_dir` must reflect whether `rel_path` is a directory: directory-only+ /// patterns such as `build/` only match a path that is itself a directory.+ /// Pass `false` for file paths (the common commit case, where enumeration+ /// only yields files). The `.ovgitignore` file itself is never ignored.+ pub fn is_ignored(&self, rel_path: &str, is_dir: bool) -> bool {+ let Some(inner) = &self.inner else {+ return false;+ };+ let cleaned = rel_path.trim_matches('/');+ if cleaned.is_empty() || cleaned == OVGITIGNORE_PATH {+ return false;+ }+ inner+ .matched_path_or_any_parents(Path::new(cleaned), is_dir)+ .is_ignore()+ }+}++/// Whether `rel_path` should be included in a commit snapshot.+///+/// Combines the hardcoded system pruning ([`crate::git::enumerate::prune_path`])+/// with the account `.ovgitignore` rules. `rel_path` is treated as a file+/// (`is_dir = false`), which matches the commit flow — enumeration only+/// yields file paths. The `.ovgitignore` file is always tracked.+pub fn should_track_path(rel_path: &str, matcher: &IgnoreMatcher) -> bool {+ if rel_path == OVGITIGNORE_PATH {+ return true;+ }+ !crate::git::enumerate::prune_path(rel_path) && !matcher.is_ignored(rel_path, false)+}++#[cfg(test)]+mod tests {+ use super::*;++ fn matcher(src: &str) -> IgnoreMatcher {+ IgnoreMatcher::parse(src.as_bytes()).expect("ignore file parses")+ }++ #[test]+ fn empty_comments_and_blank_lines_match_nothing() {+ let m = matcher("\n \n# comment\n # indented comment\n");+ assert!(!m.is_ignored("resources/a.log", false));+ assert!(should_track_path("resources/a.log", &m));+ }++ #[test]+ fn basename_glob_matches_at_any_depth() {+ let m = matcher("*.log\n");+ assert!(m.is_ignored("resources/a.log", false));+ assert!(m.is_ignored("resources/proj/nested/a.log", false));+ assert!(!m.is_ignored("resources/a.md", false));+ }++ #[test]+ fn double_star_glob_matches_nested_paths() {+ let m = matcher("**/*.bak\n");+ assert!(m.is_ignored("a.bak", false));+ assert!(m.is_ignored("resources/proj/a.bak", false));+ assert!(!m.is_ignored("resources/proj/a.md", false));+ }++ #[test]+ fn root_relative_patterns_match_from_account_root() {+ let m = matcher("resources/tmp/**\n/resources/cache/**\n");+ assert!(m.is_ignored("resources/tmp/a.txt", false));+ assert!(m.is_ignored("resources/tmp/nested/a.txt", false));+ assert!(m.is_ignored("resources/cache/a.txt", false));+ assert!(!m.is_ignored("user/default/resources/tmp/a.txt", false));+ }++ #[test]+ fn directory_patterns_match_directory_contents() {+ let m = matcher("tmp/\n/cache/\n");+ assert!(m.is_ignored("resources/tmp/a.txt", false));+ assert!(m.is_ignored("tmp/a.txt", false));+ assert!(m.is_ignored("cache/a.txt", false));+ assert!(!m.is_ignored("resources/cache/a.txt", false));+ }++ #[test]+ fn ovgitignore_is_always_tracked() {+ let m = matcher("*\n.ovgitignore\n");+ assert!(m.is_ignored("resources/a.md", false));+ assert!(should_track_path(OVGITIGNORE_PATH, &m));+ }++ #[test]+ fn system_prune_still_wins() {+ let m = IgnoreMatcher::empty();+ assert!(!should_track_path("_system/state.json", &m));+ assert!(!should_track_path("resources/index.faiss", &m));+ assert!(!should_track_path("resources/embedding_cache/a.bin", &m));+ }++ #[test]+ fn negation_is_rejected() {+ let err = IgnoreMatcher::parse(b"!keep.log\n").unwrap_err();+ assert!(matches!(err, GitError::InvalidIgnoreFile { .. }));+ assert!(err.to_string().contains("negation"));+ }++ #[test]+ fn non_utf8_is_rejected() {+ let err = IgnoreMatcher::parse(&[0xff, 0xfe]).unwrap_err();+ assert!(matches!(err, GitError::InvalidIgnoreFile { .. }));+ assert!(err.to_string().contains("UTF-8"));+ }++ #[test]+ fn oversized_file_is_rejected() {+ let bytes = vec![b'a'; OVGITIGNORE_MAX_BYTES + 1];+ let err = IgnoreMatcher::parse(&bytes).unwrap_err();+ assert!(matches!(err, GitError::IgnoreFileTooLarge { .. }));+ }++ #[test]+ fn git_style_escaping_is_rejected() {+ // `\` is unsupported by the documented subset; reject up front rather+ // than letting the matcher silently reinterpret it.+ for src in [b"foo\\bar\n".as_slice(), b"keep\\\n"] {+ let err = IgnoreMatcher::parse(src).unwrap_err();+ assert!(matches!(err, GitError::InvalidIgnoreFile { .. }));+ assert!(err.to_string().contains("escaping"), "src={:?}", src);+ }+ }++ #[test]+ fn directory_pattern_needs_is_dir_to_match_the_dir_itself() {+ // `build/` is a directory-only pattern: it matches files *inside*+ // `build/` regardless of is_dir, but the directory path `build`+ // itself only matches when is_dir is true.+ let m = matcher("build/\n");+ assert!(m.is_ignored("build/output.o", false));+ assert!(!m.is_ignored("build", false));+ assert!(m.is_ignored("build", true));+ }+}diff --git a/crates/ragfs/src/git/mod.rs b/crates/ragfs/src/git/mod.rsindex e127f8456..cabbbe771 100644--- a/crates/ragfs/src/git/mod.rs+++ b/crates/ragfs/src/git/mod.rs@@ -31,6 +31,7 @@ pub mod commit;pub mod config;pub mod enumerate;pub mod error;+pub mod ignore;pub mod index_store;pub mod object_store;pub mod ref_store;@@ -41,6 +42,7 @@ pub mod util;pub use config::{GitConfig, GitLocalConfig, GitS3ConfigPy, GitTuningConfig};pub use error::{GitError, ObjectStoreError, RefStoreError};+pub use ignore::{should_track_path, IgnoreMatcher, OVGITIGNORE_MAX_BYTES, OVGITIGNORE_PATH};pub use index_store::{CommitIndex, IndexStore, IndexStoreError};pub use object_store::ObjectStore;pub use ref_store::RefStore;diff --git a/crates/ragfs/src/git/service.rs b/crates/ragfs/src/git/service.rsindex e0bfd29c3..269c70cb3 100644--- a/crates/ragfs/src/git/service.rs+++ b/crates/ragfs/src/git/service.rs@@ -23,6 +23,7 @@ use crate::core::filesystem::FileSystem;use crate::core::types::FileInfo;use crate::git::{error::{GitError, ObjectStoreError, RefStoreError},+ ignore::{should_track_path, IgnoreMatcher, OVGITIGNORE_PATH},index_store::{CommitIndex, IndexStore},object_store::ObjectStore,ref_store::RefStore,@@ -138,6 +139,34 @@ impl GitService {}let ref_name = format!("refs/heads/{branch}");+ // Load ignore matcher and initialize counters.+ //+ // `credited_ignored` / `credited_removed` deduplicate counting across+ // the per-path iterations of a scoped commit: a path listed twice, or+ // listed both as a directory and as a file under it, is processed by+ // multiple iterations but must be credited at most once to `ignored`+ // (on-disk skip) and once to `changed` (snapshot removal). The tree+ // itself is already correct — `editor.remove` is idempotent and the+ // BTreeSet dedups candidates — only the reported counts need guarding.+ let ignore_matcher = load_ignore_matcher(&self.vfs, &account).await?;+ let mut ignored = 0usize;+ let mut changed = 0usize;+ let mut credited_ignored: HashSet<String> = HashSet::new();+ let mut credited_removed: HashSet<String> = HashSet::new();++ let mut include_path = |path: &str| -> bool {+ if crate::git::enumerate::prune_path(path) {+ return false;+ }+ if !should_track_path(path, &ignore_matcher) {+ if credited_ignored.insert(path.to_string()) {+ ignored += 1;+ }+ return false;+ }+ true+ };+// 1. Resolve current HEAD (may not exist → root commit).let prev_head: Option<ObjectId> = match self.ref_store.read(&account, &ref_name).await {Ok(oid) => Some(oid),@@ -229,7 +258,9 @@ impl GitService {crate::git::enumerate::collect_under(&self.vfs, &account, p).await?;for rel in listed {- set.insert(rel);+ if include_path(&rel) {+ set.insert(rel);+ }}if let Some(t) = prev_tree {@@ -246,19 +277,72 @@ impl GitService {}let pref = format!("{}/", p);for (path, _) in prev_paths_cache.as_ref().unwrap() {- if path.starts_with(&pref)- && !crate::git::enumerate::prune_path(path)- {+ if !path.starts_with(&pref) {+ continue;+ }+ if should_track_path(path, &ignore_matcher) {set.insert(path.clone());+ } else {+ // Previously tracked under this scope but+ // now ignored/pruned: drop it from the+ // snapshot. Every entry here came from+ // prev_tree, so the removal is a real+ // change. Use should_track_path (not+ // include_path) so `ignored` is not+ // double-counted for paths that are also+ // on disk — the on-disk pass already+ // counted them.+ editor+ .remove(self.object_store.as_ref(), &account, path)+ .await?;+ if credited_removed.insert(path.clone()) {+ changed += 1;+ }}}}}Ok(_) => {- // File: take it verbatim, subject to pruning.+ // File: take it verbatim, subject to pruning and ignore.cleanup_exact.insert(p.clone());- if !crate::git::enumerate::prune_path(p) {+ if include_path(p) {set.insert(p.clone());+ } else if let Some(t) = prev_tree {+ // Explicit file is now ignored/pruned: drop it+ // from the snapshot if it was previously tracked.+ // Only counts as a change when it actually existed+ // in prev_tree — TreeEditor::remove silently+ // no-ops for missing paths (mirrors the main+ // loop's NotFound branch below).+ //+ // Reuse the already-flattened prev_paths_cache+ // (loading it once on first need) instead of a+ // per-file root-to-leaf `lookup` tree walk, so+ // a scoped commit listing many now-ignored+ // explicit files pays one flatten + O(1) probes+ // rather than K independent walks.+ if prev_paths_cache.is_none() {+ prev_paths_cache = Some(+ crate::git::tree_builder::flatten(+ self.object_store.as_ref(),+ &account,+ t,+ &None,+ )+ .await?,+ );+ }+ let was_tracked = prev_paths_cache+ .as_ref()+ .unwrap()+ .iter()+ .any(|(pp, _)| pp == p);+ if was_tracked && credited_removed.insert(p.clone()) {+ editor+ .remove(self.object_store.as_ref(), &account, p)+ .await?;+ changed += 1;+ }}}Err(e) if is_not_found(&e) => {@@ -276,8 +360,39 @@ impl GitService {cleanup_exact.insert(p.clone());cleanup_prefixes.push(format!("{}/", p));- if !crate::git::enumerate::prune_path(p) {+ if include_path(p) {set.insert(p.clone());+ } else if let Some(t) = prev_tree {+ // `p` is gone from disk AND now ignored/pruned, so+ // it never enters the candidate set (the main+ // loop's NotFound branch won't see it). Mirror the+ // File branch: drop it from the snapshot directly+ // if it was previously tracked, so the user's+ // deletion is not silently lost as a Noop. Reuse+ // prev_paths_cache (loaded once on first need)+ // rather than a per-path `lookup` walk.+ if prev_paths_cache.is_none() {+ prev_paths_cache = Some(+ crate::git::tree_builder::flatten(+ self.object_store.as_ref(),+ &account,+ t,+ &None,+ )+ .await?,+ );+ }+ let was_tracked = prev_paths_cache+ .as_ref()+ .unwrap()+ .iter()+ .any(|(pp, _)| pp == p);+ if was_tracked && credited_removed.insert(p.clone()) {+ editor+ .remove(self.object_store.as_ref(), &account, p)+ .await?;+ changed += 1;+ }}if let Some(t) = prev_tree {if prev_paths_cache.is_none() {@@ -293,10 +408,27 @@ impl GitService {}let pref = format!("{}/", p);for (path, _) in prev_paths_cache.as_ref().unwrap() {- if path.starts_with(&pref)- && !crate::git::enumerate::prune_path(path)- {+ if !path.starts_with(&pref) {+ continue;+ }+ if should_track_path(path, &ignore_matcher) {set.insert(path.clone());+ } else {+ // Previously tracked under this scope but+ // now ignored/pruned: drop it from the+ // snapshot. Every entry here came from+ // prev_tree, so the removal is a real+ // change. Use should_track_path (not+ // include_path) so `ignored` is not+ // double-counted for paths that are also+ // on disk — the on-disk pass already+ // counted them.+ editor+ .remove(self.object_store.as_ref(), &account, path)+ .await?;+ if credited_removed.insert(path.clone()) {+ changed += 1;+ }}}}@@ -316,11 +448,13 @@ impl GitService {// snapshot. Deduped via BTreeSet so a path present in both sources// is only processed once.None => {- let mut set: std::collections::BTreeSet<String> =- crate::git::enumerate::collect_all(&self.vfs, &account)- .await?- .into_iter()- .collect();+ let listed = crate::git::enumerate::collect_all(&self.vfs, &account).await?;+ let mut set: std::collections::BTreeSet<String> = std::collections::BTreeSet::new();+ for p in listed {+ if include_path(&p) {+ set.insert(p);+ }+ }if let Some(t) = prev_tree {let prev_paths = crate::git::tree_builder::flatten(self.object_store.as_ref(),@@ -330,8 +464,20 @@ impl GitService {).await?;for (p, _) in prev_paths {- if !crate::git::enumerate::prune_path(&p) {+ if should_track_path(&p, &ignore_matcher) {set.insert(p);+ } else {+ // Previously tracked but now ignored/pruned: drop it+ // from the next tree and from the commit index seed.+ // Use should_track_path (not include_path) so `ignored`+ // is not double-counted — paths still on disk were+ // already counted by the collect_all pass above.+ editor+ .remove(self.object_store.as_ref(), &account, &p)+ .await?;+ if credited_removed.insert(p.clone()) {+ changed += 1;+ }}}}@@ -364,6 +510,11 @@ impl GitService {}}+ // Filter index seed for ignored paths+ if self.index_store.is_some() {+ new_index_entries.retain(|path, _| should_track_path(path, &ignore_matcher));+ }+// 4. For each candidate: detect delete vs upsert. Blob writes on the// slow path go through Fast Path 3 (exists precheck) when enabled;// write_object is idempotent regardless.@@ -385,7 +536,6 @@ impl GitService {// last commit, and `(size, mtime_ns)` cannot detect it. `None` (backend// could not report a write time) forces every entry down the slow path.let index_saved_at_ns: Option<i128> = prev_index.as_ref().and_then(|idx| idx.saved_at_ns);- let mut changed = 0usize;for rel_path in candidates {let abs = format!("/local/{}/{}", account, rel_path);match self.vfs.stat(&abs).await {@@ -528,6 +678,7 @@ impl GitService {let _ = fast_path_active;return Ok(CommitResponse::Noop {commit_oid: noop_oid,+ ignored,});}@@ -583,6 +734,7 @@ impl GitService {Ok(CommitResponse::Created {commit_oid,changed,+ ignored,})}@@ -1243,6 +1395,18 @@ fn is_not_found(e: &crate::core::errors::Error) -> bool {matches!(e, crate::core::errors::Error::NotFound(_))}+async fn load_ignore_matcher(+ vfs: &Arc<dyn FileSystem>,+ account: &str,+) -> Result<IgnoreMatcher, GitError> {+ let abs = format!("/local/{}/{}", account, OVGITIGNORE_PATH);+ match vfs.read(&abs, 0, 0).await {+ Ok(bytes) => IgnoreMatcher::parse(&bytes),+ Err(e) if is_not_found(&e) => Ok(IgnoreMatcher::empty()),+ Err(e) => Err(e.into()),+ }+}+/// Project a `FileInfo` into the `(size, mtime_ns)` pair Fast Path 1 keys on.////// Returns `None` when the file's `mod_time` is unrepresentable (pre-epoch@@ -1435,6 +1599,7 @@ mod tests {use crate::git::backends::local::{LocalObjectStore, LocalRefStore};use crate::git::error::ObjectStoreError;use crate::git::error::RefStoreError;+ use crate::git::ignore::OVGITIGNORE_PATH;use crate::git::tree_builder::{flatten, lookup};/// In-memory VFS mock that owns a map from absolute path to bytes.@@ -1697,6 +1862,7 @@ mod tests {CommitResponse::Created {commit_oid,changed,+ ..} => {assert!(changed >= 1, "should record at least one change");let parents = commit_parents(@@ -1769,7 +1935,7 @@ mod tests {let second = svc.commit(req("acct", "main", "noop", None)).await.unwrap();match second {- CommitResponse::Noop { commit_oid } => assert_eq!(commit_oid, first_oid),+ CommitResponse::Noop { commit_oid, .. } => assert_eq!(commit_oid, first_oid),other => panic!("expected Noop, got {other:?}"),}@@ -1851,6 +2017,7 @@ mod tests {CommitResponse::Created {commit_oid,changed,+ ..} => {assert_eq!(changed, 1, "exactly one path (a.md) was removed");commit_oid@@ -1882,6 +2049,7 @@ mod tests {CommitResponse::Created {commit_oid,changed,+ ..} => {assert_eq!(changed, 2, "both files under sub/ were removed");commit_oid@@ -2306,6 +2474,7 @@ mod tests {CommitResponse::Created {commit_oid,changed,+ ..} => {assert_eq!(changed, 3, "three files removed from snapshot");commit_oid@@ -2353,7 +2522,7 @@ mod tests {.await.unwrap();match resp {- CommitResponse::Noop { commit_oid } => assert_eq!(commit_oid, first),+ CommitResponse::Noop { commit_oid, .. } => assert_eq!(commit_oid, first),other => panic!("expected Noop, got {other:?}"),}}@@ -2377,11 +2546,393 @@ mod tests {.await.unwrap();match resp {- CommitResponse::Noop { commit_oid } => assert_eq!(commit_oid, first),+ CommitResponse::Noop { commit_oid, .. } => assert_eq!(commit_oid, first),other => panic!("expected Noop, got {other:?}"),}}+ #[tokio::test]+ async fn test_commit_ovgitignore_excludes_matching_files_and_tracks_itself() {+ let (_dir, vfs, object_store, _ref_store, svc) = make_service("acct_ignore");+ vfs.put(OVGITIGNORE_PATH, b"*.log\n");+ vfs.put("resources/a.md", b"keep");+ vfs.put("resources/a.log", b"skip");++ let resp = svc+ .commit(req("acct_ignore", "main", "ignore", None))+ .await+ .unwrap();+ let (commit_oid, ignored) = match resp {+ CommitResponse::Created {+ commit_oid,+ ignored,+ ..+ } => (commit_oid, ignored),+ other => panic!("expected Created, got {other:?}"),+ };+ assert_eq!(ignored, 1);++ let tree = commit_tree(object_store.as_ref() as &dyn ObjectStore, "acct_ignore", commit_oid).await;+ let all = flatten(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_ignore",+ tree,+ &None,+ )+ .await+ .unwrap();+ let paths: Vec<String> = all.into_iter().map(|(p, _)| p).collect();+ assert_eq!(+ paths,+ vec![+ OVGITIGNORE_PATH.to_string(),+ "resources/a.md".to_string(),+ ]+ );+ }++ #[tokio::test]+ async fn test_commit_ovgitignore_removes_previously_tracked_file_from_snapshot() {+ let (_dir, vfs, object_store, _ref_store, svc) = make_service("acct_ignore_remove");+ vfs.put("resources/a.log", b"tracked before ignore");+ let first = make_commit(&svc, "acct_ignore_remove", "main", "first").await;+ let first_tree = commit_tree(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_ignore_remove",+ first,+ )+ .await;+ assert!(lookup(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_ignore_remove",+ first_tree,+ "resources/a.log",+ )+ .await+ .unwrap()+ .is_some());++ vfs.put(OVGITIGNORE_PATH, b"*.log\n");+ let second = svc+ .commit(req("acct_ignore_remove", "main", "second", None))+ .await+ .unwrap();+ let (second_oid, ignored) = match second {+ CommitResponse::Created {+ commit_oid,+ ignored,+ ..+ } => (commit_oid, ignored),+ other => panic!("expected Created, got {other:?}"),+ };+ // The ignored file is both on disk and in prev_tree; it must be+ // counted exactly once (regression: a previous double-count via+ // include_path in both passes reported 2).+ assert_eq!(ignored, 1);++ let second_tree = commit_tree(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_ignore_remove",+ second_oid,+ )+ .await;+ assert!(lookup(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_ignore_remove",+ second_tree,+ "resources/a.log",+ )+ .await+ .unwrap()+ .is_none());+ assert!(lookup(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_ignore_remove",+ second_tree,+ OVGITIGNORE_PATH,+ )+ .await+ .unwrap()+ .is_some());+ }++ #[tokio::test]+ async fn test_commit_scoped_paths_respect_ovgitignore() {+ let (_dir, vfs, object_store, _ref_store, svc) = make_service("acct_ignore_scoped");+ vfs.put(OVGITIGNORE_PATH, b"*.log\n");+ vfs.put("resources/a.md", b"keep");+ vfs.put("resources/a.log", b"skip");++ let resp = svc+ .commit(req(+ "acct_ignore_scoped",+ "main",+ "scoped",+ Some(vec![+ "resources/a.md".to_string(),+ "resources/a.log".to_string(),+ ]),+ ))+ .await+ .unwrap();+ let (commit_oid, ignored) = match resp {+ CommitResponse::Created {+ commit_oid,+ ignored,+ ..+ } => (commit_oid, ignored),+ other => panic!("expected Created, got {other:?}"),+ };+ assert_eq!(ignored, 1);++ let tree = commit_tree(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_ignore_scoped",+ commit_oid,+ )+ .await;+ assert!(lookup(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_ignore_scoped",+ tree,+ "resources/a.md",+ )+ .await+ .unwrap()+ .is_some());+ assert!(lookup(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_ignore_scoped",+ tree,+ "resources/a.log",+ )+ .await+ .unwrap()+ .is_none());+ }++ #[tokio::test]+ async fn test_commit_invalid_ovgitignore_fails() {+ let (_dir, vfs, _object_store, _ref_store, svc) = make_service("acct_bad_ignore");+ vfs.put(OVGITIGNORE_PATH, b"!keep.log\n");++ let err = svc+ .commit(req("acct_bad_ignore", "main", "bad", None))+ .await+ .unwrap_err();+ assert!(matches!(err, GitError::InvalidIgnoreFile { .. }));+ }++ /// A scoped commit listing an explicit file that is BOTH deleted from disk+ /// AND newly matched by `.ovgitignore` must still drop it from the+ /// snapshot. Regression: the NotFound branch routed `p` through+ /// `include_path`, which returns false for ignored paths, so `p` never+ /// entered the candidate set and the prev_tree prefix loop (`p/`) does not+ /// match the file path itself — the stale blob lingered and `changed`+ /// stayed 0 (Noop), silently losing the user's deletion. The File (Ok)+ /// branch handles the on-disk analogue; this asserts symmetry.+ #[tokio::test]+ async fn test_commit_scoped_notfound_ignored_file_is_removed_from_snapshot() {+ let (_dir, vfs, object_store, _ref_store, svc) =+ make_service("acct_nf_ignore");+ vfs.put("resources/secret.log", b"tracked before ignore");+ let first = make_commit(&svc, "acct_nf_ignore", "main", "first").await;+ let first_tree = commit_tree(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_nf_ignore",+ first,+ )+ .await;+ assert!(lookup(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_nf_ignore",+ first_tree,+ "resources/secret.log",+ )+ .await+ .unwrap()+ .is_some());++ // Ignore logs, delete the file from disk, then commit it by name.+ vfs.put(OVGITIGNORE_PATH, b"*.log\n");+ vfs.delete("resources/secret.log");+ let resp = svc+ .commit(req(+ "acct_nf_ignore",+ "main",+ "second",+ Some(vec!["resources/secret.log".to_string()]),+ ))+ .await+ .unwrap();+ let second_oid = match resp {+ CommitResponse::Created { commit_oid, .. } => commit_oid,+ other => panic!("expected Created (deletion), got {other:?}"),+ };+ let second_tree = commit_tree(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_nf_ignore",+ second_oid,+ )+ .await;+ assert!(+ lookup(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_nf_ignore",+ second_tree,+ "resources/secret.log",+ )+ .await+ .unwrap()+ .is_none(),+ "deleted-and-ignored explicit file must not linger in the snapshot"+ );+ }++ /// Duplicate or overlapping entries in `paths` must not inflate the+ /// `ignored`/`changed` counters. Regression: the scoped branches counted+ /// per listed entry (before BTreeSet dedup) and `was_tracked` probed the+ /// immutable prev_tree, so listing an ignored file twice reported+ /// `ignored=2, changed=2` for a single file. The tree itself was correct+ /// (editor.remove is idempotent); only the reported counts were wrong.+ #[tokio::test]+ async fn test_commit_scoped_duplicate_paths_do_not_double_count() {+ let (_dir, vfs, object_store, _ref_store, svc) = make_service("acct_dup");+ // First commit tracks resources/a.log (no ignore rule yet).+ vfs.put("resources/a.log", b"tracked before ignore");+ let _first = make_commit(&svc, "acct_dup", "main", "first").await;++ // Now ignore logs and commit a.log by name TWICE. It is both on disk+ // and in prev_tree, so each distinct path must contribute exactly one+ // `ignored` and one removal `changed`.+ vfs.put(OVGITIGNORE_PATH, b"*.log\n");+ let resp = svc+ .commit(req(+ "acct_dup",+ "main",+ "dup",+ Some(vec![+ "resources/a.log".to_string(),+ "resources/a.log".to_string(),+ ]),+ ))+ .await+ .unwrap();+ let (second_oid, ignored, changed) = match resp {+ CommitResponse::Created {+ commit_oid,+ ignored,+ changed,+ } => (commit_oid, ignored, changed),+ other => panic!("expected Created, got {other:?}"),+ };+ assert_eq!(ignored, 1, "duplicate ignored path counted once");+ assert_eq!(changed, 1, "duplicate removal counted once");++ let second_tree = commit_tree(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_dup",+ second_oid,+ )+ .await;+ assert!(lookup(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_dup",+ second_tree,+ "resources/a.log",+ )+ .await+ .unwrap()+ .is_none());+ }++ /// A scoped commit listing a *directory* must drop previously-tracked+ /// files under that directory that the new `.ovgitignore` now excludes.+ /// Regression: the directory branch's prev_tree loop only skipped such+ /// paths without removing them from the editor, so the stale ignored+ /// file lingered in the snapshot (the full-enumeration branch already+ /// removed them). Uses LocalFileSystem so the Directory branch runs.+ #[tokio::test]+ async fn test_commit_scoped_directory_removes_now_ignored_prev_file() {+ use crate::plugins::localfs::LocalFileSystem;++ let store_dir = tempfile::tempdir().unwrap();+ let object_store = Arc::new(LocalObjectStore::new(store_dir.path()));+ let ref_store = Arc::new(LocalRefStore::new(store_dir.path()));+ let work_dir = tempfile::tempdir().unwrap();+ let acct_root = work_dir.path().join("local").join("acct_dir_ignore");+ std::fs::create_dir_all(acct_root.join("docs")).unwrap();+ std::fs::write(acct_root.join("docs/keep.md"), b"keep").unwrap();+ std::fs::write(acct_root.join("docs/secret.log"), b"tracked before ignore").unwrap();+ let vfs: Arc<dyn FileSystem> =+ Arc::new(LocalFileSystem::new(work_dir.path().to_str().unwrap()).unwrap());+ let svc = GitService::new(vfs, object_store.clone(), ref_store);++ let first = make_commit(&svc, "acct_dir_ignore", "main", "first").await;+ let first_tree = commit_tree(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_dir_ignore",+ first,+ )+ .await;+ assert!(lookup(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_dir_ignore",+ first_tree,+ "docs/secret.log",+ )+ .await+ .unwrap()+ .is_some());++ // Add an ignore rule and commit ONLY the docs directory (scoped).+ std::fs::write(acct_root.join(OVGITIGNORE_PATH), b"*.log\n").unwrap();+ let resp = svc+ .commit(req(+ "acct_dir_ignore",+ "main",+ "scoped-ignore",+ Some(vec!["docs".into()]),+ ))+ .await+ .unwrap();+ let (second_oid, ignored) = match resp {+ CommitResponse::Created {+ commit_oid,+ ignored,+ ..+ } => (commit_oid, ignored),+ other => panic!("expected Created, got {other:?}"),+ };+ // secret.log is both on disk and in prev_tree; counted once.+ assert_eq!(ignored, 1);++ let second_tree = commit_tree(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_dir_ignore",+ second_oid,+ )+ .await;+ assert!(lookup(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_dir_ignore",+ second_tree,+ "docs/keep.md",+ )+ .await+ .unwrap()+ .is_some());+ assert!(lookup(+ object_store.as_ref() as &dyn ObjectStore,+ "acct_dir_ignore",+ second_tree,+ "docs/secret.log",+ )+ .await+ .unwrap()+ .is_none());+ }+/// Mixing a file and a directory containing that file processes each/// candidate exactly once. The resulting commit must record exactly/// the directory's content, not double-process the listed file. Usesdiff --git a/crates/ragfs/src/git/types.rs b/crates/ragfs/src/git/types.rsindex eccd554ab..9e572469c 100644--- a/crates/ragfs/src/git/types.rs+++ b/crates/ragfs/src/git/types.rs@@ -16,10 +16,20 @@ pub struct CommitRequest {#[derive(Debug, Clone)]pub enum CommitResponse {- Created { commit_oid: ObjectId, changed: usize },+ Created {+ commit_oid: ObjectId,+ changed: usize,+ /// Number of candidate paths skipped by user `.ovgitignore` rules.+ /// Existing hardcoded system pruning is not included.+ ignored: usize,+ },/// No path produced an editor change; ref untouched. `commit_oid` is the/// existing HEAD (or `ObjectId::null` if the branch did not exist).- Noop { commit_oid: ObjectId },+ Noop {+ commit_oid: ObjectId,+ /// Number of candidate paths skipped by user `.ovgitignore` rules.+ ignored: usize,+ },}/// Per-path stat cache entry. Not persisted yet (Fast Path 1 is deferred),diff --git a/crates/ragfs/tests/git_s3_integration.rs b/crates/ragfs/tests/git_s3_integration.rsindex e3816a0bd..0dafe8c34 100644--- a/crates/ragfs/tests/git_s3_integration.rs+++ b/crates/ragfs/tests/git_s3_integration.rs@@ -579,7 +579,7 @@ async fn s3_e2e_commit_noop_when_unchanged() {.await.expect("commit second"){- CommitResponse::Noop { commit_oid } => {+ CommitResponse::Noop { commit_oid, .. } => {assert_eq!(commit_oid, first_oid, "Noop must report the unchanged HEAD oid");}other => panic!("expected Noop, got {other:?}"),diff --git a/docs/design/git-version-control-design.md b/docs/design/git-version-control-design.mdindex 041a066ed..7939f7e84 100644--- a/docs/design/git-version-control-design.md+++ b/docs/design/git-version-control-design.md@@ -171,6 +171,8 @@ sequenceDiagramL0/L1 派生文件(`.abstract.md`、`.overview.md`、`.relations.json`)未命中任一剪枝规则,**会**纳入主线 commit。restore 时随源文件一起回滚,无需重新生成;Python 层在 `restore` 完成后按 `(written_paths, deleted_paths)` 精确触发 L0/L1/DETAIL 向量异步重建(`.relations.json` 不触发向量任务)。+此外,版本管理支持账号级 `.ovgitignore` 控制文件,物理路径为 `/local/{account_id}/.ovgitignore`,Git tree path 为 `.ovgitignore`。该文件使用账号根相对的 glob 子集规则,在 `commit` 枚举当前 VFS 文件和扫描上一版 tree 时共同生效;匹配的文件不会进入新的 snapshot commit,即使它们曾存在于历史 commit 中。`.ovgitignore` 文件自身始终进入版本管理,规则无法把它排除。+## 4.3 单库多命名空间的优势1. **原子跨 scope 快照**:一次 commit 可同时覆盖 `resources/docs` 和 `agent/skills`,对应"Agent 一次任务的所有产出"这种逻辑事务@@ -591,6 +593,8 @@ pub async fn commit(&self, req: CommitRequest) -> Result<CommitResponse> {restore 主流程:**解析目标 commit → 提取该 commit 中 project\_dir 子树 → 与当前 HEAD 中同路径子树 diff → 通过 MountableFS.write/rm 回写 → 删除回写后空目录 → 以当前 HEAD 为 parent 生成新 commit → CAS 更新 ref → 把受影响路径返回给调用方**。`dry_run` 模式只计算差异不写,用于预检。+> **`.ovgitignore` 与 restore:** `.ovgitignore` 只影响 `commit`,不影响 `restore` / `show` / `log`。restore 的输入是 source commit 与当前 HEAD 的 Git tree diff,不能用当前工作区 `.ovgitignore` 过滤,否则会导致历史 commit 中已经被跟踪的文件无法恢复。全账号 restore 时 `.ovgitignore` 作为普通已跟踪文件随 source commit 恢复;子目录 restore 默认不触碰账号根 `.ovgitignore`。+向量索引重建在 service 层**不直接触发**,而是通过把 `written_paths` / `deleted_paths` 放到 `RestoreResponse::Applied` 中返回,Python 层(`VikingFS.restore`)再调度 `ReindexExecutor`。关键差异:与 git checkout 不同,本接口**不移动分支指针到旧 commit**,而是把"旧内容"作为新 commit 的工作树内容,正向写入。新 commit 的 parent 是当前 HEAD,不是目标 commit,这保证了:(1) HEAD 单调前进;(2) 非 `project_dir` 路径自动保留 HEAD 的最新内容,无需特殊处理;(3) restore 本身可以被再次 restore (因为它就是一个普通 commit)。@@ -859,6 +863,19 @@ class VikingFS:author_email=author_email or self._default_author_email(),)+ async def get_gitignore(self, ctx: RequestContext | None = None) -> str:+ """读取账号级 .ovgitignore;不存在时返回空字符串。"""++ async def set_gitignore(+ self,+ content: str,+ ctx: RequestContext | None = None,+ ) -> None:+ """写入账号级 .ovgitignore,不触发语义索引。"""++ async def delete_gitignore(self, ctx: RequestContext | None = None) -> None:+ """删除账号级 .ovgitignore;不存在视为成功。"""+async def restore(self,*,@@ -1198,7 +1215,7 @@ current=commit_a]- **健康检查增强** —— 文档 §14.3。当前仅 `git_enabled` / `git_backend`,未接入 `writable` / `last_commit_age_sec` / 心跳。- **GC / pack file / branch & tag 管理 / diff API** —— 文档 §19。属后续 Phase。- **loom 并发模型测试 + proptest fuzz** —— 文档 §5.2。MVP 未引入。-- 在版本管理中忽略某些特定文件 uri,类似 .gitignore 功能的实现。+- **账号级 `.ovgitignore`** —— 已实现。支持账号根 `.ovgitignore` glob 子集规则,规则仅在 `commit` 时生效;`.ovgitignore` 自身进入版本管理,不进入向量索引;`restore` 不应用当前 ignore 过滤。### Python 侧diff --git a/docs/en/api/11-snapshot.md b/docs/en/api/11-snapshot.mdindex bd8147b29..64a2dc568 100644--- a/docs/en/api/11-snapshot.md+++ b/docs/en/api/11-snapshot.md@@ -13,6 +13,8 @@ The four core commands:| `show` | View a commit's metadata, or read a file's content from that commit || `restore` | Restore a directory (or the whole account tree) to a past snapshot |+In addition, account-level `.ovgitignore` exclusion rules can be managed (`get`/`set`/`delete`) to exclude matching files from `commit`. See [Ignore management](#ignore-management).+## Core Concepts- **Commit**: A snapshot is a commit, uniquely identified by a 40-hex SHA-1 `commit_oid`. Most commands also accept an abbreviated OID prefix or a branch name (e.g. `main`).@@ -85,19 +87,21 @@ When a new snapshot is created:"result": {"result": "created","commit_oid": "3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2",- "changed": 3+ "changed": 3,+ "ignored": 1}}```-When the workspace is unchanged relative to the last commit, the result is `noop` and `commit_oid` is the current HEAD:+`changed` is the number of paths added/updated/removed in this commit; `ignored` is the number of candidate paths skipped by the account `.ovgitignore` rules (built-in system pruning is not counted). When the workspace is unchanged relative to the last commit, the result is `noop` and `commit_oid` is the current HEAD (`noop` also returns `ignored` but has no `changed`):```json{"status": "ok","result": {"result": "noop",- "commit_oid": "3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2"+ "commit_oid": "3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2",+ "ignored": 0}}```@@ -380,6 +384,136 @@ With `dry_run=true`, only the planned diff is returned and nothing is written. D}```+---++## Ignore management++The `.ovgitignore` file at the account root is an account-level exclusion file. At `commit` time, files matching the rules are excluded from the snapshot; the rules file itself is never ignored by `.ovgitignore` rules (a rule matching `.ovgitignore` does not exclude it) and never enters vector indexing. Rules affect only `commit`, not `restore`/`show`/`log`.++The syntax is a common glob subset: blank lines are ignored, `#`-prefixed lines are comments, leading/trailing whitespace is trimmed; `!` negation and backslash escaping are **unsupported**; the file is capped at 64 KiB (validated on write). Matching uses account-relative Git tree paths (`/`-separated).++Three methods are provided: `get_gitignore` (read, empty string when absent), `set_gitignore` (write), and `delete_gitignore` (delete, missing is success and idempotent). All three only need the account from the request context and take no path argument.++### get_gitignore()++Reads the account `.ovgitignore` content; returns an empty string when the file is absent.++**Python SDK (Embedded / HTTP)**++```python+content = client.snapshot.get_gitignore()+```++**HTTP API**++```+GET /api/v1/snapshot/ignore+```++```bash+curl -X GET "http://localhost:1933/api/v1/snapshot/ignore" \+ -H "X-API-Key: your-key"+```++**CLI**++```bash+ov snapshot ignore-get -o json+```++**Response**++```json+{+ "status": "ok",+ "result": "*.log\n"+}+```++> Without `-o json`, the CLI prints the raw content to stdout (so it can be redirected to a file).++### set_gitignore()++Writes the account `.ovgitignore` content (overwrites). The size limit (64 KiB) is validated up front; syntax (negation, escaping) is validated at `commit` time by the Rust layer.++**Parameters**++| Parameter | Type | Required | Default | Description |+|-----------|------|----------|---------|-------------|+| content | str | Yes | - | The `.ovgitignore` content (UTF-8) |++**Python SDK (Embedded / HTTP)**++```python+client.snapshot.set_gitignore(content="*.log\n")+```++**HTTP API**++```+PUT /api/v1/snapshot/ignore+```++```bash+curl -X PUT "http://localhost:1933/api/v1/snapshot/ignore" \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d '{"content": "*.log\n"}'+```++**CLI**++```bash+# Pass content inline with --content, or read from a file with --file+ov snapshot ignore-set --content "*.log" -o json+ov snapshot ignore-set --file ./my-rules -o json+```++**Response**++```json+{+ "status": "ok",+ "result": null+}+```++### delete_gitignore()++Deletes the account `.ovgitignore`. Missing is success (idempotent).++**Python SDK (Embedded / HTTP)**++```python+client.snapshot.delete_gitignore()+```++**HTTP API**++```+DELETE /api/v1/snapshot/ignore+```++```bash+curl -X DELETE "http://localhost:1933/api/v1/snapshot/ignore" \+ -H "X-API-Key: your-key"+```++**CLI**++```bash+ov snapshot ignore-delete -o json+```++**Response**++```json+{+ "status": "ok",+ "result": null+}+```+## A Typical FlowA complete "commit → modify → restore" flow (Python SDK):@@ -418,6 +552,7 @@ For more end-to-end examples, see the [examples/snapshot/](file:///cloudide/work|----------|-------------|------------|| Branch/commit not found, or `show`'s `path` does not exist in that commit | 404 | `NOT_FOUND` || Branch concurrently advanced during restore (CAS conflict) | 409 | `CONFLICT` |+| `.ovgitignore` too large, non-UTF-8, or containing unsupported `!` negation/backslash escaping (validated at `commit` time) | 400 | `INVALID_ARGUMENT` || Request body contains an unknown field (request model is `extra="forbid"`) | 400 | `INVALID_ARGUMENT` |## Related Documentationdiff --git a/docs/en/guides/15-snapshot.md b/docs/en/guides/15-snapshot.mdindex 5295f41dc..83a80389f 100644--- a/docs/en/guides/15-snapshot.md+++ b/docs/en/guides/15-snapshot.md@@ -214,11 +214,88 @@ curl -X POST "http://localhost:1933/api/v1/snapshot/restore" \- HEAD always advances monotonically, and **history is never rewritten or lost** — going back to an older version is itself a new commit.- `restore` only affects files within `project_dir` (the whole account tree when omitted); files outside that scope are left untouched.+## Excluding Files with `.ovgitignore`++The `.ovgitignore` file at the account root is an account-level exclusion file, analogous to a root `.gitignore`: files matching its rules are excluded from `commit` snapshots. It composes with the built-in system pruning (`_system`, `tasks`, vector-index derived files, etc.).++Key points:++- The rules file itself is **never ignored by `.ovgitignore` rules** — even if a rule matches `.ovgitignore` it is still included in snapshots, so rule changes are auditable and restorable.+- Rules affect **only `commit`**; `restore`, `show`, and `log` treat commit contents as authoritative and do not apply the current `.ovgitignore` as a filter. So restoring a historical snapshot still restores files that match the current rules.+- If a file was tracked in an earlier commit and a later rule matches it, the next `commit` removes it from the new snapshot (the workspace file itself is untouched).+- `.ovgitignore` never enters vector indexing/retrieval.++### Rule syntax++`.ovgitignore` is UTF-8 text supporting a common glob subset:++- Blank lines are ignored.+- A line whose first non-space character is `#` is a comment.+- Leading/trailing whitespace is trimmed.+- `!` negation is **unsupported** (its presence makes `commit` fail with an error).+- Git-style backslash escaping is **unsupported**.+- The file is capped at 64 KiB.++Matching uses account-relative Git tree paths (`/`-separated), e.g. `resources/proj/a.log`. For example, `*.log` matches `.log` files at any depth, `build/` matches a directory named `build` and its contents, and `/cache/**` matches only `cache/` at the account root.++### Python SDK++```python+# Write the rules+client.snapshot.set_gitignore(content="*.log\n")++# Read (returns an empty string when absent)+print(client.snapshot.get_gitignore())++# Delete (missing is success, idempotent)+client.snapshot.delete_gitignore()+```++On subsequent commits, files matching the rules are excluded, and the response's `ignored` field reports how many candidate paths were skipped:++```python+v = client.snapshot.commit(message="with ignore")+print(v["result"], v.get("ignored")) # created, 1+```++### CLI++```bash+# Set (pass content inline with --content, or read from a file with --file)+ov snapshot ignore-set --content "*.log" -o json+ov snapshot ignore-set --file ./my-rules -o json++# Get (-o json returns {"result": "<content>"}; without -o json it prints the content to stdout)+ov snapshot ignore-get -o json++# Delete (idempotent)+ov snapshot ignore-delete -o json+```++### HTTP API++```bash+# Get+curl -X GET "http://localhost:1933/api/v1/snapshot/ignore" \+ -H "X-API-Key: your-key"++# Set+curl -X PUT "http://localhost:1933/api/v1/snapshot/ignore" \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d '{"content": "*.log\n"}'++# Delete+curl -X DELETE "http://localhost:1933/api/v1/snapshot/ignore" \+ -H "X-API-Key: your-key"+```+## Notes- After editing the `git` config, restart the service / re-initialize the client for it to take effect.- With the `s3` backend, `git.s3.bucket` and `git.s3.region` are required; missing them causes initialization to fail.- If a restore has vector side effects (files written/deleted), the response carries a `task_id` you can poll via `GET /api/v1/tasks/{task_id}` to track the background vector rebuild (see the [Observability guide](05-observability.md) and [API Overview](../api/01-overview.md)).+- If `.ovgitignore` is too large (over 64 KiB) or contains unsupported syntax (`!` negation, backslash escaping), `commit` fails with an `invalid operation` error; `set_gitignore` validates the size up front.- Do not operate on the `.ovgit` directory with an external `git` tool; it is maintained by OpenViking.## Related Documentationdiff --git a/docs/zh/api/11-snapshot.md b/docs/zh/api/11-snapshot.mdindex da1345f0c..6f0db13b8 100644--- a/docs/zh/api/11-snapshot.md+++ b/docs/zh/api/11-snapshot.md@@ -13,6 +13,8 @@ OpenViking 在 VikingFS 之上提供了一套基于 Git 的多版本管理能力| `show` | 查看某个提交的元数据,或读取该提交中某个文件的内容 || `restore` | 把目录(或整棵账号树)恢复到某个历史快照的状态 |+此外还提供账号级 `.ovgitignore` 排除规则的管理命令(`get`/`set`/`delete`),用于在 `commit` 时按规则排除匹配的文件。详见 [ignore 管理](#ignore-管理)。+## 核心概念- **提交(commit)**:一个快照对应一个提交,由 40 位十六进制的 SHA-1 `commit_oid` 唯一标识。多数命令也接受 OID 的缩写前缀,或分支名(如 `main`)。@@ -85,19 +87,21 @@ ov snapshot commit -m "v1 initial import" --paths viking://resources/my_md.md -o"result": {"result": "created","commit_oid": "3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2",- "changed": 3+ "changed": 3,+ "ignored": 1}}```-当工作区相对上一次提交没有任何变化时返回 `noop`,`commit_oid` 为当前 HEAD:+`changed` 为本次提交中新增/修改/删除的路径数;`ignored` 为本次被账号 `.ovgitignore` 规则排除的候选路径数(系统内置剪枝不计入)。当工作区相对上一次提交没有任何变化时返回 `noop`,`commit_oid` 为当前 HEAD(`noop` 同样返回 `ignored`,但不含 `changed`):```json{"status": "ok","result": {"result": "noop",- "commit_oid": "3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2"+ "commit_oid": "3f2a1b9c4d5e6f70819293a4b5c6d7e8f9a0b1c2",+ "ignored": 0}}```@@ -380,6 +384,136 @@ ov snapshot restore 3f2a1b9c viking://resources/my_project --dry-run -o json}```+---++## ignore 管理++账号根目录下的 `.ovgitignore` 是账号级排除规则文件。在 `commit` 时,匹配规则的文件被排除出快照;规则文件本身不会被 `.ovgitignore` 规则忽略(即使规则匹配 `.ovgitignore` 也不会被排除),且不进入向量索引。规则只影响 `commit`,不影响 `restore`/`show`/`log`。++语法为常见 glob 子集:空行被忽略、`#` 开头为注释、行首尾空白被裁剪;**不支持** `!` 取反与反斜杠转义;文件大小上限 64 KiB(写入时即校验)。匹配路径为账号相对 Git 树路径(`/` 分隔)。++提供三个方法:`get_gitignore`(读取,缺失返回空串)、`set_gitignore`(写入)、`delete_gitignore`(删除,缺失即成功、幂等)。三者都只需请求上下文中的账号,无路径参数。++### get_gitignore()++读取账号 `.ovgitignore` 内容;文件不存在时返回空字符串。++**Python SDK (Embedded / HTTP)**++```python+content = client.snapshot.get_gitignore()+```++**HTTP API**++```+GET /api/v1/snapshot/ignore+```++```bash+curl -X GET "http://localhost:1933/api/v1/snapshot/ignore" \+ -H "X-API-Key: your-key"+```++**CLI**++```bash+ov snapshot ignore-get -o json+```++**响应**++```json+{+ "status": "ok",+ "result": "*.log\n"+}+```++> 不带 `-o json` 时,CLI 直接把原始内容打到 stdout(可重定向到文件)。++### set_gitignore()++写入账号 `.ovgitignore` 内容(覆盖)。写入前校验大小上限(64 KiB);语法(取反、转义等)在 `commit` 时由 Rust 层校验。++**参数**++| 参数 | 类型 | 必填 | 默认值 | 说明 |+|------|------|------|--------|------|+| content | str | 是 | - | `.ovgitignore` 文件内容(UTF-8) |++**Python SDK (Embedded / HTTP)**++```python+client.snapshot.set_gitignore(content="*.log\n")+```++**HTTP API**++```+PUT /api/v1/snapshot/ignore+```++```bash+curl -X PUT "http://localhost:1933/api/v1/snapshot/ignore" \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d '{"content": "*.log\n"}'+```++**CLI**++```bash+# 用 --content 直接传内容,或用 --file 从文件读取+ov snapshot ignore-set --content "*.log" -o json+ov snapshot ignore-set --file ./my-rules -o json+```++**响应**++```json+{+ "status": "ok",+ "result": null+}+```++### delete_gitignore()++删除账号 `.ovgitignore`。文件不存在也视为成功(幂等)。++**Python SDK (Embedded / HTTP)**++```python+client.snapshot.delete_gitignore()+```++**HTTP API**++```+DELETE /api/v1/snapshot/ignore+```++```bash+curl -X DELETE "http://localhost:1933/api/v1/snapshot/ignore" \+ -H "X-API-Key: your-key"+```++**CLI**++```bash+ov snapshot ignore-delete -o json+```++**响应**++```json+{+ "status": "ok",+ "result": null+}+```+## 典型流程下面演示一个"提交 → 修改 → 恢复"的完整流程(Python SDK):@@ -418,6 +552,7 @@ client.close()|------|-------------|--------|| 分支/提交不存在,或 `show` 的 `path` 在该提交中不存在 | 404 | `NOT_FOUND` || 恢复期间分支被并发提交改写(CAS 冲突) | 409 | `CONFLICT` |+| `.ovgitignore` 过大、非 UTF-8,或包含不支持的 `!` 取反/反斜杠转义语法(`commit` 时校验) | 400 | `INVALID_ARGUMENT` || 请求体包含未知字段(请求模型为 `extra="forbid"`) | 400 | `INVALID_ARGUMENT` |## 相关文档diff --git a/docs/zh/guides/15-snapshot.md b/docs/zh/guides/15-snapshot.mdindex 6a6446832..90aa519ab 100644--- a/docs/zh/guides/15-snapshot.md+++ b/docs/zh/guides/15-snapshot.md@@ -214,11 +214,88 @@ curl -X POST "http://localhost:1933/api/v1/snapshot/restore" \- HEAD 始终单调向前推进,**历史永远不会被改写或丢失**——回到旧版本本身也是一次新的提交。- `restore` 只影响 `project_dir`(省略时为整棵账号树)范围内的文件,范围之外的文件保持不变。+## 使用 `.ovgitignore` 排除文件++账号根目录下的 `.ovgitignore` 是一个账号级的排除规则文件,作用类似根 `.gitignore`:匹配该规则的文件在 `commit` 时被排除出快照。它与系统内置的剪枝规则(`_system`、`tasks`、向量索引派生文件等)叠加生效。++要点:++- 规则文件本身**不会被 `.ovgitignore` 规则忽略**,即使规则匹配 `.ovgitignore` 也会被正常纳入快照——这样规则的变更可追溯、可恢复。+- 规则**只影响 `commit`**;`restore`、`show`、`log` 仍以提交内容为准,不把当前 `.ovgitignore` 当作过滤器。因此恢复一个历史快照时,即便其中某些文件匹配当前规则,仍会被正常恢复。+- 若某个文件在更早的提交中已被跟踪、之后新增规则匹配到它,下一次 `commit` 会把它从新快照中移除(工作区的文件本身不受影响)。+- `.ovgitignore` 不会进入向量索引/检索。++### 规则语法++`.ovgitignore` 为 UTF-8 文本,支持常见的 glob 子集:++- 空行被忽略。+- 首个非空白字符为 `#` 的行是注释。+- 行首/行尾空白会被裁剪。+- **不支持** `!` 取反(出现会让 `commit` 失败并报错)。+- **不支持** Git 风格的反斜杠转义。+- 文件大小上限 64 KiB。++匹配路径使用账号相对的 Git 树路径(`/` 分隔),如 `resources/proj/a.log`。例如 `*.log` 匹配任意深度的 `.log` 文件,`build/` 匹配名为 `build` 的目录及其内容,`/cache/**` 仅匹配账号根下的 `cache/`。++### Python SDK++```python+# 写入规则+client.snapshot.set_gitignore(content="*.log\n")++# 读取(不存在时返回空字符串)+print(client.snapshot.get_gitignore())++# 删除(不存在也视为成功,幂等)+client.snapshot.delete_gitignore()+```++随后提交时,匹配规则的文件会被排除,响应里的 `ignored` 字段给出本次被排除的候选路径数:++```python+v = client.snapshot.commit(message="with ignore")+print(v["result"], v.get("ignored")) # created, 1+```++### CLI++```bash+# 设置(用 --content 直接传内容,或用 --file 从文件读取)+ov snapshot ignore-set --content "*.log" -o json+ov snapshot ignore-set --file ./my-rules -o json++# 读取(-o json 返回 {"result": "<内容>"};不加 -o json 时直接把内容打到 stdout)+ov snapshot ignore-get -o json++# 删除(幂等)+ov snapshot ignore-delete -o json+```++### HTTP API++```bash+# 读取+curl -X GET "http://localhost:1933/api/v1/snapshot/ignore" \+ -H "X-API-Key: your-key"++# 写入+curl -X PUT "http://localhost:1933/api/v1/snapshot/ignore" \+ -H "Content-Type: application/json" \+ -H "X-API-Key: your-key" \+ -d '{"content": "*.log\n"}'++# 删除+curl -X DELETE "http://localhost:1933/api/v1/snapshot/ignore" \+ -H "X-API-Key: your-key"+```+## 注意事项- 修改 `git` 配置后必须重启服务 / 重新初始化客户端才能生效。- 启用 `s3` 后端时,`git.s3.bucket` 与 `git.s3.region` 为必填项,缺失会导致初始化失败。- 恢复操作如涉及向量副作用(写入/删除文件),响应会返回一个 `task_id`,可通过 `GET /api/v1/tasks/{task_id}` 轮询后台向量重建进度(参见 [系统指南](05-observability.md) 与 [API 概览](../api/01-overview.md))。+- `.ovgitignore` 内容过大(超过 64 KiB)或包含 `!` 取反、反斜杠转义等不支持语法时,`commit` 会失败并报 `invalid operation` 错误;写入时(`set_gitignore`)会预先校验大小。- 不要手动用外部 `git` 工具去操作 `.ovgit` 目录,它由 OpenViking 维护。## 相关文档diff --git a/examples/snapshot/snapshot_cli_test.py b/examples/snapshot/snapshot_cli_test.pyindex f379e915f..aa80570b8 100644--- a/examples/snapshot/snapshot_cli_test.py+++ b/examples/snapshot/snapshot_cli_test.py@@ -116,11 +116,28 @@ def print_find(query: str, root_uri: str) -> None:run_ov(["find", query, "--uri", root_uri, "--limit", "10", "-o", "json"])-def commit_snapshot(message: str) -> dict[str, Any]:- proc = run_ov(["snapshot", "commit", "-m", message, "-o", "json"])+def commit_snapshot(message: str, paths: list[str] | None = None) -> dict[str, Any]:+ args = ["snapshot", "commit", "-m", message, "-o", "json"]+ if paths:+ args += ["--paths", ",".join(paths)]+ proc = run_ov(args)return parse_json(proc.stdout).get("result") or {}+def set_gitignore(content: str) -> None:+ run_ov(["snapshot", "ignore-set", "--content", content, "-o", "json"])+++def get_gitignore() -> str:+ proc = run_ov(["snapshot", "ignore-get", "-o", "json"])+ result = parse_json(proc.stdout).get("result")+ return result if isinstance(result, str) else ""+++def delete_gitignore() -> None:+ run_ov(["snapshot", "ignore-delete", "-o", "json"])++def get_task(task_id: str) -> dict[str, Any]:proc = run_ov(["task", "status", task_id, "-o", "json"])return parse_json(proc.stdout).get("result") or {}@@ -168,7 +185,7 @@ def main() -> None:print_section("v1 initial import")write_text(uris["guide"], f"# Guide\n\nInitial CLI content with {alpha}.\n", "create")write_text(uris["todo"], f"# Todo\n\nRemember {todo}.\n", "create")- v1 = commit_snapshot("cli v1 initial import")+ v1 = commit_snapshot("cli v1 initial import", paths=[root_uri])print_commit_oid("v1", v1)print_find(alpha, root_uri)@@ -176,7 +193,7 @@ def main() -> None:write_text(uris["guide"], f"# Guide\n\nUpdated CLI content with {beta}.\n", "replace")remove_resource(uris["todo"])write_text(uris["changelog"], f"# Changelog\n\nCreated {changelog}.\n", "create")- v2 = commit_snapshot("cli v2 modify delete add")+ v2 = commit_snapshot("cli v2 modify delete add", paths=[root_uri])print_commit_oid("v2", v2)print_find(beta, root_uri)print_find(todo, root_uri)@@ -186,7 +203,7 @@ def main() -> None:mkdir(f"{root_uri}/archive")write_text(uris["changelog"], f"# Changelog\n\nCreated {changelog}. Added {gamma}.\n", "replace")write_text(uris["archive"], f"# Archive\n\nArchived marker {archive}.\n", "create")- v3 = commit_snapshot("cli v3 second changes")+ v3 = commit_snapshot("cli v3 second changes", paths=[root_uri])print_commit_oid("v3", v3)print_find(gamma, root_uri)print_find(archive, root_uri)@@ -210,6 +227,23 @@ def main() -> None:print_find(changelog, root_uri)run_ov(["snapshot", "log", "--limit", "10", "-o", "json"])+ print_section("ovgitignore exclude")+ set_gitignore("*.txt\n")+ print(f"get_gitignore: {get_gitignore()!r}")+ # Write two files: debug.txt matches *.txt (excluded), notes.md does not.+ ignored_uri = f"{root_uri}/debug.txt"+ kept_uri = f"{root_uri}/notes.md"+ write_text(ignored_uri, f"# Scratch\n\ndebug noise {archive}.\n", "create")+ write_text(kept_uri, f"# Notes\n\nkept marker {archive}.\n", "create")+ v4 = commit_snapshot("cli v4 with ovgitignore", paths=[root_uri])+ print(f"ignored count: {v4.get('ignored')}")+ # debug.txt matches *.txt -> show on the snapshot should 404.+ run_ov(["snapshot", "show", v4.get("commit_oid", ""), "--path", ignored_uri, "-o", "json"], check=False)+ # notes.md is not ignored -> readable from the snapshot.+ run_ov(["snapshot", "show", v4.get("commit_oid", ""), "--path", kept_uri, "-o", "json"], check=False)+ delete_gitignore()+ print(f"get_gitignore after delete: {get_gitignore()!r}")+print_section("done")print("CLI snapshot multi-version example finished")diff --git a/examples/snapshot/snapshot_example.py b/examples/snapshot/snapshot_example.pyindex 7173f8a3c..968ff694e 100644--- a/examples/snapshot/snapshot_example.py+++ b/examples/snapshot/snapshot_example.py@@ -59,8 +59,8 @@ def print_read(client: Any, uri: str) -> None:print(f"read {uri}: {len(content)} chars | {first_line}")-def commit_snapshot(client: Any, message: str) -> dict[str, Any]:- result = client.snapshot.commit(message=message)+def commit_snapshot(client: Any, message: str, paths: list[str] | None = None) -> dict[str, Any]:+ result = client.snapshot.commit(message=message, paths=paths)print(f"commit {message!r}: result={result.get('result')} oid={short_oid(result.get('commit_oid'))}")return result@@ -121,14 +121,14 @@ def main() -> None:print_section("v1 initial import")write_text(client, uris["guide"], f"# Guide\n\nInitial SDK content with {alpha}.\n", mode="create")write_text(client, uris["todo"], f"# Todo\n\nRemember {todo}.\n", mode="create")- v1 = commit_snapshot(client, "sdk v1 initial import")+ v1 = commit_snapshot(client, "sdk v1 initial import", paths=[root_uri])print_find(client, alpha, root_uri)print_section("v2 modify delete add")write_text(client, uris["guide"], f"# Guide\n\nUpdated SDK content with {beta}.\n", mode="replace")remove_resource(client, uris["todo"])write_text(client, uris["changelog"], f"# Changelog\n\nCreated {changelog}.\n", mode="create")- v2 = commit_snapshot(client, "sdk v2 modify delete add")+ v2 = commit_snapshot(client, "sdk v2 modify delete add", paths=[root_uri])print_find(client, beta, root_uri)print_find(client, todo, root_uri)print_find(client, changelog, root_uri)@@ -138,7 +138,7 @@ def main() -> None:print(f"mkdir: {root_uri}/archive")write_text(client, uris["changelog"], f"# Changelog\n\nCreated {changelog}. Added {gamma}.\n", mode="replace")write_text(client, uris["archive"], f"# Archive\n\nArchived marker {archive}.\n", mode="create")- v3 = commit_snapshot(client, "sdk v3 second changes")+ v3 = commit_snapshot(client, "sdk v3 second changes", paths=[root_uri])print_find(client, gamma, root_uri)print_find(client, archive, root_uri)log_before = client.snapshot.log(limit=10)@@ -174,6 +174,33 @@ def main() -> None:for commit in log_after:print(f" {short_oid(commit.get('oid'))} {commit.get('message', '')}")+ print_section("ovgitignore exclude")+ # Set an account-level .ovgitignore rule. Files matching it are excluded+ # from subsequent commits; the ignore file itself is always versioned.+ client.snapshot.set_gitignore(content="*.txt\n")+ print(f"get_gitignore: {client.snapshot.get_gitignore()!r}")+ # Write two files: debug.txt matches *.txt (excluded), notes.md does not.+ ignored_uri = f"{root_uri}/debug.txt"+ kept_uri = f"{root_uri}/notes.md"+ write_text(client, ignored_uri, f"# Scratch\n\ndebug noise {gamma}.\n", mode="create")+ write_text(client, kept_uri, f"# Notes\n\nkept marker {archive}.\n", mode="create")+ v4 = commit_snapshot(client, "sdk v4 with ovgitignore", paths=[root_uri])+ print(f"ignored count: {v4.get('ignored')}")+ # debug.txt was excluded -> reading it from the snapshot fails.+ try:+ client.snapshot.show(v4["commit_oid"], path=ignored_uri)+ ignored_present = True+ except Exception as exc: # AGFSNotFoundError when excluded+ ignored_present = False+ print(f"debug.txt excluded from snapshot (show raised: {type(exc).__name__})")+ # notes.md is not ignored -> readable from the snapshot.+ kept_blob = client.snapshot.show(v4["commit_oid"], path=kept_uri)+ print(f"debug.txt in v4 snapshot: {ignored_present}")+ print(f"notes.md in v4 snapshot: {bool(kept_blob)}")+ # Clean up the rule.+ client.snapshot.delete_gitignore()+ print(f"get_gitignore after delete: {client.snapshot.get_gitignore()!r}")+print_section("done")print("Python SDK snapshot multi-version example finished")finally:diff --git a/examples/snapshot/snapshot_http_api_test.py b/examples/snapshot/snapshot_http_api_test.pyindex 74306f658..c4d83ae9a 100644--- a/examples/snapshot/snapshot_http_api_test.py+++ b/examples/snapshot/snapshot_http_api_test.py@@ -97,12 +97,15 @@ def print_find(client: httpx.Client, query: str, root_uri: str) -> None:)-def commit_snapshot(client: httpx.Client, message: str) -> dict[str, Any]:+def commit_snapshot(client: httpx.Client, message: str, paths: list[str] | None = None) -> dict[str, Any]:+ body: dict[str, Any] = {"message": message}+ if paths:+ body["paths"] = pathsdata = request_json(client,"POST","/api/v1/snapshot/commit",- json={"message": message},+ json=body,)return data.get("result") or {}@@ -111,6 +114,20 @@ def show_snapshot(client: httpx.Client, target_ref: str) -> None:request_json(client, "GET", "/api/v1/snapshot/show", label=f"snapshot show {target_ref}", params={"target_ref": target_ref})+def get_gitignore(client: httpx.Client) -> str:+ data = request_json(client, "GET", "/api/v1/snapshot/ignore", label="get .ovgitignore")+ result = data.get("result")+ return result if isinstance(result, str) else ""+++def set_gitignore(client: httpx.Client, content: str) -> None:+ request_json(client, "PUT", "/api/v1/snapshot/ignore", label="set .ovgitignore", json={"content": content})+++def delete_gitignore(client: httpx.Client) -> None:+ request_json(client, "DELETE", "/api/v1/snapshot/ignore", label="delete .ovgitignore")++def wait_for_task(client: httpx.Client, task_id: str | None, *, timeout: float = WAIT_TIMEOUT, poll_interval: float = 0.5) -> None:"""Poll a background task by id until it reaches a terminal state.@@ -164,14 +181,14 @@ def main() -> None:print_section("v1 initial import")write_text(client, uris["guide"], f"# Guide\n\nInitial HTTP content with {alpha}.\n", "create")write_text(client, uris["todo"], f"# Todo\n\nRemember {todo}.\n", "create")- v1 = commit_snapshot(client, "http v1 initial import")+ v1 = commit_snapshot(client, "http v1 initial import", paths=[root_uri])print_find(client, alpha, root_uri)print_section("v2 modify delete add")write_text(client, uris["guide"], f"# Guide\n\nUpdated HTTP content with {beta}.\n", "replace")remove_resource(client, uris["todo"])write_text(client, uris["changelog"], f"# Changelog\n\nCreated {changelog}.\n", "create")- v2 = commit_snapshot(client, "http v2 modify delete add")+ v2 = commit_snapshot(client, "http v2 modify delete add", paths=[root_uri])print_find(client, beta, root_uri)print_find(client, todo, root_uri)print_find(client, changelog, root_uri)@@ -180,7 +197,7 @@ def main() -> None:mkdir(client, f"{root_uri}/archive")write_text(client, uris["changelog"], f"# Changelog\n\nCreated {changelog}. Added {gamma}.\n", "replace")write_text(client, uris["archive"], f"# Archive\n\nArchived marker {archive}.\n", "create")- v3 = commit_snapshot(client, "http v3 second changes")+ v3 = commit_snapshot(client, "http v3 second changes", paths=[root_uri])print_find(client, gamma, root_uri)print_find(client, archive, root_uri)request_json(@@ -223,6 +240,35 @@ def main() -> None:params={"branch": "main", "limit": 10},)+ print_section("ovgitignore exclude")+ set_gitignore(client, "*.txt\n")+ print(f"get_gitignore: {get_gitignore(client)!r}")+ # Write two files: debug.txt matches *.txt (excluded), notes.md does not.+ ignored_uri = f"{root_uri}/debug.txt"+ kept_uri = f"{root_uri}/notes.md"+ write_text(client, ignored_uri, f"# Scratch\n\ndebug noise {archive}.\n", "create")+ write_text(client, kept_uri, f"# Notes\n\nkept marker {archive}.\n", "create")+ v4 = commit_snapshot(client, "http v4 with ovgitignore", paths=[root_uri])+ print(f"ignored count: {v4.get('ignored')}")+ # debug.txt matches *.txt -> reading it from the snapshot 404s.+ request_json(+ client,+ "GET",+ "/api/v1/snapshot/show",+ label=f"debug.txt excluded from v4: {ignored_uri}",+ params={"target_ref": v4.get("commit_oid", ""), "path": ignored_uri},+ )+ # notes.md is not ignored -> readable from the snapshot.+ request_json(+ client,+ "GET",+ "/api/v1/snapshot/show",+ label=f"notes.md kept in v4: {kept_uri}",+ params={"target_ref": v4.get("commit_oid", ""), "path": kept_uri},+ )+ delete_gitignore(client)+ print(f"get_gitignore after delete: {get_gitignore(client)!r}")+print_section("done")print("HTTP API snapshot multi-version example finished")diff --git a/openviking/client/local.py b/openviking/client/local.pyindex 9ae167d9f..546aefbc9 100644--- a/openviking/client/local.py+++ b/openviking/client/local.py@@ -1161,6 +1161,18 @@ class LocalClient(BaseClient):"""Walk back along parents[0] up to limit commits."""return await self._service.fs.log(branch=branch, limit=limit, ctx=self._ctx)+ async def git_get_ignore(self) -> str:+ """Return the account .ovgitignore content (empty string if absent)."""+ return await self._service.fs.get_gitignore(ctx=self._ctx)++ async def git_set_ignore(self, *, content: str) -> None:+ """Write the account .ovgitignore control file."""+ await self._service.fs.set_gitignore(content=content, ctx=self._ctx)++ async def git_delete_ignore(self) -> None:+ """Delete the account .ovgitignore control file (missing is success)."""+ await self._service.fs.delete_gitignore(ctx=self._ctx)+# ============= Debug =============async def check_consistency(self, uri: str) -> Dict[str, Any]:diff --git a/openviking/server/routers/snapshot.py b/openviking/server/routers/snapshot.pyindex ec7500a0e..f7ba48900 100644--- a/openviking/server/routers/snapshot.py+++ b/openviking/server/routers/snapshot.py@@ -175,3 +175,60 @@ async def show("X-Snapshot-Size": str(blob["size"]),},)++[email protected]("/ignore")+async def get_ignore(+ _ctx: RequestContext = Depends(get_request_context),+):+ """Return the account ``.ovgitignore`` content (empty string if absent)."""+ service = get_service()+ try:+ result = await service.fs.get_gitignore(ctx=_ctx)+ except AGFSClientError as e:+ mapped = map_exception(e)+ if mapped is not None:+ raise mapped from e+ raise+ return Response(status="ok", result=result)+++class SetIgnoreRequest(BaseModel):+ """Request body for ``PUT /api/v1/snapshot/ignore``."""++ model_config = ConfigDict(extra="forbid")++ content: str++[email protected]("/ignore")+async def set_ignore(+ request: SetIgnoreRequest = Body(...),+ _ctx: RequestContext = Depends(get_request_context),+):+ """Write the account ``.ovgitignore`` control file."""+ service = get_service()+ try:+ await service.fs.set_gitignore(content=request.content, ctx=_ctx)+ except AGFSClientError as e:+ mapped = map_exception(e)+ if mapped is not None:+ raise mapped from e+ raise+ return Response(status="ok", result=None)++[email protected]("/ignore")+async def delete_ignore(+ _ctx: RequestContext = Depends(get_request_context),+):+ """Delete the account ``.ovgitignore`` control file (missing is success)."""+ service = get_service()+ try:+ await service.fs.delete_gitignore(ctx=_ctx)+ except AGFSClientError as e:+ mapped = map_exception(e)+ if mapped is not None:+ raise mapped from e+ raise+ return Response(status="ok", result=None)diff --git a/openviking/service/fs_service.py b/openviking/service/fs_service.pyindex beb7960d6..76846f390 100644--- a/openviking/service/fs_service.py+++ b/openviking/service/fs_service.py@@ -618,3 +618,24 @@ class FSService:"""Forward to VikingFS.log. Walks parents[0] up to limit commits."""viking_fs = self._ensure_initialized()return await viking_fs.log(branch=branch, limit=limit, ctx=ctx)++ async def get_gitignore(self, *, ctx: RequestContext) -> str:+ """Forward to VikingFS.get_gitignore. Returns the account .ovgitignore+ content, or an empty string if absent."""+ viking_fs = self._ensure_initialized()+ return await viking_fs.get_gitignore(ctx=ctx)++ async def set_gitignore(+ self, *, content: str, ctx: RequestContext+ ) -> None:+ """Forward to VikingFS.set_gitignore. Writes the account .ovgitignore+ control file (validates the size limit)."""+ viking_fs = self._ensure_initialized()+ await viking_fs.set_gitignore(content, ctx=ctx)++ async def delete_gitignore(self, *, ctx: RequestContext) -> None:+ """Forward to VikingFS.delete_gitignore. Removes the account+ .ovgitignore; missing is success."""+ viking_fs = self._ensure_initialized()+ await viking_fs.delete_gitignore(ctx=ctx)+diff --git a/openviking/snapshot_namespace.py b/openviking/snapshot_namespace.pyindex ed6c7c37d..3196f42a4 100644--- a/openviking/snapshot_namespace.py+++ b/openviking/snapshot_namespace.py@@ -85,6 +85,21 @@ class AsyncSnapshotNamespace:await self._client._ensure_initialized()return await self._client._client.git_log(branch=branch, limit=limit)+ async def get_gitignore(self) -> str:+ """Return the account .ovgitignore content (empty string if absent)."""+ await self._client._ensure_initialized()+ return await self._client._client.git_get_ignore()++ async def set_gitignore(self, *, content: str) -> None:+ """Write the account .ovgitignore control file."""+ await self._client._ensure_initialized()+ await self._client._client.git_set_ignore(content=content)++ async def delete_gitignore(self) -> None:+ """Delete the account .ovgitignore control file (missing is success)."""+ await self._client._ensure_initialized()+ await self._client._client.git_delete_ignore()+class SyncSnapshotNamespace:"""Synchronous wrapper around AsyncSnapshotNamespace.@@ -156,3 +171,12 @@ class SyncSnapshotNamespace:limit: int = 20,) -> List[Dict[str, Any]]:return run_async(self._ns().log(branch=branch, limit=limit))++ def get_gitignore(self) -> str:+ return run_async(self._ns().get_gitignore())++ def set_gitignore(self, *, content: str) -> None:+ return run_async(self._ns().set_gitignore(content=content))++ def delete_gitignore(self) -> None:+ return run_async(self._ns().delete_gitignore())diff --git a/openviking/storage/viking_fs.py b/openviking/storage/viking_fs.pyindex d4782c77e..983a19b78 100644--- a/openviking/storage/viking_fs.py+++ b/openviking/storage/viking_fs.py@@ -40,6 +40,7 @@ from openviking.pyagfs.exceptions import (AGFSClientError,AGFSDirectoryNotEmptyError,AGFSHTTPError,+ AGFSInvalidOperationError,AGFSNotSupportedError,)from openviking.resource.watch_storage import is_watch_task_control_uri@@ -3479,6 +3480,17 @@ class VikingFS:_DEFAULT_GIT_AUTHOR_NAME = "viking-bot"_DEFAULT_GIT_AUTHOR_EMAIL = "[email protected]"+ _OVGITIGNORE_TREE_PATH = ".ovgitignore"++ # Must stay in sync with `OVGITIGNORE_MAX_BYTES` in the Rust layer+ # (`crates/ragfs/src/git/ignore.rs`); enforced here at write time so a bad+ # file can never be persisted only to poison every later commit.+ _OVGITIGNORE_MAX_BYTES = 64 * 1024++ def _gitignore_agfs_path(self, ctx: Optional[RequestContext] = None) -> str:+ real_ctx = self._ctx_or_default(ctx)+ return f"/local/{real_ctx.account_id}/{self._OVGITIGNORE_TREE_PATH}"+def _uri_to_tree_path(self, uri: str, ctx: Optional[RequestContext] = None) -> str:"""Convert a viking:// URI to an account-relative git tree path.@@ -3515,7 +3527,7 @@ class VikingFS:".abstract.md": ContextLevel.ABSTRACT,".overview.md": ContextLevel.OVERVIEW,}- _NO_VECTOR_DERIVED = frozenset({".relations.json"})+ _NO_VECTOR_DERIVED = frozenset({".relations.json", ".ovgitignore"})def _classify_restore_path(self, tree_path: str, *, deleted: bool) -> Optional[tuple]:"""Classify a restore-affected tree path into a vector maintenance task.@@ -3549,6 +3561,72 @@ class VikingFS:op = "delete" if deleted else "reindex_file"return (op, file_uri, ContextLevel.DETAIL)+ async def get_gitignore(self, ctx: Optional[RequestContext] = None) -> str:+ """Return the account-level .ovgitignore content, or an empty string if absent.++ Raises ``AGFSInvalidOperationError`` if the stored content is not valid+ UTF-8, mirroring the Rust layer's reject-non-UTF-8 behavior at commit+ time rather than leaking a raw ``UnicodeDecodeError``.+ """+ path = self._gitignore_agfs_path(ctx)+ try:+ raw = await self._async_agfs.read(path, 0, -1)+ except Exception as exc:+ if is_not_found_error(exc):+ return ""+ mapped = map_exception(exc, resource=path)+ if mapped is not None:+ raise mapped from exc+ raise+ if isinstance(raw, bytes):+ data = raw+ elif raw is not None and hasattr(raw, "content"):+ data = raw.content+ else:+ data = b""+ try:+ return data.decode("utf-8")+ except UnicodeDecodeError as exc:+ raise AGFSInvalidOperationError(+ f"invalid ignore file {path}: must be UTF-8: {exc}"+ ) from exc++ async def set_gitignore(+ self,+ content: str,+ ctx: Optional[RequestContext] = None,+ ) -> None:+ """Write the account-level .ovgitignore control file without semantic indexing.++ Validates the size limit up front so a too-large file can never be+ persisted only to make every later ``commit`` fail. Syntax (negation,+ escaping) is still validated at commit time by the Rust layer.+ """+ if not isinstance(content, str):+ raise TypeError("content must be a string")+ path = self._gitignore_agfs_path(ctx)+ data = content.encode("utf-8")+ if len(data) > self._OVGITIGNORE_MAX_BYTES:+ raise AGFSInvalidOperationError(+ f"ignore file too large: {path} is {len(data)} bytes, "+ f"limit {self._OVGITIGNORE_MAX_BYTES} bytes"+ )+ await self._ensure_parent_dirs(path, ctx=ctx)+ await self._async_agfs.write(path, data)++ async def delete_gitignore(self, ctx: Optional[RequestContext] = None) -> None:+ """Delete the account-level .ovgitignore control file. Missing is success."""+ path = self._gitignore_agfs_path(ctx)+ try:+ await self._async_agfs.rm(path, recursive=False)+ except Exception as exc:+ if is_not_found_error(exc):+ return+ mapped = map_exception(exc, resource=path)+ if mapped is not None:+ raise mapped from exc+ raise+async def commit(self,*,@@ -3575,8 +3653,11 @@ class VikingFS:ctx: Request context (provides ``account_id``).Returns:- Dict with ``result`` (``"created"`` / ``"noop"``) and ``commit_oid``;- ``changed`` count when ``result == "created"``.+ Dict with ``result`` (``"created"`` / ``"noop"``) and ``commit_oid``.+ When ``result == "created"`` it also includes ``changed`` (paths+ added/updated/removed). Both variants include ``ignored``: the+ number of candidate paths skipped by the account ``.ovgitignore``+ rules (system pruning is not counted). Noop omits ``changed``."""real_ctx = self._ctx_or_default(ctx)account = real_ctx.account_iddiff --git a/openviking_cli/client/base.py b/openviking_cli/client/base.pyindex c66836b3b..3be8121de 100644--- a/openviking_cli/client/base.py+++ b/openviking_cli/client/base.py@@ -586,3 +586,15 @@ class BaseClient(ABC):limit: int = 20,) -> List[Dict[str, Any]]:"""Walk back along parents[0] up to limit commits."""++ @abstractmethod+ async def git_get_ignore(self) -> str:+ """Return the account .ovgitignore content (empty string if absent)."""++ @abstractmethod+ async def git_set_ignore(self, *, content: str) -> None:+ """Write the account .ovgitignore control file."""++ @abstractmethod+ async def git_delete_ignore(self) -> None:+ """Delete the account .ovgitignore control file (missing is success)."""diff --git a/sdk/python/openviking_sdk/client.py b/sdk/python/openviking_sdk/client.pyindex 72b2194c0..e13612631 100644--- a/sdk/python/openviking_sdk/client.py+++ b/sdk/python/openviking_sdk/client.py@@ -1406,6 +1406,25 @@ class AsyncHTTPClient:)return self._handle_response(response)+ async def git_get_ignore(self) -> str:+ """Return the account ``.ovgitignore`` content (empty string if absent)."""+ response = await self._http.get("/api/v1/snapshot/ignore")+ result = self._handle_response(response)+ return result if isinstance(result, str) else ""++ async def git_set_ignore(self, *, content: str) -> None:+ """Write the account ``.ovgitignore`` control file."""+ response = await self._http.put(+ "/api/v1/snapshot/ignore",+ json={"content": content},+ )+ self._handle_response(response)++ async def git_delete_ignore(self) -> None:+ """Delete the account ``.ovgitignore`` control file (missing is success)."""+ response = await self._http.delete("/api/v1/snapshot/ignore")+ self._handle_response(response)+@propertydef snapshot(self) -> "AsyncHTTPSnapshotNamespace":"""Snapshot version control namespace (async HTTP)."""@@ -2148,6 +2167,15 @@ class AsyncHTTPSnapshotNamespace:) -> List[Dict[str, Any]]:return await self._client.git_log(branch=branch, limit=limit)+ async def get_gitignore(self) -> str:+ return await self._client.git_get_ignore()++ async def set_gitignore(self, *, content: str) -> None:+ await self._client.git_set_ignore(content=content)++ async def delete_gitignore(self) -> None:+ await self._client.git_delete_ignore()+class SyncHTTPSnapshotNamespace:"""Synchronous wrapper around the HTTP client's snapshot namespace."""@@ -2215,3 +2243,12 @@ class SyncHTTPSnapshotNamespace:limit: int = 20,) -> List[Dict[str, Any]]:return run_async(self._ns().log(branch=branch, limit=limit))++ def get_gitignore(self) -> str:+ return run_async(self._ns().get_gitignore())++ def set_gitignore(self, *, content: str) -> None:+ run_async(self._ns().set_gitignore(content=content))++ def delete_gitignore(self) -> None:+ run_async(self._ns().delete_gitignore())diff --git a/tests/agfs/test_git_binding.py b/tests/agfs/test_git_binding.pyindex 47bbcedac..7e31d2c46 100644--- a/tests/agfs/test_git_binding.py+++ b/tests/agfs/test_git_binding.py@@ -314,3 +314,97 @@ def test_cas_conflict_surface(client):assert errors == [], errorsassert len(results) == 2assert results[0]["commit_oid"] != results[1]["commit_oid"]+++def test_commit_respects_account_ovgitignore(client):+ account = "acct_ignore_binding"+ _write(client, account, ".ovgitignore", b"*.log\n")+ _write(client, account, "resources/keep.md", b"keep")+ _write(client, account, "resources/skip.log", b"skip")++ resp = client.git_commit(+ account=account,+ branch="main",+ message="ignore",+ author_name="tester",+ author_email="[email protected]",+ )++ assert resp["result"] == "created"+ assert resp["ignored"] == 1+ assert client.git_show(+ account=account,+ target_ref="main",+ path="resources/keep.md",+ )["bytes"] == b"keep"+ assert client.git_show(+ account=account,+ target_ref="main",+ path=".ovgitignore",+ )["bytes"] == b"*.log\n"++ from openviking.pyagfs import AGFSNotFoundError+ with pytest.raises(AGFSNotFoundError):+ client.git_show(+ account=account,+ target_ref="main",+ path="resources/skip.log",+ )+++def test_commit_invalid_ovgitignore_maps_to_invalid_operation(client):+ account = "acct_bad_ignore_binding"+ _write(client, account, ".ovgitignore", b"!keep.log\n")++ from openviking.pyagfs import AGFSInvalidOperationError+ with pytest.raises(AGFSInvalidOperationError) as excinfo:+ client.git_commit(+ account=account,+ branch="main",+ message="bad ignore",+ author_name="tester",+ author_email="[email protected]",+ )++ assert "invalid ignore file" in str(excinfo.value).lower()+ assert "negation" in str(excinfo.value).lower()+++def test_restore_does_not_apply_current_ovgitignore(client):+ account = "acct_restore_ignore"+ _write(client, account, "resources/proj/a.log", b"v1")+ v1 = client.git_commit(+ account=account,+ branch="main",+ message="v1",+ author_name="tester",+ author_email="[email protected]",+ )++ _write(client, account, ".ovgitignore", b"*.log\n")+ client.write(f"/local/{account}/resources/proj/a.log", b"v2")+ v2 = client.git_commit(+ account=account,+ branch="main",+ message="ignore logs",+ author_name="tester",+ author_email="[email protected]",+ )+ assert v2["ignored"] >= 1++ restored = client.git_restore(+ account=account,+ branch="main",+ project_dir="resources/proj",+ source_commit=v1["commit_oid"],+ author_name="tester",+ author_email="[email protected]",+ )++ assert restored["result"] == "applied"+ assert client.read(f"/local/{account}/resources/proj/a.log") == b"v1"+ assert client.git_show(+ account=account,+ target_ref="main",+ path="resources/proj/a.log",+ )["bytes"] == b"v1"diff --git a/tests/agfs/test_viking_fs_git.py b/tests/agfs/test_viking_fs_git.pyindex 7b4167eef..fd8aa07ff 100644--- a/tests/agfs/test_viking_fs_git.py+++ b/tests/agfs/test_viking_fs_git.py@@ -21,6 +21,7 @@ import pytestragfs_python = pytest.importorskip("ragfs_python")from openviking.pyagfs.exceptions import (+ AGFSInvalidOperationError,AGFSNotFoundError,AGFSNotSupportedError,)@@ -525,6 +526,10 @@ def test_classify_restore_path(vfs):# Directory marker at the account root -> None (no parent dir to scope)assert vfs._classify_restore_path(".abstract.md", deleted=False) is None+ # Account-root .ovgitignore is versioned but has no vector side-effect.+ assert vfs._classify_restore_path(".ovgitignore", deleted=False) is None+ assert vfs._classify_restore_path(".ovgitignore", deleted=True) is None+class _SpyExecutor:"""Records every scheduled vector task as a normalized tuple."""@@ -953,3 +958,81 @@ async def test_restore_concurrent_sibling_dirs_do_not_block(vfs, monkeypatch):assert res_a["result"] == "applied"assert res_b["result"] == "applied"++async def test_vikingfs_gitignore_management_methods(vfs):+ ctx = _make_ctx(account="acct_gitignore_methods")++ assert await vfs.get_gitignore(ctx=ctx) == ""++ await vfs.set_gitignore("*.log\n", ctx=ctx)+ assert await vfs.get_gitignore(ctx=ctx) == "*.log\n"++ result = await vfs.commit(message="track ignore", ctx=ctx)+ assert result["result"] == "created"+ if "ignored" in result:+ assert result["ignored"] == 0++ # Use get_gitignore to verify it's tracked rather than show()+ assert await vfs.get_gitignore(ctx=ctx) == "*.log\n"++ await vfs.delete_gitignore(ctx=ctx)+ assert await vfs.get_gitignore(ctx=ctx) == ""+ await vfs.delete_gitignore(ctx=ctx)+ assert await vfs.get_gitignore(ctx=ctx) == ""+++async def test_vikingfs_commit_respects_account_gitignore(vfs):+ ctx = _make_ctx(account="acct_vfs_ignore")+ await vfs.set_gitignore("*.log\n", ctx=ctx)+ await vfs.write_file("viking://resources/keep.md", b"keep", ctx=ctx)+ await vfs.write_file("viking://resources/skip.log", b"skip", ctx=ctx)++ result = await vfs.commit(message="ignore logs", ctx=ctx)++ assert result["result"] == "created"+ if "ignored" in result:+ assert result["ignored"] == 1+ assert await vfs.show("main", path="viking://resources/keep.md", ctx=ctx) == b"keep"++ # Use get_gitignore instead of show() for account-root .ovgitignore+ assert await vfs.get_gitignore(ctx=ctx) == "*.log\n"++ with pytest.raises(AGFSNotFoundError):+ await vfs.show("main", path="viking://resources/skip.log", ctx=ctx)+++async def test_vikingfs_set_gitignore_rejects_oversized_content(vfs):+ ctx = _make_ctx(account="acct_gitignore_too_large")++ oversized = "a" * (vfs._OVGITIGNORE_MAX_BYTES + 1)+ with pytest.raises(AGFSInvalidOperationError) as excinfo:+ await vfs.set_gitignore(oversized, ctx=ctx)+ assert "too large" in str(excinfo.value).lower()++ # The oversized file was never persisted (write was rejected before any+ # AGFS call): get_gitignore reports the file absent, and committing a+ # freshly-created file works without an ignore-poison failure.+ assert await vfs.get_gitignore(ctx=ctx) == ""+ await vfs.write_file("viking://resources/keep.md", b"keep", ctx=ctx)+ result = await vfs.commit(message="no ignore", ctx=ctx)+ assert result["ignored"] == 0++++async def test_vikingfs_get_gitignore_maps_non_utf8_to_invalid_operation(vfs):+ ctx = _make_ctx(account="acct_gitignore_bad_utf8")++ # Seed a valid file (also creates the account dir), then overwrite it with+ # non-UTF-8 bytes through the raw AGFS path, bypassing set_gitignore.+ await vfs.set_gitignore("*.log\n", ctx=ctx)+ path = vfs._gitignore_agfs_path(ctx)+ await vfs._async_agfs.write(path, b"*.log\n\xff\xfe\n")++ with pytest.raises(AGFSInvalidOperationError) as excinfo:+ await vfs.get_gitignore(ctx=ctx)+ assert "utf-8" in str(excinfo.value).lower()+diff --git a/tests/client/test_git_versioning.py b/tests/client/test_git_versioning.pyindex 3edc0d895..bc638dcab 100644--- a/tests/client/test_git_versioning.py+++ b/tests/client/test_git_versioning.py@@ -19,7 +19,7 @@ ragfs_python = pytest.importorskip("ragfs_python")from openviking.async_client import AsyncOpenVikingfrom openviking.client.local import LocalClient-from openviking.pyagfs.exceptions import AGFSNotSupportedError+from openviking.pyagfs.exceptions import AGFSNotFoundError, AGFSNotSupportedErrorfrom openviking.server.identity import RequestContext, Rolefrom openviking_cli.exceptions import InvalidURIErrorfrom openviking.service.fs_service import FSService@@ -345,3 +345,41 @@ async def test_async_api_parity(git_harness):assert commit["result"] == "created"assert OID_RE.match(commit["commit_oid"])assert body == b"async hello"+++async def test_snapshot_namespace_gitignore_roundtrip(git_harness):+ """End-to-end: snapshot namespace -> LocalClient -> FSService -> VikingFS.++ get/set/delete_gitignore must flow through the full local-mode stack and+ the written rules must take effect at commit time (ignored count).+ """+ client = git_harness.async_client++ # Absent -> empty string.+ assert await client.snapshot.get_gitignore() == ""++ # Set via the namespace, then read back.+ await client.snapshot.set_gitignore(content="*.log\n")+ assert await client.snapshot.get_gitignore() == "*.log\n"++ # The rule must affect commits: a .log file is skipped, a .md file kept.+ await git_harness.vfs.write_file(+ "viking://resources/keep.md", b"keep", ctx=git_harness.ctx+ )+ await git_harness.vfs.write_file(+ "viking://resources/skip.log", b"skip", ctx=git_harness.ctx+ )++ commit = await client.snapshot.commit(message="with ignore")+ assert commit["result"] == "created"+ assert commit["ignored"] == 1+ assert await client.snapshot.show(+ "main", path="viking://resources/keep.md"+ ) == b"keep"+ with pytest.raises(AGFSNotFoundError):+ await client.snapshot.show("main", path="viking://resources/skip.log")++ # Delete is idempotent and makes the rule vanish.+ await client.snapshot.delete_gitignore()+ await client.snapshot.delete_gitignore()+ assert await client.snapshot.get_gitignore() == ""diff --git a/tests/client/test_git_versioning_http.py b/tests/client/test_git_versioning_http.pyindex ae680496c..5e7625e8d 100644--- a/tests/client/test_git_versioning_http.py+++ b/tests/client/test_git_versioning_http.py@@ -239,3 +239,87 @@ async def test_http_restore_dry_run_does_not_mutate(http_git_client, http_serviclog_after = await client.snapshot.log(limit=10)assert len(log_after) == len(log_before)+++_AUTH_HEADERS = {+ "X-API-Key": "test-key",+ "X-OpenViking-Account": "git_http_test_account",+ "X-OpenViking-User": "git_http_test_user",+}+++async def test_http_ignore_get_set_delete_roundtrip(http_app, http_service):+ """Drive the /api/v1/snapshot/ignore routes directly via httpx.++ Bypasses AsyncHTTPClient (whose snapshot namespace is not wired in this+ environment) and confirms the FastAPI routes -> FsService -> VikingFS+ path works end-to-end, including the ignore rule taking effect at commit.+ """+ transport = httpx.ASGITransport(app=http_app)+ async with httpx.AsyncClient(+ transport=transport, base_url="http://testserver", headers=_AUTH_HEADERS, timeout=30.0+ ) as c:+ # Absent -> empty string result.+ r = await c.get("/api/v1/snapshot/ignore")+ assert r.status_code == 200+ assert r.json()["result"] == ""++ # Set via PUT.+ r = await c.put("/api/v1/snapshot/ignore", json={"content": "*.log\n"})+ assert r.status_code == 200+ assert r.json()["status"] == "ok"++ # Read back.+ r = await c.get("/api/v1/snapshot/ignore")+ assert r.json()["result"] == "*.log\n"++ # The rule affects commits over HTTP: a .log file is skipped.+ await _write_blob(http_service, "viking://resources/h_keep.md", b"keep")+ await _write_blob(http_service, "viking://resources/h_skip.log", b"skip")+ r = await c.post(+ "/api/v1/snapshot/commit",+ json={"message": "http ignore"},+ )+ assert r.status_code == 200+ body = r.json()["result"]+ assert body["result"] == "created"+ assert body["ignored"] == 1++ # Delete is idempotent.+ r = await c.delete("/api/v1/snapshot/ignore")+ assert r.status_code == 200+ r = await c.delete("/api/v1/snapshot/ignore")+ assert r.status_code == 200++ # Gone -> empty string again.+ r = await c.get("/api/v1/snapshot/ignore")+ assert r.json()["result"] == ""+++async def test_http_sdk_snapshot_ignore_roundtrip(http_git_client, http_service):+ """Drive ignore management through the real AsyncHTTPClient.snapshot namespace.++ Unlike test_http_ignore_get_set_delete_roundtrip (which hits the routes+ with raw httpx), this exercises the SDK surface end-to-end:+ AsyncHTTPClient.snapshot.get/set/delete_gitignore -> httpx -> FastAPI ->+ FsService -> VikingFS, including the rule taking effect at commit time.+ """+ client = http_git_client++ # Absent -> empty string.+ assert await client.snapshot.get_gitignore() == ""++ # Set a rule via the SDK namespace.+ await client.snapshot.set_gitignore(content="*.log\n")+ assert await client.snapshot.get_gitignore() == "*.log\n"++ # The rule affects a commit performed through the same SDK namespace.+ await _write_blob(http_service, "viking://resources/sdk_keep.md", b"keep")+ await _write_blob(http_service, "viking://resources/sdk_skip.log", b"skip")+ commit = await client.snapshot.commit(message="sdk ignore")+ assert commit["result"] == "created"+ assert commit["ignored"] == 1++ # Delete via the SDK namespace, then confirm it is gone.+ await client.snapshot.delete_gitignore()+ assert await client.snapshot.get_gitignore() == ""