Skip to content
Grog Docs

Querying Targets

Why Query Your Build Graph?

Understanding the relationships between your build targets is essential for optimizing your build process. Grog provides powerful querying capabilities that help you:

  • Run only the targets affected by changes in CI, saving build time
  • Understand dependencies between targets for better project organization
  • Debug build issues by tracing dependency chains
  • Create targeted build commands for specific workflows

Available Query Commands

Grog offers several commands that can be used individually or chained together with tools like jq to extract precisely the information you need:

  • grog list: List all targets matching a pattern
  • grog deps: Get a target’s dependencies (direct or transitive)
  • grog rdeps: Get a target’s dependents (“reverse dependencies”)
  • grog owners: Find targets that include specific files as inputs
  • grog changes: Identify targets affected by changes since a specific commit

Target Selection Basics

Before diving into specific commands, it’s important to understand how to select targets in Grog. Most query commands accept target patterns that let you specify individual targets or groups of targets.

Target Patterns

Terminal window
# Reference a single target
grog build //package:target_name


# Reference all targets in a package
grog build //package:all


# Reference all targets in a package and its sub-packages
grog build //package/...


# Reference a target in the current package
grog build :target_name

Filtering by Tags

You can add tags to your targets in their definitions and then filter by those tags:

Terminal window
# Build all targets in the model_training package
# that have either the "ci-only" OR "python" tag
grog build --tag=ci-only --tag=python //model_training/...

Filtering by Target Type

You can filter targets by their type using the --target-type flag:

Terminal window
# List all test targets in the repository
grog list --target-type=test


# List all non-test targets in the repository
grog list --target-type=no_test


# List all targets with binary outputs in the repository
grog list --target-type=bin_output


# List all targets (default behavior)
grog list --target-type=all

The --target-type flag is available for all query commands: list, deps, rdeps, and changes.

Platform Selection

By default, all querying commands hide platforms that are marked as incompatible with the current platform. See here for the platform selection docs.

To bypass platform selectors, pass the --all-platforms, (shorthand: -a) flag.

grog list

Terminal window
grog list [target-pattern] [--target-type=<type>]

Lists all targets that match the given target pattern. If no pattern is provided, it lists all targets in the repository.

Parameters:

  • --target-type: Filter targets by type (all, test, no_test, bin_output)
    • all: Include all targets (default)
    • test: Include only test targets
    • no_test: Include only non-test targets
    • bin_output: Include only targets with binary outputs

Examples:

Terminal window
# List all targets in the repository
grog list


# List all targets in a specific package and its sub-packages
grog list //services/...


# List all targets in a specific package (not including sub-packages)
grog list //services:all


# List all test targets in the repository
grog list --target-type=test


# List all targets with binary outputs in a specific package
grog list //services/... --target-type=bin_output

Output format:

//package:target1
//package:target2
//package/subpackage:target3
...

grog deps

Terminal window
grog deps <target-label> [--transitive] [--target-type=<type>]

Lists the dependencies of a specific target. By default, it shows only direct dependencies, but with the --transitive flag, it shows the complete dependency tree.

Parameters:

  • --transitive: Include all transitive dependencies of the target
  • --target-type: Filter dependencies by type (all, test, no_test, bin_output)
    • all: Include all dependencies (default)
    • test: Include only test dependencies
    • no_test: Include only non-test dependencies
    • bin_output: Include only dependencies with binary outputs

Examples:

Terminal window
# Show direct dependencies of a target
grog deps //services/api:server


# Show all transitive dependencies (the complete dependency tree)
grog deps --transitive //services/api:server


# Show only test dependencies
grog deps //services/api:server --target-type=test


# Show only dependencies with binary outputs
grog deps --transitive //services/api:server --target-type=bin_output

This command is particularly useful for understanding what needs to be built before a specific target can be built.

grog rdeps

Terminal window
grog rdeps <target-pattern> [--transitive] [--target-type=<type>]

