buck2-target-determination

This skill should be used when determining which Buck2 targets are affected by code changes for incremental builds and tests. Use this when users ask to test/build changed code, find affected targets, or run incremental workflows with jj revisions.
Category: discovered
Tags: github, community
Version: 1.0.0
Author: walid
Downloads: 0
GitHub stars: 4
Updated: 2025-11-21
Source: thoughtpolice/a
Download the latest version (v1.0.0) from this page.
SKILL.md

---
name: buck2-target-determination
description: This skill should be used when determining which Buck2 targets are affected by code changes for incremental builds and tests. Use this when users ask to test/build changed code, find affected targets, or run incremental workflows with jj revisions.
---

# Buck2 Target Determination

## Overview

Target determination identifies which Buck2 targets are affected by code changes between two jj revisions. This enables incremental workflows that only build/test what changed, dramatically reducing build times (often 10-100x faster than full builds).

## When to Use This Skill

Use this skill when:
- User wants to "test what changed" or "test my changes"
- User asks to "build only affected targets"
- User requests "incremental build/test"
- Setting up CI/CD workflows that should only test affected code
- Analyzing impact of changes before committing
- User mentions `quicktd` or target determination

## How Target Determination Works

The `quicktd` tool:
1. Accepts two jj revsets (e.g., `'@-'` and `'@'`)
2. Computes file changes between those revisions
3. Builds Buck2 target graphs at both revisions
4. Identifies targets whose BUILD files or sources changed
5. Outputs affected targets to a file path

**Critical**: Always use the `root//` cell prefix with quicktd to avoid ambiguous cell references.

## Basic Usage Pattern

```bash
# Find targets affected between parent (@-) and current (@)
TARGETS=$(buck2 run root//buck/tools/quicktd -- '@-' '@' depot//src/...)

# Build affected targets
buck2 build @$TARGETS

# Test affected targets
buck2 test @$TARGETS
```

**Why at-file syntax (`@$TARGETS`)?** Target lists can be extremely large (thousands of targets), exceeding command-line length limits. At-file syntax loads targets from a file.

## Common Revset Patterns

### Development Workflows

```bash
# Changes in current commit (most common)
buck2 run root//buck/tools/quicktd -- '@-' '@' depot//src/...

# Changes since trunk
buck2 run root//buck/tools/quicktd -- 'trunk()' '@' depot//src/...

# Last 3 commits
buck2 run root//buck/tools/quicktd -- '@---' '@' depot//src/...

# Specific commit range
buck2 run root//buck/tools/quicktd -- 'abc123' 'def456' depot//src/...
```

### CI/CD Workflows

```bash
# Changes in pull request (compared to main)
buck2 run root//buck/tools/quicktd -- 'trunk()' '@' depot//...

# Full repository scan
buck2 run root//buck/tools/quicktd -- 'root()' '@' depot//...
```

### Scope Limiting

```bash
# Only specific directory
buck2 run root//buck/tools/quicktd -- '@-' '@' depot//src/myproject/...

# Multiple directories
buck2 run root//buck/tools/quicktd -- '@-' '@' depot//src/... depot//tools/...
```

## Complete Workflow Examples

### Pre-Commit Testing

```bash
# 1. Make changes
jj new -m "feat: implement feature"
# ... edit files ...

# 2. Find affected targets
TARGETS=$(buck2 run root//buck/tools/quicktd -- '@-' '@' depot//src/...)

# 3. Build affected targets
buck2 build @$TARGETS

# 4. Test affected targets
buck2 test @$TARGETS

# 5. If passing, commit
jj commit -m "feat: implement feature"
```

### Impact Analysis

```bash
# See what targets are affected
TARGETS=$(buck2 run root//buck/tools/quicktd -- '@-' '@' depot//src/...)

# Count affected targets
wc -l $TARGETS

# Show affected targets
cat $TARGETS

# Find which are tests
buck2 query "kind('.*_test', set(@$TARGETS))"

# Find which are binaries
buck2 query "kind('.*_binary', set(@$TARGETS))"
```

## Helper Script Usage

Use `scripts/quicktd_helper.py` for simplified invocations:

```bash
# Interactive mode - prompts for revsets
python3 scripts/quicktd_helper.py

# Quick patterns
python3 scripts/quicktd_helper.py --pattern current    # '@-' to '@'
python3 scripts/quicktd_helper.py --pattern trunk      # 'trunk()' to '@'
python3 scripts/quicktd_helper.py --pattern full       # 'root()' to '@'

# Custom revsets
python3 scripts/quicktd_helper.py --from '@---' --to '@' --scope depot//src/myproject/...

# Auto-build affected targets
python3 scripts/quicktd_helper.py --pattern current --build

# Auto-test affected targets
python3 scripts/quicktd_helper.py --pattern current --test

# Both build and test
python3 scripts/quicktd_helper.py --pattern trunk --build --test
```

The helper provides:
- Better error messages
- Target count and preview
- Optional auto-build/test
- Common pattern shortcuts

## Troubleshooting

### "No targets affected"

Possible causes:
- No files changed (check `jj diff`)
- Changes only to files not in any BUILD target
- Scope too narrow (expand from `depot//src/myproject/...` to `depot//src/...`)
- Files not committed to jj (Buck2 only sees committed files)

Solution:
```bash
# Check what changed
jj diff

# Verify files are committed
jj status

# Expand scope
buck2 run root//buck/tools/quicktd -- '@-' '@' depot//...
```

### "Could not find cell" error

The `root//` prefix is missing. Always use:

```bash
# ✓ Correct
buck2 run root//buck/tools/quicktd -- ...

# ✗ Wrong
buck2 run //buck/tools/quicktd -- ...
```

### Large target lists cause failures

Use at-file syntax (`@filename`) instead of passing targets directly:

```bash
# ✓ Correct
TARGETS=$(buck2 run root//buck/tools/quicktd -- '@-' '@' depot//src/...)
buck2 test @$TARGETS

# ✗ Wrong (may exceed command-line limits)
buck2 test $(cat $TARGETS)
```

## Performance Benefits

Real-world example:
```bash
# Without target determination (builds everything)
time buck2 test depot//src/...
# → 1847 actions, 15m 23s

# With target determination (1 file changed)
TARGETS=$(buck2 run root//buck/tools/quicktd -- '@-' '@' depot//src/...)
time buck2 test @$TARGETS
# → 12 actions, 8.3s
# → 111x faster!
```

## Best Practices

1. **Always use `root//` prefix** - Prevents cell reference errors
2. **Use at-file syntax** - Required for large target lists
3. **Scope appropriately** - Balance coverage vs speed
4. **Commit before testing** - Buck2 only sees committed files
5. **Cache the output** - Store `$TARGETS` for multiple commands
6. **Check target count** - `wc -l $TARGETS` to verify results
7. **Run quality tests separately** - `depot//buck/tests/...` aren't in quicktd scope

## Resources

### scripts/quicktd_helper.py
Python helper script that wraps quicktd with common patterns and better output formatting.

### references/revset_patterns.md
Comprehensive guide to jj revset patterns for use with quicktd.