Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

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.rs
index 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", &params).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.rs
index 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.rs
index 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.rs
index 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.rs
index 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) -> PyResu
CommitResponse::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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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. Uses
diff --git a/crates/ragfs/src/git/types.rs b/crates/ragfs/src/git/types.rs
index 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.rs
index 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.md
index 041a066ed..7939f7e84 100644
--- a/docs/design/git-version-control-design.md
+++ b/docs/design/git-version-control-design.md
@@ -171,6 +171,8 @@ sequenceDiagram
L0/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.md
index 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 Flow
A 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 Documentation
diff --git a/docs/en/guides/15-snapshot.md b/docs/en/guides/15-snapshot.md
index 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 Documentation
diff --git a/docs/zh/api/11-snapshot.md b/docs/zh/api/11-snapshot.md
index 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.md
index 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.py
index 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.py
index 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.py
index 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"] = paths
data = 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.py
index 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.py
index 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"]),
},
)
+
+
+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
+
+
+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)
+
+
+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.py
index 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.py
index 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.py
index 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_id
diff --git a/openviking_cli/client/base.py b/openviking_cli/client/base.py
index 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.py
index 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)
+
@property
def 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.py
index 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 == [], errors
assert len(results) == 2
assert 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.py
index 7b4167eef..fd8aa07ff 100644
--- a/tests/agfs/test_viking_fs_git.py
+++ b/tests/agfs/test_viking_fs_git.py
@@ -21,6 +21,7 @@ import pytest
ragfs_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.py
index 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 AsyncOpenViking
from openviking.client.local import LocalClient
-from openviking.pyagfs.exceptions import AGFSNotSupportedError
+from openviking.pyagfs.exceptions import AGFSNotFoundError, AGFSNotSupportedError
from openviking.server.identity import RequestContext, Role
from openviking_cli.exceptions import InvalidURIError
from 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.py
index 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_servic
log_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() == ""