tessl/golang-bufbuild--buf

The buf CLI is the best tool for working with Protocol Buffers, providing linting, breaking change detection, code generation, formatting, and integration with the Buf Schema Registry for modern Protobuf development workflows

—

Pending

Overview

Eval results

Files

Dependency Management

Name: tessl/golang-bufbuild--buf
Author: tessl

Manage Protocol Buffer dependencies, workspace configurations, and module relationships. Buf provides tools for visualizing, updating, and maintaining dependencies across projects and workspaces.

Capabilities

Dependency Graph Visualization

Display and analyze the dependency relationships between modules.

/**
 * Show dependency graph for modules
 * @param input - Proto files, directories, git repos, BSR modules, or archives
 */
buf dep graph [flags] [input]

# Key flags:
--format string         Output format (text, json, dot, mermaid)
--config string         Configuration file path
--exclude-imports       Exclude imported dependencies from graph
--type string          Filter by dependency type (direct, transitive, all)

Usage Examples:

# Show text dependency graph
buf dep graph

# Generate DOT format for Graphviz
buf dep graph --format dot > deps.dot
dot -Tpng deps.dot -o deps.png

# Generate Mermaid diagram
buf dep graph --format mermaid > deps.mmd

# Show JSON format for programmatic use
buf dep graph --format json

# Show only direct dependencies
buf dep graph --type direct

# Graph for specific input
buf dep graph buf.build/googleapis/googleapis

Graph Output Formats:

# Text format (default)
acme/petapis
├── googleapis/googleapis@v1.2.3
│   └── grpc-ecosystem/grpc-gateway@v2.15.2
└── envoyproxy/protoc-gen-validate@v0.9.1

# JSON format
{
  "modules": [
    {
      "name": "buf.build/acme/petapis",
      "dependencies": [
        {
          "name": "buf.build/googleapis/googleapis", 
          "commit": "abc123...",
          "type": "direct"
        }
      ]
    }
  ]
}

# DOT format (Graphviz)
digraph dependencies {
  "acme/petapis" -> "googleapis/googleapis";
  "googleapis/googleapis" -> "grpc-ecosystem/grpc-gateway";
}

# Mermaid format
graph TD
  A[acme/petapis] --> B[googleapis/googleapis]
  B --> C[grpc-ecosystem/grpc-gateway]

Dependency Updates

Update dependencies to their latest versions while maintaining compatibility.

/**
 * Update dependencies to latest compatible versions
 * @param input - Proto files, directories, git repos, BSR modules, or archives
 */
buf dep update [flags] [input]

# Key flags:
--config string         Configuration file path
--only strings         Update only specified dependencies
--exclude strings      Exclude specific dependencies from update
--strategy string      Update strategy (latest, minor, patch)

Usage Examples:

# Update all dependencies to latest
buf dep update

# Update only specific dependencies
buf dep update --only buf.build/googleapis/googleapis

# Update with minor version strategy
buf dep update --strategy minor

# Update excluding certain dependencies
buf dep update --exclude buf.build/legacy/apis

# Update specific workspace directory
buf dep update proto/public/

Update Strategies:

# latest - Update to latest available version (default)
buf dep update --strategy latest

# minor - Update within minor version (x.Y.z)
buf dep update --strategy minor  

# patch - Update within patch version (x.y.Z)
buf dep update --strategy patch

Dependency Pruning

Remove unused dependencies from modules and workspaces.

/**
 * Remove unused dependencies from configuration
 * @param input - Proto files, directories, git repos, BSR modules, or archives
 */
buf dep prune [flags] [input]

# Key flags:
--config string         Configuration file path
--write                Write changes back to configuration file
--dry-run              Show what would be removed without making changes

Usage Examples:

# Show unused dependencies (dry run)
buf dep prune

# Remove unused dependencies
buf dep prune --write

# Dry run for specific module
buf dep prune --dry-run proto/apis/

# Prune with custom config
buf dep prune --config custom.yaml --write

Dependency Configuration

buf.yaml Dependencies

Configure module dependencies in buf.yaml:

# Direct dependencies in buf.yaml
version: v1
name: buf.build/acme/petapis

deps:
  - buf.build/googleapis/googleapis           # Latest version
  - buf.build/grpc-ecosystem/grpc-gateway:v2.15.2  # Specific version
  - buf.build/envoyproxy/protoc-gen-validate:main   # Branch/label

buf.lock Resolution

Dependency lock file showing resolved versions:

# buf.lock (auto-generated)
version: v1
deps:
  - remote: buf.build
    owner: googleapis  
    repository: googleapis
    commit: 62f35882210941b06d351afc3c5a4b3233d40b05
    digest: shake256:a1b2c3d4e5f6...
    
  - remote: buf.build
    owner: grpc-ecosystem
    repository: grpc-gateway  
    commit: a7f35faf610eaefb2d72a93b7697ea04d1d5fe17
    digest: shake256:f6e5d4c3b2a1...

Workspace Dependencies

Configure workspace-level dependencies in buf.work.yaml:

# buf.work.yaml workspace dependencies
version: v1
directories:
  - proto/public
  - proto/internal
  
# Workspace-level dependencies (shared across modules)
deps:
  - buf.build/grpc-ecosystem/grpc-gateway
  - buf.build/envoyproxy/protoc-gen-validate

Dependency Types

