Skip to main content

ctx diff

Generate context for changed files with their related dependencies.

Synopsis​

ctx diff [REVISION] [OPTIONS]

Description​

The diff command identifies changed files compared to a git reference and includes context about the symbols and dependencies affected by those changes. This is useful for:

  • Code review - Get context for reviewing a PR or commit
  • Change impact - Understand what's affected by your changes
  • Pre-commit - Verify changes before committing

Options​

OptionDescriptionDefault
REVISIONGit reference to compare againstHEAD~1
--max-tokens <N>Maximum tokens in output8000
--depth <N>Depth for finding related symbols1
--changes-onlyOnly include changed files, not related contextfalse
--stagedCompare staged changes instead of a revisionfalse
--summaryShow only summary, not file contentsfalse
-f, --format <FORMAT>Output format (xml, markdown, md, plain, json)xml
--show-sizesShow file sizes in the project treefalse
--no-treeDisable the project tree in outputfalse

Examples​

Changes Since Last Commit​

# See what changed since the previous commit (default: HEAD~1)
ctx diff

Compare with Branch​

# Changes compared to main branch
ctx diff main

# Changes in feature branch
ctx diff origin/main

Review a Specific Commit​

# Changes in the last commit
ctx diff HEAD~1

Staged Changes​

# Only the changes you have staged
ctx diff --staged

Token-Limited Output​

# Limit output for smaller context windows
ctx diff --max-tokens 4000

Summary Mode​

# Just see what changed without file contents
ctx diff --summary

Output:

Changed files (5):
  M src/auth.rs       - 3 symbols affected
  M src/handlers.rs   - 2 symbols affected
  A src/cache.rs      - new file
  D src/legacy.rs     - removed

Related symbols:
  - authenticate (src/auth.rs:42) - modified
  - handleLogin (src/handlers.rs:15) - calls authenticate
  - UserSession (src/models.rs:8) - used by authenticate

Deep Dependency Analysis​

# Find more related context
ctx diff main --depth 4

How It Works​

  1. Detect Changes: Uses git diff to find modified, added, and deleted files
  2. Parse Hunks: Identifies which lines/symbols changed
  3. Find Related: Follows call graph to find dependent symbols
  4. Generate Context: Outputs changed files plus relevant context

Output​

The output includes:

  • Changed files with their full contents
  • Related files containing symbols affected by the changes (unless --changes-only is set)
  • Context limited to --max-tokens

Integration with Code Review​

The ctx review command builds on diff to fetch and review a GitHub pull request. It requires the GitHub CLI (gh) to be installed and authenticated:

# Get context for a GitHub PR
ctx review 123

Tips​

  • Use --summary first to understand scope of changes
  • Increase --depth for refactoring tasks
  • Combine with --format markdown for PR descriptions
  • Use in CI to generate change documentation

See Also​