Dependency Management

/**
 * 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)

# 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

# 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]

/**
 * 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)

# 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/

# 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

/**
 * 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

# 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

# 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 (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...

# 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

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

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

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

# 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

# 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

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

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

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

# 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

# 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

# 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

# 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

# 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

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

# 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