detect_changes

Overview

The detect_changes tool analyzes your uncommitted git changes (diff) and maps them to indexed symbols in the knowledge graph, then traces which execution flows are impacted. This is essential for pre-commit review and understanding the scope of your changes.

When to use: Before committing — to understand what your changes affect. Pre-commit review, PR preparation.Next step: Review affected processes. Use context() on high-risk symbols. READ gitnexus://repo/{name}/process/{name} for full traces.

Parameters

scope

string

default:"unstaged"

What changes to analyze:

"unstaged" - Only unstaged changes (default)
"staged" - Only staged changes (what will be committed)
"all" - Both staged and unstaged changes
"compare" - Compare against a specific branch/commit (requires base_ref)

Use cases:

"staged" - Pre-commit check
"all" - Full working tree analysis
"compare" - PR impact analysis (e.g., comparing against main)

base_ref

string

Branch or commit to compare against when using scope: "compare"Examples:

"main"
"develop"
"HEAD~3" (3 commits back)
"abc123def" (specific commit hash)

repo

string

Repository name or path. Required when multiple repos are indexed. Omit if only one repo is available.

Response

changed_symbols

array

required

Symbols modified by the git diff

Show symbol properties

uid

string

Unique symbol identifier

name

string

Symbol name

type

string

Symbol type (Function, Class, Method, etc.)

filePath

string

File containing the change

changeType

string

Type of change: modified, added, deleted

linesChanged

number

Number of lines affected

affected_processes

array

required

Execution flows impacted by these changes

Show process properties

name

string

Process name (e.g., “LoginFlow”, “CheckoutFlow”)

affectedSteps

array

Which steps in the flow are affected

totalSteps

number

Total steps in this process

module

string

Functional area this process belongs to

risk

string

required

Overall risk assessment: LOW, MEDIUM, HIGH, or CRITICALBased on:

Number of changed symbols
Number of affected processes
Criticality of affected modules

summary

object

required

High-level change summary

Show properties

filesChanged

number

Number of files modified

symbolsChanged

number

Number of symbols modified

processesAffected

number

Number of execution flows impacted

modulesAffected

array

List of functional areas touched

Example Usage

Check Unstaged Changes (Default)

detect_changes()

Pre-Commit Check (Staged Only)

detect_changes({
  scope: "staged"
})

Full Working Tree Analysis

detect_changes({
  scope: "all"
})

PR Impact Analysis

detect_changes({
  scope: "compare",
  base_ref: "main"
})

Multi-Repo Change Detection

detect_changes({
  scope: "staged",
  repo: "my-app"
})

Example Response

{
  "changed_symbols": [
    {
      "uid": "func_validateUser_abc123",
      "name": "validateUser",
      "type": "Function",
      "filePath": "src/auth/validator.ts",
      "changeType": "modified",
      "linesChanged": 12
    },
    {
      "uid": "func_checkToken_def456",
      "name": "checkToken",
      "type": "Function",
      "filePath": "src/auth/token.ts",
      "changeType": "modified",
      "linesChanged": 5
    }
  ],
  "affected_processes": [
    {
      "name": "LoginFlow",
      "affectedSteps": [2, 3],
      "totalSteps": 5,
      "module": "Authentication"
    },
    {
      "name": "TokenRefresh",
      "affectedSteps": [1],
      "totalSteps": 3,
      "module": "Authentication"
    }
  ],
  "risk": "MEDIUM",
  "summary": {
    "filesChanged": 2,
    "symbolsChanged": 2,
    "processesAffected": 2,
    "modulesAffected": ["Authentication"]
  }
}

Risk Assessment

Risk Level	Criteria	Action
LOW	Less than 3 symbols, 1-2 processes, single module	Standard testing
MEDIUM	3-8 symbols, 2-5 processes, 1-2 modules	Careful review, test affected flows
HIGH	More than 8 symbols, more than 5 processes, multiple modules	Comprehensive testing, staged deployment
CRITICAL	Critical modules (auth, payments), wide impact	Extensive testing, careful monitoring

Real-World Examples

Example 1: Pre-Commit Check

// Task: "What will this commit affect?"
detect_changes({
  scope: "staged"
})

// Result:
// - Changed: validateUser in validator.ts
// - Affected: LoginFlow (step 2), TokenRefresh (step 1)
// - Risk: MEDIUM
// Action: Test login and token refresh flows before committing

Example 2: PR Preparation

// Task: "What's the impact of my feature branch vs main?"
detect_changes({
  scope: "compare",
  base_ref: "main"
})

