Incremental Scanning

Incremental scanning with the --changed flag scans only files that have been modified, staged, or added in your git repository. This dramatically speeds up scans in development workflows and CI pipelines.

Quick Start

Scan only git-changed files:

aguara scan --changed .

Aguara scans:

Staged files: Changes added with git add
Unstaged files: Modified but not yet staged
Untracked files: New files not yet committed

How It Works

Git Integration

Aguara runs these git commands to detect changes:

# 1. Check if git is available
which git

# 2. Check if we're in a git repo
git rev-parse --git-dir

# 3. Get tracked changes (staged + unstaged)
git diff --name-only HEAD

# 4. Get untracked files
git ls-files --others --exclude-standard

All files from steps 3 and 4 are scanned.

Fallback for New Repos

In repositories with no commits yet (e.g., git init but no git commit):

# Falls back to staged files only
git diff --name-only --cached

No Git? No Problem

If git is not installed or the directory is not a git repository:

--changed is silently ignored
Aguara scans all files (standard behavior)
No error is thrown

Use Cases

1. Pre-Commit Hook

Scan only changed files before committing:

# .git/hooks/pre-commit
#!/bin/bash
aguara scan --changed --fail-on high --no-color

Generate this hook automatically:

aguara init --hook

2. Pull Request CI

Scan only files modified in a PR:

# .github/workflows/pr-check.yml
name: Security Scan (Changed Files)

on:
  pull_request:

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # needed for git diff

      - name: Scan changed files
        run: |
          curl -fsSL https://raw.githubusercontent.com/garagon/aguara/main/install.sh | bash
          aguara scan --changed --ci

3. Development Workflow

While editing skills or MCP servers, get instant feedback:

# Edit files...
vim skills/deploy.md

# Quick scan
aguara scan --changed --verbose

Only scans skills/deploy.md (and any other modified files).

4. Monorepo Optimization

In large repos with hundreds of skills:

# Full scan (slow)
aguara scan .  # 30s for 500 files

# Incremental scan (fast)
aguara scan --changed .  # 1s for 5 changed files

Combining with Other Flags

With `--monitor`

Scan changed files AND track hashes for rug-pull detection:

aguara scan --changed --monitor .

This:

Scans only git-modified files (faster)
Updates hashes in state file for those files
Detects rug-pull attacks on next scan

With `--severity`

Filter findings by severity:

aguara scan --changed --severity high

Only reports HIGH and CRITICAL findings from changed files.

With `--fail-on`

Exit with code 1 if changed files have high-severity issues:

aguara scan --changed --fail-on high

Perfect for CI gates.

With `--ci`

Combines --fail-on high and --no-color:

aguara scan --changed --ci

Equivalent to:

aguara scan --changed --fail-on high --no-color

Git-Changed File Detection

Staged Files

Files added with git add:

git add skills/new-skill.md
aguara scan --changed .
# Scans: skills/new-skill.md

Unstaged Files

Modified but not staged:

vim skills/deploy.md  # make changes
aguara scan --changed .
# Scans: skills/deploy.md

Untracked Files

New files not yet added:

touch skills/experimental.md
aguara scan --changed .
# Scans: skills/experimental.md

Deleted Files

Deleted files are not scanned (nothing to analyze).

Renamed Files

Git tracks renames as delete + add. Aguara scans the new path:

git mv old.md new.md
aguara scan --changed .
# Scans: new.md

Performance

Benchmark (500-file repo)

Scan Type	Files Scanned	Duration
Full scan	500	28s
`--changed` (5 files)	5	0.8s
`--changed` (50 files)	50	4.2s

35x faster for typical PR workflows (5-10 changed files).

Overhead

Git command execution adds ~50ms overhead:

time git diff --name-only HEAD
# 0.05s

Negligible compared to scan time.

Limitations

1. Requires Git

If git is not installed or the directory is not a git repo, --changed has no effect (all files are scanned).

2. Branch Context

--changed compares against HEAD (current commit). To compare against a specific branch:

# Not supported directly; use git worktree or custom script
git diff --name-only main...HEAD | xargs -I{} aguara scan {}

3. Submodules

Git submodule changes are detected if the submodule pointer changed, but files inside submodules are not scanned unless you run Aguara inside the submodule directory.

4. Ignored Files

Files matching .aguaraignore or .gitignore are skipped even if changed.

Best Practices

1. Use in Development

Enable --changed in your daily workflow for instant feedback:

alias ascan='aguara scan --changed --verbose'

2. Full Scan in Merge to Main

Run incremental scans on PRs, but full scans on merge to main:

# .github/workflows/security.yml
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Scan
        run: |
          curl -fsSL https://raw.githubusercontent.com/garagon/aguara/main/install.sh | bash
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            aguara scan --changed --ci
          else
            aguara scan --ci
          fi

3. Combine with Watch Mode (Future)

While not yet supported, you can simulate watch mode with entr:

git ls-files | entr -c aguara scan --changed /_

Re-runs scan on every file change.

Comparison with —monitor

Feature	`--changed`	`--monitor`
Detects	All issues in git-modified files	Dangerous content in changed files (vs. previous scan)
Requires	Git repository	Persistent state file
Scope	Git-tracked changes	All files (compares vs. previous scan)
Persistence	None (stateless)	Stores hashes in state file
Use Case	Fast PR scans, pre-commit hooks	Rug-pull detection, long-term monitoring

You can combine both:

aguara scan --changed --monitor .

This scans only git-changed files and tracks their hashes for rug-pull detection.

Troubleshooting

”No files scanned” with —changed

If Aguara reports 0 files scanned:

Check git status:
```
git status
```
Ensure files are tracked or untracked (not ignored):
```
git ls-files --others --exclude-standard
```
Verify you’re in a git repository:
```
git rev-parse --git-dir
```

—changed not working in CI

Ensure fetch-depth: 0 in actions/checkout:

- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # fetch full history

Shallow clones (depth=1) don’t have enough git history for git diff HEAD.

Rug-Pull Detection — Track file changes across scans
Output Formats — CI-friendly JSON and SARIF output
MCP Discovery — Auto-detect MCP configs to scan

Get Started

Core Concepts

CLI Usage

Configuration

CI/CD Integration

Rules & Detection

Advanced Features

​Quick Start

​How It Works

​Git Integration

​Fallback for New Repos

​No Git? No Problem

​Use Cases

​1. Pre-Commit Hook

​2. Pull Request CI

​3. Development Workflow

​4. Monorepo Optimization

​Combining with Other Flags

​With --monitor

​With --severity

​With --fail-on

​With --ci

​Git-Changed File Detection

​Staged Files

​Unstaged Files

​Untracked Files

​Deleted Files

​Renamed Files

​Performance

​Benchmark (500-file repo)

​Overhead

​Limitations

​1. Requires Git

​2. Branch Context

​3. Submodules

​4. Ignored Files

​Best Practices

​1. Use in Development

​2. Full Scan in Merge to Main

​3. Combine with Watch Mode (Future)

​Comparison with —monitor

​Troubleshooting

​”No files scanned” with —changed

​—changed not working in CI

​Related

Build docs developers (and LLMs) love