How Threadline Detects Code Changes

Threadline automatically detects your CI/CD environment and gathers the appropriate code changes (diff) for analysis. Understanding what changes are included helps you know exactly what your threadlines are testing.

Diff Detection Strategy

Threadline uses different git diff strategies depending on the context and clone depth. Understanding these strategies helps you know exactly what changes are being reviewed.

Two Dots vs Three Dots

Three Dots (A...B): Merge-base comparison. Shows only changes from the common ancestor (merge base) to the target commit. This excludes unrelated changes that happened in the base branch after branching.

Example: git diff origin/main...HEAD shows only what the developer changed, not changes that happened in main after they branched.

Two Dots (A..B): Direct comparison. Shows all differences between the two branch tips, including unrelated changes that happened in the base branch after branching (drift).

Example: git diff origin/main..HEAD shows all differences, potentially including files the developer didn't touch.

Clone Depth Impact

CI environments often use shallow clones (depth=1) for performance. This affects which diff strategy works:

Full Clone or Sufficient Depth:

  • Three-dot diff works perfectly - shows only developer's changes
  • Merge base can be calculated: git merge-base origin/main HEAD
  • This is the preferred strategy for PR/MR reviews

Shallow Clone (depth=1):

  • Three-dot diff may fail if merge base isn't available locally
  • Threadline falls back to two-dot diff (direct comparison)
  • May include drift from main, but provides working diff instead of crashing
  • A warning is logged when fallback occurs

Note: Threadline always tries three-dot diff first (merge-base). If it fails due to shallow clone limitations, it automatically falls back to two-dot diff. This ensures checks always run, even if the diff includes some unrelated changes.

Context-Specific Strategies

PR/MR Context:

  1. Fetch target branch: git fetch origin {targetBranch}
  2. Find merge base: git merge-base origin/{targetBranch} HEAD
  3. Try three-dot diff: git diff origin/{targetBranch}...HEAD
  4. If that fails, fallback to two-dot: git diff origin/{targetBranch}..HEAD

Commit/Push Context:

  1. Extract parent SHA using plumbing: git cat-file -p HEAD
  2. Fetch parent commit: git fetch origin {parentSha} --depth=1
  3. Compare using two-dot: git diff {parentSha}..HEAD

Uses plumbing commands to work reliably in shallow clones. Two-dot is appropriate here since we're comparing a commit to its parent.

Local Development

Default: Staged/Unstaged Changes

When: Running threadlines check locally without flags

What's included: Staged changes (if any), otherwise unstaged changes

How:

  • Priority 1: git diff --cached (staged changes)
  • Priority 2: git diff (unstaged changes)

This allows you to review what you've staged before committing, or review unstaged changes if nothing is staged. Perfect for catching issues before they reach your CI pipeline.

Flags for Specific Contexts

  • --commit <ref> - Review a specific commit. Extracts parent SHA using git cat-file -p <ref>, fetches parent, then compares git diff <parentSha>..<ref>
  • --file <path> - Review entire file (all lines as additions). Creates artificial diff in git diff format. Populates repo name and author from git config.
  • --folder <path> - Review all files in folder recursively. Reads all files in folder and creates combined diff. Populates repo name and author from git config.
  • --files <paths...> - Review multiple specified files. Reads multiple files and creates combined diff. Populates repo name and author from git config.

Understanding Your Test Coverage

The diff detection strategy directly impacts what your threadlines test:

  • PR/MR context: Tests all changes that will be merged (using merge-base to exclude drift from main), giving you complete coverage of the feature
  • Push (no PR/MR): Tests the last commit only - for full branch coverage, create a PR/MR
  • Local (staged/unstaged): Tests your work-in-progress, catching issues before commit
  • Local flags: --commit, --file, --folder, --files provide specific review contexts

Each threadline filters the diff to only include files matching its patterns. This means:

  • A threadline for *.ts files won't see changes to *.md files
  • If no files match a threadline's patterns, that threadline is marked as "not relevant"
  • You can see exactly which files were sent to each threadline in the check details page

Context Lines

Threadline requests 200 lines of context around each change (-U200) to give the LLM sufficient surrounding code for accurate analysis. The diff viewer in the UI shows only the changes by default, with an option to expand and see the full context.