// Result:
// - Changed: 12 symbols across 8 files
// - Affected: CheckoutFlow, PaymentProcessing, RefundHandler
// - Risk: HIGH
// Action: Include comprehensive test results in PR description

Example 3: Debugging Recent Changes

// Task: "Something broke - what did I change?"
detect_changes({
  scope: "all"
})

// Result:
// - Changed: processPayment (modified), validateCard (modified)
// - Affected: CheckoutFlow (steps 3, 4)
// - Risk: MEDIUM
// Root cause: Changes to validateCard broke checkout

Best Practices

Run before every commit

Make detect_changes({scope: "staged"}) part of your pre-commit workflow to understand what you’re about to commit.

Use 'compare' for PRs

When preparing a pull request, use scope: "compare" with base_ref: "main" to see the full impact of your branch.

Review affected processes

Don’t just look at changed symbols — review which execution flows are affected. Breaking “LoginFlow” is more critical than a utility function.

Follow up with context()

For high-risk changes, use context() on changed symbols to understand their full dependency graph.

Compare risk with impact()

If detect_changes shows MEDIUM/HIGH risk, run impact() on changed symbols to see the full blast radius.

Workflow Integration

Pre-Commit Hook

#!/bin/bash
# .git/hooks/pre-commit

# Run GitNexus change detection
echo "Analyzing impact of staged changes..."
result=$(npx gitnexus mcp detect_changes --scope staged)

# Check risk level
if echo "$result" | grep -q "CRITICAL\|HIGH"; then
  echo "⚠️  High-risk changes detected. Please review carefully."
  echo "$result"
  # Optionally block commit: exit 1
fi

CI/CD Integration

# .github/workflows/pr-check.yml
name: PR Impact Analysis

on:
  pull_request:
    branches: [main]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      
      - name: Analyze PR Impact
        run: |
          npx gitnexus mcp detect_changes \
            --scope compare \
            --base-ref origin/main

Use Cases

Pre-commit review: Understand what you’re about to commit
PR preparation: Document the scope of changes
Debugging: “What did I just change that broke this?”
Code review: Reviewers can see execution flow impact
Risk assessment: Automated change risk evaluation
Test planning: Know which tests to focus on

Limitations

Index Freshness Requireddetect_changes maps git diffs to the knowledge graph. If your index is stale (outdated), it may miss recently added symbols or show incorrect mappings.Solution: If you see a staleness warning, run npx gitnexus analyze before using detect_changes.

impact - Deeper blast radius analysis for specific symbols
context - Understand changed symbols in detail
rename - Safe refactoring tool

gitnexus://repo/{name}/processes - Review affected execution flows
gitnexus://repo/{name}/context - Check if index is stale

MCP Tools

MCP Resources

MCP Prompts

CLI Commands

Overview

Parameters

Response

Example Usage

Check Unstaged Changes (Default)

Pre-Commit Check (Staged Only)

Full Working Tree Analysis

PR Impact Analysis

Multi-Repo Change Detection

Example Response

Risk Assessment

Real-World Examples

Example 1: Pre-Commit Check

Example 2: PR Preparation

Example 3: Debugging Recent Changes

Best Practices

Workflow Integration

Pre-Commit Hook

CI/CD Integration

Use Cases

Limitations

Build docs developers (and LLMs) love

MCP Tools

MCP Resources

MCP Prompts

CLI Commands

​Overview

​Parameters

​Response

​Example Usage

​Check Unstaged Changes (Default)

​Pre-Commit Check (Staged Only)

​Full Working Tree Analysis

​PR Impact Analysis

​Multi-Repo Change Detection

​Example Response

​Risk Assessment

​Real-World Examples

​Example 1: Pre-Commit Check

​Example 2: PR Preparation

​Example 3: Debugging Recent Changes

​Best Practices

​Workflow Integration

​Pre-Commit Hook

​CI/CD Integration

​Use Cases

​Limitations

​Related Tools

​Related Resources

Build docs developers (and LLMs) love

Overview

Parameters

Response

Example Usage

Check Unstaged Changes (Default)

Pre-Commit Check (Staged Only)

Full Working Tree Analysis

PR Impact Analysis

Multi-Repo Change Detection

Example Response

Risk Assessment

Real-World Examples

Example 1: Pre-Commit Check

Example 2: PR Preparation

Example 3: Debugging Recent Changes

Best Practices

Workflow Integration

Pre-Commit Hook

CI/CD Integration

Use Cases

Limitations

Related Tools

Related Resources