Incremental & Diff Scans

Scan only changed files instead of your entire codebase. Incremental scanning is perfect for PR checks and fast feedback during development.

Incremental Scans

Scan only files changed since the last commit:

oculum scan --incremental

This uses git diff to identify changed files and only scans those.

How It Works

1. Oculum queries Git for changed files
2. Only those files are scanned
3. Results show findings in changed code only

Benefits

• Faster scans — Focus on new code, not the entire codebase
• Relevant results — See findings for the code you're working on
• Lower cost — Fewer files means lower API usage

---

Diff Against a Branch

Compare your current code against a specific branch:

# Compare against main
oculum scan --diff main

# Compare against develop
oculum scan --diff develop

# Compare against origin/main
oculum scan --diff origin/main

This is useful for PR reviews and pre-merge checks.

---

Diff Against a Commit

Compare against a specific commit:

# Compare against a commit hash
oculum scan --diff abc1234

# Compare against HEAD~3
oculum scan --diff HEAD~3

---

Baseline Mode

Track progress over time by comparing against a baseline:

# Create a baseline
oculum baseline create

# Scan and show only new findings
oculum scan --new

The --new flag shows only findings that aren't in the baseline.

See Baselines for details.

---

CI/CD Usage

Pull Request Checks

Fast feedback on PRs by scanning only changed files:

# GitHub Actions
- uses: oculum/scan-action@v1
  with:
    api-key: ${{ secrets.OCULUM_API_KEY }}
    incremental: 'true'
    diff-base: ${{ github.base_ref }}

Or with the CLI:

# In CI environment
oculum scan --diff $BASE_BRANCH --fail-on high

Main Branch Scans

Full scans on main branch for comprehensive coverage:

oculum scan --depth verified --fail-on high

Recommended Strategy

---

Combining with Other Options

Incremental + Verified

oculum scan --incremental --depth verified

Fast + accurate — scans only changed files with AI validation.

Incremental + Quiet

oculum scan --incremental --quiet --fail-on high

Minimal CI output, fast feedback.

Incremental + JSON Output

oculum scan --incremental --format json --output pr-scan.json

Machine-readable output for PR comments or dashboards.

---

Limitations

Git Repository Required

Incremental scans require a Git repository:

Error: Not a git repository. Incremental scans require git.

Staged vs Committed Changes

--incremental scans files changed since the last commit, not staged changes.

To scan staged files:

git diff --cached --name-only | xargs oculum scan

File Renames

When files are renamed, both old and new paths are considered changed.

Binary Files

Binary files are always skipped, even if changed.

---

Performance Comparison

Incremental scans provide 10-20x speedup for typical PR workflows.

---

Configuration

Set incremental as the default in your config:

{
  "profiles": {
    "pr": {
      "incremental": true,
      "depth": "local",
      "failOn": "critical"
    },
    "main": {
      "depth": "verified",
      "failOn": "high"
    }
  }
}

# Use PR profile for incremental
oculum scan -p pr

# Use main profile for full scan
oculum scan -p main

---

Troubleshooting

"No files to scan"

If no changed files are found:

1. Check you're in a Git repository
2. Verify there are actual changes: git status
3. The diff base might be wrong — try --diff main

Scanning Too Many Files

If incremental scans are slow:

1. Check your diff base: git diff --name-only main
2. Large diffs might be from merge commits
3. Consider using --include to focus on specific paths

Missing Findings

Incremental scans only show findings in changed files. For complete coverage, run a full scan periodically.

---

Related

• Baselines — Track findings over time
• CI/CD Setup — CI integration patterns
• Targeting Files — Include/exclude patterns