Skip to content

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

feat(upload): respect root and nested `.gitignore` during filtering (#1812)

sentisso9b45c2149971
diff --git a/docs/en/api/02-resources.md b/docs/en/api/02-resources.md
index b62a5840c..f2695f5f3 100644
--- a/docs/en/api/02-resources.md
+++ b/docs/en/api/02-resources.md
@@ -31,7 +31,7 @@ OpenViking supports various resource types, categorized by functionality:
| Type | Resource Name | Description |
|------|---------------|-------------|
| Code Files | `*.py`, `*.js`, ... | Supports common programming languages (Python, JavaScript, Go, Rust, Java, etc.) |
-| Git Protocol Repository | `git://...` | Git URL, local directory, `.zip` package, automatically filters `.git`, `node_modules` and other directories |
+| Git Protocol Repository | `git://...` | Git URL, local directory, `.zip` package, respects `.gitignore` and automatically filters `.git`, `node_modules` and other directories |
| Git Code Hosting Platform | `https://github.com/{org}/{repo}` | URLs from GitHub, GitLab, Bitbucket and other code hosting platforms |
| Raw Files from Git Hosting | `https://github.com/{org}/{repo}/raw/{branch}/{path}` | Raw file download URLs from GitHub, GitLab, Bitbucket and other platforms |
@@ -157,6 +157,7 @@ This endpoint is the core entry point for resource management, supporting adding
- Raw HTTP calls for local files require first uploading via [temp_upload](#temp_upload) to obtain `temp_file_id`
- When `to` is specified and the target already exists, triggers incremental update
- `watch_interval` only takes effect when `to` is provided
+- For local directory inputs, scanning respects `.gitignore` files (root and nested) with standard Git semantics; `ignore_dirs`, `include`, and `exclude` further refine what is ingested.
#### 3. Usage Examples
diff --git a/docs/en/concepts/06-extraction.md b/docs/en/concepts/06-extraction.md
index cf387e372..7809e0efb 100644
--- a/docs/en/concepts/06-extraction.md
+++ b/docs/en/concepts/06-extraction.md
@@ -26,7 +26,7 @@ Parser handles document format conversion and structuring, creating file structu
| Plain text | TextParser | .txt | Supported |
| PDF | PDFParser | .pdf | Supported |
| HTML | HTMLParser | .html, .htm | Supported |
-| Code | CodeRepositoryParser | .py, .js, .go, etc. | |
+| Code | CodeRepositoryParser | .py, .js, .go, etc. | Respects `.gitignore` and ignores common non-code directories |
| Image | ImageParser | .png, .jpg, etc. | |
| Video | VideoParser | .mp4, .avi, etc. | |
| Audio | AudioParser | .mp3, .wav, etc. | |
diff --git a/docs/en/getting-started/02-quickstart.md b/docs/en/getting-started/02-quickstart.md
index f295a2c8e..9f42ecf62 100644
--- a/docs/en/getting-started/02-quickstart.md
+++ b/docs/en/getting-started/02-quickstart.md
@@ -151,6 +151,7 @@ try:
client.initialize()
# Add resource (supports URL, file, or directory)
+ # Local directory scans respect .gitignore by default.
add_result = client.add_resource(
path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md"
)
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index 70ebb15ac..7a101a2a1 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -996,6 +996,8 @@ Config file for the HTTP client (`SyncHTTPClient` / `AsyncHTTPClient`) and CLI t
| `upload.include` | Default include patterns for `add-resource` (CSV) | `null` |
| `upload.exclude` | Default exclude patterns for `add-resource` (CSV) | `null` |
+Local directory uploads respect `.gitignore` files (root and nested). `ignore_dirs/include/exclude` apply on top of that.
+
CLI flags can override these identity fields per command:
```bash
diff --git a/docs/zh/api/02-resources.md b/docs/zh/api/02-resources.md
index a86c3da76..4ed641273 100644
--- a/docs/zh/api/02-resources.md
+++ b/docs/zh/api/02-resources.md
@@ -28,7 +28,7 @@ OpenViking 支持多种资源类型,按照功能分类如下:
| 类型 | 资源名 | 说明 |
|------|--------|------|
| 代码文件 | `*.py`, `*.js`, ... | 支持常见编程语言(Python, JavaScript, Go, Rust, Java 等) |
-| Git 协议代码仓库 | `git://...` | Git URL, 本地目录, `.zip` 包,会自动过滤 `.git`, `node_modules` 等目录 |
+| Git 协议代码仓库 | `git://...` | Git URL, 本地目录, `.zip` 包,遵循 `.gitignore` 并自动过滤 `.git`, `node_modules` 等目录 |
| Git 代码托管平台 | `https://github.com/{org}/{repo}` | GitHub, GitLab, Bitbucket 等代码托管平台的 URL |
| Git 代码托管平台上的 raw 文件 | `https://github.com/{org}/{repo}/raw/{branch}/{path}` | GitHub, GitLab, Bitbucket 等代码托管平台的 raw 文件下载 URL |
@@ -150,6 +150,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
- `to` 和 `parent` 都可用于指定目标路径,但不能同时使用;指定 `to` 且目标已存在时,触发增量更新。
- `path` 和 `temp_file_id` 不能同时指定,上传本地文件需要先通过 [temp_upload](#temp_upload) 上传获取 `temp_file_id`,在 SDK 和 CLI 中已经封装好。
- `watch_interval` 仅在指定 `to` 时生效
+- 本地目录输入会遵循 `.gitignore`(根目录和子目录,标准 Git 语义);`ignore_dirs`、`include`、`exclude` 会在此基础上进一步过滤。
#### 3. 使用示例
diff --git a/docs/zh/concepts/06-extraction.md b/docs/zh/concepts/06-extraction.md
index 69d379be7..72f789267 100644
--- a/docs/zh/concepts/06-extraction.md
+++ b/docs/zh/concepts/06-extraction.md
@@ -25,7 +25,7 @@ Parser 负责文档格式转换和结构化,在临时目录创建文件结构
| 纯文本 | TextParser | .txt | 已支持 |
| PDF | PDFParser | .pdf | 已支持 |
| HTML | HTMLParser | .html, .htm | 已支持 |
-| 代码 | CodeRepositoryParser | github 代码仓库等 | 已支持 |
+| 代码 | CodeRepositoryParser | github 代码仓库等 | 遵循 `.gitignore` 并忽略常见非代码目录 |
| 图片 | ImageParser | .png, .jpg 等 | |
| 视频 | AudioParser | .mp3, .wav 等 | |
| 音频 | VideoParser | .mp4, .avi 等 | |
diff --git a/docs/zh/getting-started/02-quickstart.md b/docs/zh/getting-started/02-quickstart.md
index 357d75593..ebb2ce8c7 100644
--- a/docs/zh/getting-started/02-quickstart.md
+++ b/docs/zh/getting-started/02-quickstart.md
@@ -151,6 +151,7 @@ try:
client.initialize()
# Add resource (supports URL, file, or directory)
+ # Local directory scans respect .gitignore by default.
add_result = client.add_resource(
path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md"
)
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index d3312aff9..e9ce9fd59 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -970,6 +970,8 @@ HTTP 客户端(`SyncHTTPClient` / `AsyncHTTPClient`)和 CLI 工具连接远
| `upload.include` | `add-resource` 默认包含模式(CSV) | `null` |
| `upload.exclude` | `add-resource` 默认排除模式(CSV) | `null` |
+本地目录上传会默认遵循 `.gitignore`(根目录和子目录,含 `!` 反向规则)。`ignore_dirs/include/exclude` 会在此基础上进一步过滤。
+
也可以在单次命令里用 CLI 参数覆盖这些身份字段:
```bash
diff --git a/openviking/parse/directory_scan.py b/openviking/parse/directory_scan.py
index 6b255baf9..797a04219 100644
--- a/openviking/parse/directory_scan.py
+++ b/openviking/parse/directory_scan.py
@@ -14,6 +14,7 @@ from dataclasses import dataclass, field
from pathlib import Path
from typing import List, Optional, Set, Union
+from openviking.parse.gitignore import GitignoreMatcher
from openviking.parse.parsers.constants import IGNORE_DIRS
from openviking.parse.parsers.upload_utils import is_text_file
from openviking.parse.registry import ParserRegistry, get_registry
@@ -183,8 +184,8 @@ def scan_directory(
"""
Traverse directory tree and classify every file (phase-one validation).
- - Skips directories in IGNORE_DIRS (or ignore_dirs), and skips dot files,
- symlinks, and empty files (they are not included in any list).
+ - Skips directories in IGNORE_DIRS (or ignore_dirs), gitignored paths,
+ and skips dot files, symlinks, and empty files (they are not included in any list).
- If include is set, only files whose name matches one of the glob patterns are considered
(e.g. include="*.pdf,*.md"). If exclude is set, files matching any exclude pattern are
skipped (e.g. exclude="drafts/" for path prefix, or "*.tmp" for name glob).
@@ -220,6 +221,7 @@ def scan_directory(
effective_registry = registry if registry is not None else get_registry()
include_patterns = _parse_patterns(include)
exclude_patterns = _parse_patterns(exclude)
+ gitignore_matcher = GitignoreMatcher(root)
# Normalize ignore_dirs:
# - If caller passed a comma-separated string (common from CLI/HTTP),
@@ -235,6 +237,7 @@ def scan_directory(
result = DirectoryScanResult(root=root)
for dir_path_str, dir_names, file_names in os.walk(root, topdown=True):
dir_path = Path(dir_path_str)
+ dir_spec = gitignore_matcher.spec_for_dir(dir_path)
# Prune subdirectories in-place so os.walk won't descend into them
kept = []
@@ -245,8 +248,16 @@ def scan_directory(
skipped_path = str(sub.relative_to(root))
skipped_path = _normalize_rel_path(skipped_path)
result.skipped.append(f"{skipped_path} ({reason})")
- else:
- kept.append(d)
+ continue
+
+ if gitignore_matcher.is_ignored_dir(sub, dir_spec):
+ skipped_path = str(sub.relative_to(root))
+ skipped_path = _normalize_rel_path(skipped_path)
+ result.skipped.append(f"{skipped_path} (gitignore)")
+ continue
+
+ kept.append(d)
+
dir_names[:] = kept
for name in file_names:
@@ -261,6 +272,9 @@ def scan_directory(
if skip:
result.skipped.append(f"{rel_path} ({reason})")
continue
+ if gitignore_matcher.is_ignored_file(file_path, dir_spec):
+ result.skipped.append(f"{rel_path} (gitignore)")
+ continue
if include_patterns and not _matches_include(name, include_patterns):
result.skipped.append(f"{rel_path} (excluded by include filter)")
diff --git a/openviking/parse/gitignore.py b/openviking/parse/gitignore.py
new file mode 100644
index 000000000..3351cdb30
--- /dev/null
+++ b/openviking/parse/gitignore.py
@@ -0,0 +1,142 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Gitignore-aware matching helpers for directory scanning."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional
+
+from pathspec import GitIgnoreSpec
+
+
+def _normalize_rel_path(rel_path: str) -> str:
+ return rel_path.replace("\\", "/")
+
+
+def _is_comment_line(line: str) -> bool:
+ return line.startswith("#")
+
+
+def _transform_gitignore_line(line: str, base_rel: str) -> str:
+ """
+ Transform a gitignore pattern line from a nested .gitignore to root-relative.
+
+ - Patterns without '/' should match anywhere under base_rel.
+ - Patterns with '/' are scoped to base_rel.
+ - Leading '/' anchors to base_rel.
+ """
+ raw = line.rstrip("\n")
+ if not raw or _is_comment_line(raw):
+ return raw
+
+ negated = False
+ pattern = raw
+ if raw.startswith("!"):
+ negated = True
+ pattern = raw[1:]
+
+ if not base_rel:
+ return raw
+
+ scoped = pattern
+ if scoped.startswith("/"):
+ scoped = scoped.lstrip("/")
+ scoped = f"{base_rel}/{scoped}" if scoped else base_rel
+ elif "/" in scoped:
+ scoped = f"{base_rel}/{scoped}"
+ else:
+ scoped = f"{base_rel}/**/{scoped}" if scoped else base_rel
+
+ return f"!{scoped}" if negated else scoped
+
+
+@dataclass
+class GitignoreMatcher:
+ """
+ Helper class for matching files and directories against gitignore specs.
+ It maintains an in-memory cache of gitignore specs per directory for faster matching.
+ """
+
+ root: Path
+ _spec_cache: Dict[Path, Optional[GitIgnoreSpec]]
+
+ def __init__(self, root: Path) -> None:
+ self.root = root.resolve()
+ self._spec_cache = {}
+
+ def spec_for_dir(self, dir_path: Path) -> Optional[GitIgnoreSpec]:
+ """
+ Resolve the gitignore spec for the given directory (including parent specs recursively).
+ """
+ dir_path = dir_path.resolve()
+ if dir_path in self._spec_cache:
+ return self._spec_cache[dir_path]
+
+ parent_spec = None
+ # try to resolve all parent specs recursively
+ if dir_path != self.root:
+ parent_spec = self.spec_for_dir(dir_path.parent)
+
+ local_spec = self._load_local_spec(dir_path)
+
+ if parent_spec and local_spec:
+ spec = parent_spec + local_spec
+ else:
+ spec = local_spec or parent_spec
+
+ self._spec_cache[dir_path] = spec
+ return spec
+
+ def is_ignored_file(self, file_path: Path, spec: Optional[GitIgnoreSpec]) -> bool:
+ if not spec:
+ return False
+
+ rel_path = self._rel_path(file_path)
+ return spec.match_file(rel_path)
+
+ def is_ignored_dir(self, dir_path: Path, spec: Optional[GitIgnoreSpec]) -> bool:
+ if not spec:
+ return False
+
+ rel_path = self._rel_path(dir_path)
+ return spec.match_file(f"{rel_path}/")
+
+ def _rel_path(self, path: Path) -> str:
+ try:
+ rel = path.relative_to(self.root)
+ except ValueError:
+ rel = path
+
+ rel_norm = _normalize_rel_path(str(rel))
+ return "" if rel_norm == "." else rel_norm
+
+ def _load_local_spec(self, dir_path: Path) -> Optional[GitIgnoreSpec]:
+ """
+ Load the local .gitignore spec in the given directory.
+ """
+ gitignore_path = dir_path / ".gitignore"
+ if not gitignore_path.is_file():
+ return None
+ try:
+ content = gitignore_path.read_text(encoding="utf-8", errors="ignore")
+ except OSError:
+ return None
+
+ lines = content.splitlines()
+ if not lines:
+ return None
+
+ base_rel = self._rel_path(dir_path)
+ transformed = self._transform_lines(lines, base_rel)
+ if not transformed:
+ return None
+
+ return GitIgnoreSpec.from_lines(transformed)
+
+ def _transform_lines(self, lines: Iterable[str], base_rel: str) -> List[str]:
+ if not base_rel:
+ return list(lines)
+
+ return [_transform_gitignore_line(line, base_rel) for line in lines]
diff --git a/openviking/parse/parsers/README.md b/openviking/parse/parsers/README.md
index ceffac297..9fb5637fb 100644
--- a/openviking/parse/parsers/README.md
+++ b/openviking/parse/parsers/README.md
@@ -141,7 +141,7 @@ L1: """
### 5. CodeRepositoryParser (`code/*`)
**支持来源**: github 代码仓库等
-代码解析器,支持语法高亮和代码结构分析。能识别函数、类、方法等代码元素。
+代码解析器,支持语法高亮和代码结构分析。能识别函数、类、方法等代码元素,遵循 `.gitignore` 并忽略常见非代码目录。
### 6. MediaParser (`media/*.py`)
diff --git a/openviking/parse/parsers/code/README.md b/openviking/parse/parsers/code/README.md
index 26b13cf3b..dde00ebe5 100644
--- a/openviking/parse/parsers/code/README.md
+++ b/openviking/parse/parsers/code/README.md
@@ -79,7 +79,7 @@ viking://resources/github/volcengine/OpenViking/
2. 对于代码仓库中的文档,除了图片以外,不要让大模型处理文本以外的其他模态内容,如视频、音频等。
- **说明**:".md"、".txt"、".rst" 等纯文本格式的文档文件**会被处理**,因为它们属于"文本内容"
- **排除**:视频(.mp4, .mov, .avi 等)、音频(.mp3, .wav, .m4a 等)等非文本格式**不会被处理**
-3. 可以忽略代码仓库中的隐藏文件,如 .git 文件夹下面的内容,__pycache__ 文件夹下面的内容等。
+3. 可以忽略代码仓库中的隐藏文件,如 .git 文件夹下面的内容,__pycache__ 文件夹下面的内容等;同时遵循 `.gitignore` 规则。
4. 对于代码仓库中的符号链接,我们应当忽略并记录其目标路径,而不是直接解析符号链接。
5. 对于代码仓库中的子目录,我们应当递归地处理,确保所有包含代码的目录,都被正确映射到 Viking URI 路径。
diff --git a/openviking/parse/parsers/code/code.py b/openviking/parse/parsers/code/code.py
index 62c37fd55..0541280c0 100644
--- a/openviking/parse/parsers/code/code.py
+++ b/openviking/parse/parsers/code/code.py
@@ -51,7 +51,7 @@ class CodeRepositoryParser(BaseParser):
Features:
- Shallow clone for Git repositories
- - Automatic filtering of non-code directories (.git, node_modules, etc.)
+ - Automatic filtering based on .gitignore and of non-code directories (.git, node_modules, etc.)
- Direct mapping to VikingFS temp directory
- Preserves directory structure without chunking
diff --git a/openviking/parse/parsers/upload_utils.py b/openviking/parse/parsers/upload_utils.py
index d4139f6c5..24a759ac3 100644
--- a/openviking/parse/parsers/upload_utils.py
+++ b/openviking/parse/parsers/upload_utils.py
@@ -8,6 +8,7 @@ import re
from pathlib import Path
from typing import Any, List, Optional, Set, Tuple, Union
+from openviking.parse.gitignore import GitignoreMatcher
from openviking.parse.parsers.constants import (
ADDITIONAL_TEXT_EXTENSIONS,
CODE_EXTENSIONS,
@@ -219,6 +220,7 @@ async def upload_directory(
effective_ignore_extensions = (
ignore_extensions if ignore_extensions is not None else IGNORE_EXTENSIONS
)
+ gitignore_matcher = GitignoreMatcher(local_dir)
warnings: List[str] = []
@@ -227,11 +229,26 @@ async def upload_directory(
parent_uris: Set[str] = {viking_uri_base}
for root, dirs, files in os.walk(local_dir):
- dirs[:] = [
- d for d in dirs if not should_skip_directory(d, ignore_dirs=effective_ignore_dirs)
- ]
+ dir_path = Path(root)
+ dir_spec = gitignore_matcher.spec_for_dir(dir_path)
+
+ # Prune subdirectories in-place so os.walk won't descend into them
+ kept = []
+ for d in dirs:
+ sub_dir_path = dir_path / d
+ should_skip = should_skip_directory(d, ignore_dirs=effective_ignore_dirs)
+ if should_skip:
+ continue
+
+ if gitignore_matcher.is_ignored_dir(sub_dir_path, dir_spec):
+ continue
+
+ kept.append(d)
+
+ dirs[:] = kept
+
for file_name in files:
- file_path = Path(root) / file_name
+ file_path = dir_path / file_name
should_skip, _ = should_skip_file(
file_path,
max_file_size=max_file_size,
@@ -239,6 +256,10 @@ async def upload_directory(
)
if should_skip:
continue
+
+ if gitignore_matcher.is_ignored_file(file_path, dir_spec):
+ continue
+
rel_path_str = str(file_path.relative_to(local_dir)).replace(os.sep, "/")
try:
safe_rel = _sanitize_rel_path(rel_path_str)
diff --git a/pyproject.toml b/pyproject.toml
index 41fc676f7..1210e4e32 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -82,6 +82,7 @@ dependencies = [
"argon2-cffi>=23.0.0",
"lark-oapi>=1.5.3",
"mcp>=1.27.0",
+ "pathspec>=1.1.1",
]
diff --git a/tests/parse/test_directory_scan.py b/tests/parse/test_directory_scan.py
index 1dc25c001..d152f91f2 100644
--- a/tests/parse/test_directory_scan.py
+++ b/tests/parse/test_directory_scan.py
@@ -389,6 +389,75 @@ class TestIncludeExclude:
assert "excluded by include" in skipped_reasons or "excluded by exclude" in skipped_reasons
+class TestGitignoreHandling:
+ """Test gitignore-aware exclusion in scan_directory."""
+
+ def test_respects_root_gitignore(self, tmp_path: Path, registry: ParserRegistry) -> None:
+ (tmp_path / ".gitignore").write_text("*.log\n", encoding="utf-8")
+ (tmp_path / "keep.txt").write_text("ok", encoding="utf-8")
+ (tmp_path / "skip.log").write_text("no", encoding="utf-8")
+
+ result = scan_directory(tmp_path, registry=registry, strict=False)
+ rel_paths = [f.rel_path for f in result.processable + result.unsupported]
+
+ assert "keep.txt" in rel_paths
+ assert "skip.log" not in rel_paths
+ assert any("skip.log (gitignore)" in s for s in result.skipped)
+
+ def test_respects_nested_gitignore(self, tmp_path: Path, registry: ParserRegistry) -> None:
+ (tmp_path / ".gitignore").write_text("*.log\n", encoding="utf-8")
+
+ (tmp_path / "src").mkdir()
+ (tmp_path / "src" / "skip.log").write_text("no", encoding="utf-8")
+ (tmp_path / "src" / "keep.tmp").write_text("ok", encoding="utf-8")
+
+ (tmp_path / "src" / "sub").mkdir()
+ (tmp_path / "src" / "sub" / ".gitignore").write_text("*.tmp\n", encoding="utf-8")
+ (tmp_path / "src" / "sub" / "keep.txt").write_text("ok", encoding="utf-8")
+ (tmp_path / "src" / "sub" / "skip.log").write_text("no", encoding="utf-8")
+ (tmp_path / "src" / "sub" / "skip.tmp").write_text("no", encoding="utf-8")
+
+ result = scan_directory(tmp_path, registry=registry, strict=False)
+ rel_paths = [f.rel_path for f in result.processable + result.unsupported]
+
+ # .tmp is accepted in src/
+ assert "src/keep.tmp" in rel_paths
+ assert "src/skip.log" not in rel_paths
+ assert "src/sub/keep.txt" in rel_paths
+ assert "src/sub/skip.tmp" not in rel_paths
+ # .tmp is no longer accepted in src/sub/ due to nested gitignore
+ assert "src/sub/skip.log" not in rel_paths
+ assert any("src/skip.log (gitignore)" in s for s in result.skipped)
+ assert any("src/sub/skip.tmp (gitignore)" in s for s in result.skipped)
+ assert any("src/sub/skip.log (gitignore)" in s for s in result.skipped)
+
+ def test_respects_negation(self, tmp_path: Path, registry: ParserRegistry) -> None:
+ (tmp_path / ".gitignore").write_text("*.tmp\n!important.tmp\n", encoding="utf-8")
+ (tmp_path / "a.tmp").write_text("no", encoding="utf-8")
+ (tmp_path / "important.tmp").write_text("yes", encoding="utf-8")
+
+ result = scan_directory(tmp_path, registry=registry, strict=False)
+ rel_paths = [f.rel_path for f in result.processable + result.unsupported]
+
+ assert "a.tmp" not in rel_paths
+ assert "important.tmp" in rel_paths
+ skipped_reasons = " ".join(result.skipped)
+ assert "gitignore" in skipped_reasons
+
+ def test_ignored_directory_is_pruned(self, tmp_path: Path, registry: ParserRegistry) -> None:
+ (tmp_path / ".gitignore").write_text("generated/\n", encoding="utf-8")
+ (tmp_path / "generated").mkdir()
+ (tmp_path / "generated" / "skip.txt").write_text("no", encoding="utf-8")
+ (tmp_path / "keep.txt").write_text("ok", encoding="utf-8")
+
+ result = scan_directory(tmp_path, registry=registry, strict=False)
+ rel_paths = [f.rel_path for f in result.processable + result.unsupported]
+
+ assert "keep.txt" in rel_paths
+ assert "generated/skip.txt" not in rel_paths
+ assert any("generated (gitignore)" in s for s in result.skipped)
+
+
class TestClassifiedFileAndResult:
"""Test ClassifiedFile and DirectoryScanResult types."""
diff --git a/tests/test_upload_utils.py b/tests/test_upload_utils.py
index 61c2bf712..1fa8f81d8 100644
--- a/tests/test_upload_utils.py
+++ b/tests/test_upload_utils.py
@@ -375,6 +375,18 @@ class TestUploadDirectory:
# Most files are > 5 bytes, so fewer uploads
assert count < 4
+ @pytest.mark.asyncio
+ async def test_respects_gitignore(self, tmp_path: Path, viking_fs: FakeVikingFS) -> None:
+ (tmp_path / ".gitignore").write_text("*.tmp\n", encoding="utf-8")
+ (tmp_path / "keep.txt").write_text("ok", encoding="utf-8")
+ (tmp_path / "skip.tmp").write_text("no", encoding="utf-8")
+
+ count, _ = await upload_directory(tmp_path, "viking://temp/gi", viking_fs)
+
+ assert count == 1
+ assert "viking://temp/gi/keep.txt" in viking_fs.files
+ assert "viking://temp/gi/skip.tmp" not in viking_fs.files
+
# ---------------------------------------------------------------------------
# detect_and_convert_encoding (additional edge cases)
diff --git a/uv.lock b/uv.lock
index 40ef8b075..d1a92ac01 100644
--- a/uv.lock
+++ b/uv.lock
@@ -3513,6 +3513,7 @@ dependencies = [
{ name = "opentelemetry-exporter-otlp-proto-http" },
{ name = "opentelemetry-instrumentation-asyncio" },
{ name = "opentelemetry-sdk" },
+ { name = "pathspec" },
{ name = "pdfminer-six" },
{ name = "pdfplumber" },
{ name = "protobuf" },
@@ -3756,6 +3757,7 @@ requires-dist = [
{ name = "pandas", marker = "extra == 'benchmark'", specifier = ">=2.0.0" },
{ name = "pandas", marker = "extra == 'eval'", specifier = ">=2.0.0" },
{ name = "pandas", marker = "extra == 'test'", specifier = ">=2.0.0" },
+ { name = "pathspec", specifier = ">=1.1.1" },
{ name = "pdfminer-six", specifier = ">=20251230" },
{ name = "pdfplumber", specifier = ">=0.10.0" },
{ name = "prompt-toolkit", marker = "extra == 'bot'", specifier = ">=3.0.0" },
@@ -4107,11 +4109,11 @@ wheels = [
[[package]]
name = "pathspec"
-version = "1.0.4"
+version = "1.1.1"
source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/fa/36/e27608899f9b8d4dff0617b2d9ab17ca5608956ca44461ac14ac48b44015/pathspec-1.0.4.tar.gz", hash = "sha256:0210e2ae8a21a9137c0d470578cb0e595af87edaa6ebf12ff176f14a02e0e645", size = 131200, upload-time = "2026-01-27T03:59:46.938Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/5a/82/42f767fc1c1143d6fd36efb827202a2d997a375e160a71eb2888a925aac1/pathspec-1.1.1.tar.gz", hash = "sha256:17db5ecd524104a120e173814c90367a96a98d07c45b2e10c2f3919fff91bf5a", size = 135180, upload-time = "2026-04-27T01:46:08.907Z" }
wheels = [
- { url = "https://files.pythonhosted.org/packages/ef/3c/2c197d226f9ea224a9ab8d197933f9da0ae0aac5b6e0f884e2b8d9c8e9f7/pathspec-1.0.4-py3-none-any.whl", hash = "sha256:fb6ae2fd4e7c921a165808a552060e722767cfa526f99ca5156ed2ce45a5c723", size = 55206, upload-time = "2026-01-27T03:59:45.137Z" },
+ { url = "https://files.pythonhosted.org/packages/f1/d9/7fb5aa316bc299258e68c73ba3bddbc499654a07f151cba08f6153988714/pathspec-1.1.1-py3-none-any.whl", hash = "sha256:a00ce642f577bf7f473932318056212bc4f8bfdf53128c78bbd5af0b9b20b189", size = 57328, upload-time = "2026-04-27T01:46:07.06Z" },
]
[[package]]