Lists all targets that depend on the specified target(s) - essentially the reverse of deps. The --transitive flag includes indirect dependents.

Parameters:

  • --transitive: Include all transitive dependents of the target
  • --target-type: Filter dependents by type (all, test, no_test, bin_output)
    • all: Include all dependents (default)
    • test: Include only test dependents
    • no_test: Include only non-test dependents
    • bin_output: Include only dependents with binary outputs

Examples:

Terminal window
# Find all targets that directly depend on a library
grog rdeps //libs/common:utils


# Find all targets that directly or indirectly depend on a library
grog rdeps --transitive //libs/common:utils


# Find all test targets that depend on a library
grog rdeps //libs/common:utils --target-type=test


# Find all targets with binary outputs that depend on a library
grog rdeps --transitive //libs/common:utils --target-type=bin_output

This command helps you understand the impact of changes to a target - which other targets will need to be rebuilt if this target changes.

grog owners

Terminal window
grog owners <file-path-or-glob>

Finds all targets that include the specified file(s) in their inputs. This is useful for determining which targets need to be rebuilt when specific files change.

Examples:

Terminal window
# Find targets that use a specific file
grog owners src/libs/auth/login.go


# Find targets that use any Go file in a directory
grog owners src/libs/auth/**/*.go

This command is particularly helpful when you want to understand which parts of your build are affected by changes to specific files.

grog changes

Terminal window
grog changes [target-pattern] [--since=<commit>] [--dependents=none|direct|transitive] [--target-type=<type>]

Identifies targets whose inputs have changed since a specific commit. This is extremely useful for CI pipelines where you only want to build what’s changed.

Parameters:

  • --since: The git commit to compare against (defaults to HEAD~1)
  • --dependents: Controls whether to include targets that depend on changed targets
    • none: Only include directly changed targets (default)
    • direct: Include changed targets and their direct dependents
    • transitive: Include changed targets and all their dependents (direct and indirect)
  • --target-type: Filter targets by type (all, test, no_test, bin_output)
    • all: Include all targets (default)
    • test: Include only test targets
    • no_test: Include only non-test targets
    • bin_output: Include only targets with binary outputs

Examples:

Terminal window
# Find all targets that changed in the current commit
grog changes


# Find all targets that changed since a specific commit
grog changes --since=origin/main


# Find all targets that changed in a specific package since a specific commit
grog changes //services/api/... --since=origin/main


# Find all targets affected by changes (including dependents)
grog changes --since=origin/main --dependents=transitive


# Find all test targets affected by changes
grog changes --since=origin/main --target-type=test


# Find all targets with binary outputs affected by changes
grog changes --since=origin/main --target-type=bin_output

CI Pipeline Example

This command is particularly valuable in CI pipelines. Here’s an example of how you might use it in a GitHub Actions workflow:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0 # Needed to access commit history


      - name: Build changed targets
        run: |
          # Get all targets affected by changes since the merge base with main
          CHANGED_TARGETS=$(grog changes --since=origin/main --dependents=transitive)


          # If there are changed targets, build them
          if [ -n "$CHANGED_TARGETS" ]; then
            echo "Building changed targets: $CHANGED_TARGETS"
            grog build $CHANGED_TARGETS
          else
            echo "No targets changed, skipping build"
          fi

Combining Query Commands

You can combine Grog’s query commands with standard Unix tools to create powerful workflows:

Terminal window
# Find all test targets affected by changes (using grep)
grog changes --since=origin/main --dependents=transitive | grep "test$" | xargs grog test


# Find all test targets affected by changes (using --target-type)
grog changes --since=origin/main --dependents=transitive --target-type=test | xargs grog test


# Find all Docker targets that depend on a specific library
grog rdeps --transitive //libs/common:utils | grep "docker" | xargs grog build


# Find all targets with binary outputs that depend on a specific library
grog rdeps --transitive //libs/common:utils --target-type=bin_output | xargs grog build

By mastering Grog’s query commands, you can significantly optimize your build process and gain deeper insights into your project’s structure.