Direct Dependencies

Dependencies explicitly declared in buf.yaml:

# Direct dependency declaration
deps:
  - buf.build/googleapis/googleapis    # Direct dependency

Transitive Dependencies

Dependencies of dependencies, automatically resolved:

# Transitive resolution example
# Your module depends on googleapis/googleapis
# googleapis/googleapis depends on protocolbuffers/wellknowntypes
# protocolbuffers/wellknowntypes becomes a transitive dependency

Development Dependencies

Dependencies used only for development (not yet supported, but planned):

# Future syntax (not yet implemented)
dev_deps:
  - buf.build/bufbuild/buf-test-utils
  - buf.build/acme/internal-tools

Version Constraints

Version Formats

Supported version reference formats:

# Semantic version tags
buf.build/owner/module:v1.2.3
buf.build/owner/module:v2.0.0-beta.1

# Branch references  
buf.build/owner/module:main
buf.build/owner/module:development

# Commit references
buf.build/owner/module:abc123def456789

# Latest (default if no version specified)
buf.build/owner/module:latest
buf.build/owner/module            # Implicit latest

Version Resolution

How buf resolves version constraints:

# Resolution priority (highest to lowest)
1. Exact commit hash         # abc123def456789
2. Semantic version tag      # v1.2.3  
3. Branch/label reference    # main, latest
4. Default latest           # If no version specified

Dependency Sources

BSR Modules

Primary source for Protocol Buffer dependencies:

# BSR module references
buf.build/googleapis/googleapis
buf.build/grpc-ecosystem/grpc-gateway
buf.build/envoyproxy/protoc-gen-validate
buf.build/bufbuild/protovalidate

Local Dependencies

Local file system dependencies (for development):

# Local path dependencies (buf.work.yaml only)
directories:
  - proto/public              # Local module directory
  - ../shared-protos         # Relative path
  - /absolute/path/to/protos # Absolute path

Git Dependencies

Git repository dependencies (limited support):

# Git repository references (experimental)
https://github.com/owner/repo.git#branch=main
https://github.com/owner/repo.git#tag=v1.0.0

Workspace Management

Multi-Module Workspaces

Managing dependencies across multiple modules:

# buf.work.yaml
version: v1
directories:
  - services/user-api
  - services/order-api  
  - shared/common-protos

# Each directory has its own buf.yaml with dependencies
# services/user-api/buf.yaml
version: v1
name: buf.build/acme/user-api
deps:
  - buf.build/acme/common-protos  # Reference to workspace module
  - buf.build/googleapis/googleapis

# services/order-api/buf.yaml
version: v1  
name: buf.build/acme/order-api
deps:
  - buf.build/acme/common-protos  # Shared dependency
  - buf.build/acme/user-api       # Inter-service dependency

Dependency Conflicts

Resolving version conflicts in workspaces:

# Conflict resolution strategies
# 1. Highest version wins (default)
Module A depends on googleapis:v1.2.0
Module B depends on googleapis:v1.3.0
Result: googleapis:v1.3.0 is used

# 2. Lock file pins specific versions
# buf.lock ensures consistent resolution across builds

# 3. Workspace-level dependency override
# buf.work.yaml can specify shared dependency versions

Caching and Performance

Dependency Caching

Buf caches resolved dependencies for performance:

# Cache locations
~/.cache/buf/                    # Linux/macOS
%LOCALAPPDATA%\buf\              # Windows

# Cache management
buf registry cc                  # Clear registry cache
BUF_CACHE_DIR=/custom/path      # Custom cache directory

Offline Mode

Working with cached dependencies offline:

# Buf automatically uses cached dependencies when available
# No special offline mode required - works seamlessly

# Pre-populate cache for offline development
buf dep graph  # Downloads and caches all dependencies

Error Handling

Common dependency-related errors and solutions:

# Dependency not found
Error: dependency "buf.build/owner/nonexistent" not found
Solution: Verify module name and check BSR availability

# Version conflict
Error: conflicting versions for buf.build/googleapis/googleapis
Solution: Use buf dep update to resolve conflicts

# Circular dependency
Error: circular dependency detected
Solution: Review module dependencies and break circular references

# Authentication required
Error: authentication required for private module
Solution: Run 'buf registry login' to authenticate

# Network connectivity
Error: failed to resolve dependencies (network error)  
Solution: Check internet connection and BSR availability

Exit Codes

0   # Success
1   # General error (network, authentication, etc.)
2   # Invalid configuration or arguments
3   # Dependency resolution failure
4   # Circular dependency detected

Best Practices

Dependency Management

Recommended practices for managing dependencies:

# 1. Pin to specific versions in production
deps:
  - buf.build/googleapis/googleapis:v1.2.3  # Good
  - buf.build/googleapis/googleapis         # Avoid in prod

# 2. Use semantic versioning
buf.build/owner/module:v1.2.3              # Semantic version
buf.build/owner/module:main                # Development branch

# 3. Regular dependency updates
buf dep update --strategy minor            # Conservative updates
buf dep prune --write                      # Remove unused deps

# 4. Workspace organization
buf.work.yaml                              # Top-level workspace
├── services/
│   ├── api-a/buf.yaml                    # Service modules
│   └── api-b/buf.yaml
└── shared/
    └── common/buf.yaml                    # Shared modules

Install with Tessl CLI