📡 go-broadcast

Stateless File Sync Orchestrator for Repository Management

CI / CD	Quality & Security	Docs & Meta	Community

🗂️ Table of Contents

Quick Start
Key Features
How It Works
Usage Examples
Coverage System
Performance
Documentation
Examples & Tests
Code Standards
AI Compliance
Maintainers
Contributing
License

⚡ Quick Start

Get up and running with go-broadcast in under 5 minutes!

Prerequisites

Go 1.24+ (supported release) and GitHub CLI installed
GitHub authentication: gh auth login

Installation

go install github.com/mrz1836/go-broadcast/cmd/go-broadcast@latest

Create Configuration

Create a sync.yaml file:

version: 1
source:
  repo: "mrz1836/template-repo"
  branch: "master"
targets:
  - repo: "mrz1836/target-repo"
    files:
      - src: ".github/workflows/ci.yml"
        dest: ".github/workflows/ci.yml"
    directories:
      - src: ".github/coverage"
        dest: ".github/coverage"
        exclude: ["*.out", "*.test"]
    transform:
      repo_name: true

Run Sync

# Validate configuration
go-broadcast validate --config sync.yaml

# Preview changes (dry run)
go-broadcast sync --dry-run --config sync.yaml

# Execute sync
go-broadcast sync --config sync.yaml

Example Dry-Run Output

When using --dry-run, go-broadcast provides clean, readable output showing exactly what would happen:

🔍 📋 COMMIT PREVIEW
┌─────────────────────────────────────────────────────────────────
│ Message: sync: update 2 files from source repository
│ Files: 2 changed
│ README.md, Makefile
└─────────────────────────────────────────────────────────────────

📄 FILE CHANGES:
   ✨ README.md (added) (+1249 bytes)
   📝 Makefile (modified) (+45 bytes)

🔍 DRY-RUN: Pull Request Preview
┌─────────────────────────────────────────────────────────────────
│ Repository: company/service-name
│ Branch: chore/sync-files-20250130-143052-abc123f
├─────────────────────────────────────────────────────────────────
│ Title: [Sync] Update project files from source repository (abc123f)
├─────────────────────────────────────────────────────────────────
│ ## What Changed
│ * Updated project files to synchronize with the latest ch...
│
│ ## Changed Files
│
│ - `README.md` (added)
│ - `Makefile` (modified)
└─────────────────────────────────────────────────────────────────

✅ DRY-RUN SUMMARY: Repository sync preview completed successfully
   📁 Repository: company/service-name
   🌿 Branch: chore/sync-files-20250130-143052-abc123f
   📝 Files: 2 would be changed
   🔗 Commit: dry-run-commit-sha
   💡 Run without --dry-run to execute these changes

That's it! 🎉 go-broadcast automatically:

Clones your template repository
Applies configured transformations
Creates a branch in each target repository
Commits synchronized files
Opens a pull request for review

💡 Pro tip: go-broadcast includes a built-in coverage system, enterprise performance, and comprehensive logging & debugging - explore the features below!

✨ Key Features

go-broadcast is more than just file sync - it's a complete repository management platform:

🔄 Intelligent Sync Engine

File & directory sync - Supports individual files and entire directories with smart exclusions
Stateless architecture - No databases, all state tracked via GitHub
Smart diff detection - Only syncs files that actually changed
Zero-downtime operations - Works at any scale without conflicts
Full audit trail - Every sync tracked in branches and PRs
Automated PR management - Auto-assign reviewers, assignees, and labels

⚡ Enterprise Performance

587M+ ops/sec - Binary detection with zero allocations
239M+ ops/sec - Content comparison for identical files
13.5M+ ops/sec - Cache operations with minimal memory
Directory processing - 1000+ files in ~32ms with concurrent worker pools
API optimization - 90%+ reduction in GitHub API calls through tree API
Concurrent sync - Multiple repositories in parallel

🛡️ Security & Compliance

60+ linters - Zero tolerance policy for code issues
Vulnerability scanning - govulncheck, OSSAR, CodeQL integration
OpenSSF Scorecard - Supply chain security assessment
Secret detection - gitleaks integration prevents leaks

📊 Built-in Coverage System

Third-party replacement - Zero external dependencies, complete data privacy
Professional badges - GitHub-style badges with real-time updates
Interactive dashboard - Modern UI with analytics and trends
🔗 Live Dashboard

🔍 How It Works

go-broadcast uses a stateless architecture that tracks synchronization state through GitHub itself - no databases or state files needed!

State Tracking Through Branch Names

Every sync operation creates a branch with encoded metadata:

chore/sync-files-20250123-143052-abc123f
│    │         │                │
│    │         │                └─── Source commit SHA (7 chars)
│    │         └──────────────────── Timestamp (YYYYMMDD-HHMMSS)
│    └────────────────────────────── Template identifier
└─────────────────────────────────── Configurable prefix

How go-broadcast Determines What to Sync

State Discovery - Queries GitHub to find:
- Latest commit in source repository
- All sync branches in target repositories
- Open sync pull requests

Smart Comparison - For each target:

Source commit: abc123f (latest)
Target's last sync: def456g (from branch name)
Status: Behind → Needs sync ✓

Content-Based Sync - Only syncs files that actually changed:
- Fetches current files from target (individual files or directory contents)
- Applies transformations to source files
- Compares content byte-by-byte with smart exclusion filtering
- Skips unchanged files and processes directories concurrently

Pull Request Metadata

Each PR includes structured metadata for complete traceability:

<!-- go-broadcast metadata
source:
  repo: company/template-repo
  branch: master
  commit: abc123f7890
files:
  - src: .github/workflows/ci.yml
    dest: .github/workflows/ci.yml
directories:
  - src: .github/coverage
    dest: .github/coverage
    excluded: ["*.out", "*.test"]
    files_synced: 87
    processing_time_ms: 4
performance:
  total_files: 88
  api_calls_saved: 79
timestamp: 2025-01-23T14:30:52Z
-->

Why This Approach is Powerful

✅ No State Files - Everything lives in GitHub
✅ Atomic Operations - Each sync is self-contained
✅ Full Audit Trail - Branch and PR history shows all syncs
✅ Disaster Recovery - State can be reconstructed from GitHub
✅ Works at Scale - No state corruption with concurrent syncs

💡 Usage Examples

Common Use Cases

Sync CI/CD workflows across microservices:

source:
  repo: "company/ci-templates"
targets:
  - repo: "company/user-service"
    files:
      - src: "workflows/ci.yml"
        dest: ".github/workflows/ci.yml"
    transform:
      variables:
        SERVICE_NAME: "user-service"

Sync entire directories with smart exclusions:

source:
  repo: "company/ci-templates"
targets:
  - repo: "company/microservice-a"
    directories:
      - src: ".github/workflows"
        dest: ".github/workflows"
        exclude: ["*-local.yml", "*.disabled"]
      - src: ".github/coverage"
        dest: ".github/coverage"
        # Smart defaults automatically exclude: *.out, *.test, *.exe, **/.DS_Store
    transform:
      repo_name: true

Mixed file and directory synchronization:

source:
  repo: "company/template-repo"
targets:
  - repo: "company/service"
    files:
      - src: "Makefile"
        dest: "Makefile"
    directories:
      - src: "configs"
        dest: "configs"
        exclude: ["*.local", "*.secret"]
    transform:
      variables:
        SERVICE_NAME: "user-service"

Automated PR management with assignees, reviewers, and labels:

defaults:
  pr_labels: ["automated-sync", "chore"]
  pr_assignees: ["tech-lead", "platform-team"]
  pr_reviewers: ["senior-dev1", "senior-dev2"]  
  pr_team_reviewers: ["architecture-team"]
targets:
  - repo: "company/critical-service"
    files:
      - src: "security/policies.yml"
        dest: "security/policies.yml"
    # Critical service needs security team review
    pr_labels: ["security-update", "high-priority"]
    pr_assignees: ["security-lead"]
    pr_reviewers: ["security-engineer"]
    pr_team_reviewers: ["security-team"]

Essential Commands

# Validate and preview
go-broadcast validate --config sync.yaml
go-broadcast sync --dry-run --config sync.yaml

# Execute sync
go-broadcast sync --config sync.yaml
go-broadcast sync org/specific-repo --config sync.yaml

# Monitor status
go-broadcast status --config sync.yaml

# Troubleshooting and diagnostics
go-broadcast diagnose                    # Collect system diagnostic information
go-broadcast diagnose > diagnostics.json # Save diagnostics to file

# Cancel active syncs
go-broadcast cancel                      # Cancel all active sync operations
go-broadcast cancel org/repo1            # Cancel syncs for specific repository
go-broadcast cancel --dry-run            # Preview what would be cancelled

Configuration Reference

🔄 File Transformations

transform:
  repo_name: true  # Updates Go module paths
  variables:
    SERVICE_NAME: "my-service"    # {{SERVICE_NAME}} → my-service
    ENVIRONMENT: "production"     # ${ENVIRONMENT} → production

📁 File & Directory Mapping Options

File Mapping:

files:
  - src: "Makefile"         # Copy to same location
    dest: "Makefile"
  - src: "template.md"      # Rename during sync  
    dest: "README.md"
  - src: "config/app.yml"   # Move to different directory
    dest: "configs/app.yml"

Directory Mapping:

directories:
  - src: ".github/workflows"           # Basic directory sync
    dest: ".github/workflows"
  - src: ".github/coverage"            # Directory with exclusions  
    dest: ".github/coverage"
    exclude: ["*.out", "*.test", "gofortress-coverage"]
  - src: "docs"                        # Advanced directory options
    dest: "documentation" 
    exclude: ["*.tmp", "**/draft/*"]
    preserve_structure: true           # Keep nested structure (default: true)
    include_hidden: true               # Include hidden files (default: true)
    transform:                         # Apply transforms to all files
      variables:
        VERSION: "v2.0"

Smart Default Exclusions: Automatically applied to all directories: *.out, *.test, *.exe, **/.DS_Store, **/tmp/*, **/.git

⚙️ Advanced Configuration

version: 1
source:
  repo: "org/template-repo"
  branch: "master"
# Global PR settings applied to ALL targets (merged with target-specific settings)
global:
  pr_labels: ["automated-sync", "chore"]
  pr_assignees: ["platform-team"]
  pr_reviewers: ["platform-lead"]
  pr_team_reviewers: ["infrastructure-team"]
# Default settings (fallback when no global or target settings)
defaults:
  branch_prefix: "chore/sync-files"  
  pr_labels: ["maintenance"]
  pr_assignees: ["maintainer1", "maintainer2"]
  pr_reviewers: ["reviewer1", "reviewer2"]
  pr_team_reviewers: ["platform-team"]
targets:
  - repo: "org/target-repo"
    files:
      - src: ".github/workflows/ci.yml"
        dest: ".github/workflows/ci.yml"
    directories:
      - src: ".github/coverage"
        dest: ".github/coverage"
        exclude: ["*.out", "gofortress-coverage"]
    transform:
      repo_name: true
      variables:
        ENVIRONMENT: "production"
    # Additional PR settings merged with global settings
    # Final labels: ["automated-sync", "chore", "service-specific"]
    pr_labels: ["service-specific"]
    # Final assignees: ["platform-team", "service-owner"]  
    pr_assignees: ["service-owner"]
    # Final reviewers: ["platform-lead", "service-reviewer"]
    pr_reviewers: ["service-reviewer"]

❌ Cancel Sync Operations

When issues arise, you can cancel active sync operations to prevent unwanted changes.

Cancel sync operations when issues arise:

# Cancel all active syncs (closes PRs and deletes branches)
go-broadcast cancel --config sync.yaml

# Cancel syncs for specific repositories only
go-broadcast cancel company/service1 company/service2

# Preview what would be cancelled without making changes
go-broadcast cancel --dry-run --config sync.yaml

# Close PRs but keep sync branches for later cleanup
go-broadcast cancel --keep-branches --config sync.yaml

# Add custom comment when closing PRs
go-broadcast cancel --comment "Cancelling due to template update" --config sync.yaml

🌐 Global PR Assignment Configuration

The global section allows you to define PR assignments (labels, assignees, reviewers, team reviewers) that are merged with target-specific assignments rather than overridden. This provides powerful control over PR workflows across all repositories.

How It Works

Merge Priority: global + target → defaults (fallback)

Global settings apply to ALL target repositories
Target settings are merged with global settings (duplicates removed)
Default settings are used only when neither global nor target settings exist

Example Configuration

version: 1
source:
  repo: "org/template-repo"
  branch: "master"

# Applied to ALL PRs across all targets
global:
  pr_labels: ["automated-sync", "chore"]
  pr_assignees: ["platform-team"]
  pr_reviewers: ["platform-lead"]
  pr_team_reviewers: ["infrastructure-team"]

# Fallback settings (used only if no global/target assignments)
defaults:
  branch_prefix: "chore/sync-files"
  pr_labels: ["maintenance"]

targets:
  # This repo gets ONLY global settings
  - repo: "org/service-a"
    files:
      - src: ".github/workflows/ci.yml"
        dest: ".github/workflows/ci.yml"
    # Effective PR settings:
    # Labels: ["automated-sync", "chore"]
    # Assignees: ["platform-team"]
    # Reviewers: ["platform-lead"]
    # Team reviewers: ["infrastructure-team"]

  # This repo gets global + target merged
  - repo: "org/service-b"
    files:
      - src: ".github/workflows/ci.yml"
        dest: ".github/workflows/ci.yml"
    pr_labels: ["critical", "service-b"]
    pr_assignees: ["service-b-owner"]
    # Effective PR settings (merged):
    # Labels: ["automated-sync", "chore", "critical", "service-b"]
    # Assignees: ["platform-team", "service-b-owner"]
    # Reviewers: ["platform-lead"] (from global)
    # Team reviewers: ["infrastructure-team"] (from global)

Use Cases

Organization-wide standards: Apply consistent labels and assignees across all repositories
Platform team oversight: Ensure platform team is always assigned to infrastructure changes
Security requirements: Add security team reviewers to all template updates
Compliance labeling: Automatically tag all PRs with audit/compliance labels

📚 Documentation

Quick Start – Get up and running in 5 minutes with the Quick Start guide
Usage Examples – Real-world scenarios in the Usage Examples section
Directory Sync Guide – Complete guide to directory synchronization including exclusion patterns and performance tips at docs/directory-sync.md
Configuration Reference – Comprehensive configuration options including global PR assignment merging
Configuration Examples – Browse practical patterns in the examples directory
Troubleshooting – Solve common issues with the troubleshooting guide
API Reference – Dive into the godocs at pkg.go.dev/github.com/mrz1836/go-broadcast
Integration Tests – End-to-end testing examples in test/integration
Internal Utilities – Shared testing and validation utilities in internal packages
Performance – Check the latest numbers in the Performance section

📦 Repository Features

Continuous Integration on Autopilot with GitHub Actions – every push is built, tested, and reported in minutes.
Pull‑Request Flow That Merges Itself thanks to auto‑merge and hands‑free Dependabot auto‑merge.
One‑Command Builds powered by battle‑tested Make targets for linting, testing, releases, and more.
First‑Class Dependency Management using native Go Modules.
Uniform Code Style via gofumpt plus zero‑noise linting with golangci‑lint.
Confidence‑Boosting Tests with testify, the Go race detector, crystal‑clear HTML coverage snapshots, and automatic reporting via internal coverage system.
Hands‑Free Releases delivered by GoReleaser whenever you create a new Tag.
Relentless Dependency & Vulnerability Scans via Dependabot, Nancy, govulncheck, and OSSAR.
Security Posture by Default with CodeQL, OpenSSF Scorecard, OSSAR, and secret‑leak detection via gitleaks.
Automatic Syndication to pkg.go.dev on every release for instant godoc visibility.
Polished Community Experience using rich templates for Issues & PRs.
All the Right Meta Files (LICENSE, CITATION.cff, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SUPPORT.md, SECURITY.md) pre‑filled and ready.
Code Ownership clarified through a CODEOWNERS file, keeping reviews fast and focused.
Zero‑Noise Dev Environments with tuned editor settings (.editorconfig) plus curated ignore files for VS Code, Docker, and Git.
Label Sync Magic: your repo labels stay in lock‑step with .github/labels.yml.
Friendly First PR Workflow – newcomers get a warm welcome thanks to a dedicated workflow.
Standards‑Compliant Docs adhering to the standard‑readme spec.
Instant Cloud Workspaces via Gitpod – spin up a fully configured dev environment with automatic linting and tests.
Out‑of‑the‑Box VS Code Happiness with a preconfigured Go workspace and .vscode folder with all the right settings.
Optional Release Broadcasts to your community via Slack, Discord, or Twitter – plug in your webhook.
AI Compliance Playbook – machine‑readable guidelines (AGENTS.md, CLAUDE.md, .cursorrules, sweep.yaml) keep ChatGPT, Claude, Cursor & Sweep aligned with your repo's rules.
Pre-commit Hooks for Consistency powered by pre-commit and the .pre-commit-config.yaml file—run the same formatting, linting, and tests before every commit, just like CI.
Automated Hook Updates keep the .pre-commit-config.yaml current via a weekly workflow.
DevContainers for Instant Onboarding – Launch a ready-to-code environment in seconds with VS Code DevContainers and the included .devcontainer.json config.

🚀 Library Deployment

This project uses goreleaser for streamlined binary and library deployment to GitHub. To get started, install it via:

brew install goreleaser

The release process is defined in the .goreleaser.yml configuration file.

To generate a snapshot (non-versioned) release for testing purposes, run:

make release-snap

Before tagging a new version, update the release metadata (version) in the CITATION.cff file:

make citation version=0.2.1

Then create and push a new Git tag using:

make tag version=x.y.z

This process ensures consistent, repeatable releases with properly versioned artifacts and citation metadata.

🔨 Makefile Commands

View all makefile commands

make help

List of all current commands:

bench                 ## Run all benchmarks in the Go application
bench-compare         ## Run benchmarks and save results for comparison
bench-cpu             ## Run benchmarks with CPU profiling
bench-full            ## Run comprehensive benchmarks with multiple iterations
bench-save            ## Save current benchmark results as baseline
build-go              ## Build the Go application (locally)
citation              ## Update version in CITATION.cff (use version=X.Y.Z)
clean-mods            ## Remove all the Go mod cache
coverage              ## Show test coverage
diff                  ## Show git diff and fail if uncommitted changes exist
fumpt                 ## Run fumpt to format Go code
generate              ## Run go generate in the base of the repo
godocs                ## Trigger GoDocs tag sync
govulncheck-install   ## Install govulncheck (pass VERSION= to override)
govulncheck           ## Scan for vulnerabilities
help                  ## Display this help message
install-go            ## Install using go install with specific version
install-releaser      ## Install GoReleaser
install-stdlib        ## Install the Go standard library for the host platform
install               ## Install the application binary
lint-version          ## Show the golangci-lint version
lint                  ## Run the golangci-lint application (install if not found)
loc                   ## Total lines of code table
mod-download          ## Download Go module dependencies
mod-tidy              ## Clean up go.mod and go.sum
pre-build             ## Pre-build all packages to warm cache
release-snap          ## Build snapshot binaries
release-test          ## Run release dry-run (no publish)
release               ## Run production release (requires github_token)
tag-remove            ## Remove local and remote tag (use version=X.Y.Z)
tag-update            ## Force-update tag to current commit (use version=X.Y.Z)
tag                   ## Create and push a new tag (use version=X.Y.Z)
test-ci-no-race       ## CI test suite without race detector
test-ci               ## CI test runs tests with race detection and coverage (no lint - handled separately)
test-cover-race       ## Runs unit tests with race detector and outputs coverage
test-cover            ## Unit tests with coverage (no race)
test-fuzz             ## Run fuzz tests only (no unit tests)
test-no-lint          ## Run only tests (no lint)
test-parallel         ## Run tests in parallel (faster for large repos)
test-race             ## Unit tests with race detector (no coverage)
test-short            ## Run tests excluding integration tests (no lint)
test                  ## Default testing uses lint + unit tests (fast)
uninstall             ## Uninstall the Go binary
update-linter         ## Upgrade golangci-lint (macOS only)
update-releaser       ## Reinstall GoReleaser
update                ## Update dependencies
vet-parallel          ## Run go vet in parallel (faster for large repos)
vet                   ## Run go vet only on your module packages

⚡ GitHub Workflows

🎛️ The Workflow Control Center

All GitHub Actions workflows in this repository are powered by a single configuration file: .env.shared – your one-stop shop for tweaking CI/CD behavior without touching a single YAML file! 🎯

This magical file controls everything from:

⚙️ Go version matrix (test on multiple versions or just one)
🏃 Runner selection (Ubuntu or macOS, your wallet decides)
🔬 Feature toggles (coverage, fuzzing, linting, race detection, benchmarks)
🛡️ Security tool versions (gitleaks, nancy, govulncheck)
🤖 Auto-merge behaviors (how aggressive should the bots be?)
🏷️ PR management rules (size labels, auto-assignment, welcome messages)

Pro tip: Want to disable code coverage? Just flip ENABLE_CODE_COVERAGE=false in .env.shared and push. No YAML archaeology required!

Workflow Name	Description
auto-merge-on-approval.yml	Automatically merges PRs after approval and all required checks, following strict rules.
codeql-analysis.yml	Analyzes code for security vulnerabilities using GitHub CodeQL.
dependabot-auto-merge.yml	Automatically merges Dependabot PRs that meet all requirements.
fortress.yml	Runs the GoFortress security and testing workflow, including linting, testing, releasing, and vulnerability checks.
ossar.yml	Runs OSSAR static analysis workflow
pull-request-management.yml	Labels PRs by branch prefix, assigns a default user if none is assigned, and welcomes new contributors with a comment.
scorecard.yml	Runs OpenSSF Scorecard to assess supply chain security.
stale.yml	Warns about (and optionally closes) inactive issues and PRs on a schedule or manual trigger.
sync-labels.yml	Keeps GitHub labels in sync with the declarative manifest at `.github/labels.yml`.
update-python-dependencies.yml	Updates Python dependencies for pre-commit hooks in the repository.
update-pre-commit-hooks.yml	Automatically update versions for pre-commit hooks

📦 Updating Dependencies

To update all dependencies (Go modules, linters, and related tools), run:

make update

This command ensures all dependencies are brought up to date in a single step, including Go modules and any tools managed by the Makefile. It is the recommended way to keep your development environment and CI in sync with the latest versions.

🔧 Pre-commit Hooks

Set up the optional pre-commit hooks to run the same formatting, linting, and tests defined in AGENTS.md before every commit:

pip install pre-commit
pre-commit install

The hooks are configured in .pre-commit-config.yaml and mirror the CI pipeline.

🐛 Logging and Debugging

go-broadcast provides comprehensive logging capabilities designed for debugging, monitoring, and troubleshooting. The logging system features intuitive verbose flags, component-specific debug modes, and automatic sensitive data redaction.

Quick Start

# Basic logging levels
go-broadcast sync --log-level debug     # Debug level logging
go-broadcast sync --log-level info      # Info level logging (default)
go-broadcast sync --log-level warn      # Warning level logging
go-broadcast sync --log-level error     # Error level logging

# Collect comprehensive diagnostic information
go-broadcast diagnose                    # Display diagnostic info to stdout
go-broadcast diagnose > diagnostics.json # Save diagnostics to file for support

Note: Advanced verbose flags (-v, -vv, -vvv) and component-specific debug flags (--debug-git, --debug-api, etc.) are planned features not yet implemented. The current implementation supports --log-level for basic debugging.

Log Levels

ERROR: Critical failures that prevent operation
WARN: Important issues that don't stop execution
INFO: High-level operation progress (default)
DEBUG: Detailed operation information (--log-level debug)

Advanced Logging Features

Performance Monitoring

All operations are timed automatically. Look for duration_ms in logs:

# Find slow operations
go-broadcast sync --log-format json 2>&1 | \
  jq -r 'select(.duration_ms > 5000) | "\(.operation): \(.duration_ms)ms"'

Security and Compliance

All tokens and secrets are automatically redacted
Audit trail for configuration changes and repository access
No sensitive data is ever logged

Troubleshooting Common Issues

Git Authentication Issues

# Enable debug logging to see git operations
go-broadcast sync --log-level debug

# Common indicators:
# - "Authentication failed" in git output
# - "Permission denied" errors
# - Check GH_TOKEN or GITHUB_TOKEN environment variables

API Rate Limiting

# Monitor operations with debug logging
go-broadcast sync --log-level debug 2>&1 | grep -i "rate"

File Transformation Issues

# Use debug logging to see operation details
go-broadcast sync --log-level debug

# Debug output shows:
# - File operations
# - Configuration processing
# - Error details

State Discovery Problems

# Enable debug logging for repository state information
go-broadcast sync --log-level debug

# Debug output includes:
# - Repository access attempts
# - Branch discovery
# - File discovery process

Log Management

Debug Sessions

# Save debug session
go-broadcast sync --log-level debug 2> debug-$(date +%Y%m%d-%H%M%S).log

# Review debug logs
go-broadcast sync --log-level debug 2>&1 | tee sync-debug.log

Diagnostic Information Collection

The diagnose command collects comprehensive system information for troubleshooting:

# Collect all diagnostic information (JSON format)
go-broadcast diagnose

# Information collected includes:
# - System details (OS, architecture, CPU count, hostname)
# - go-broadcast version and build information
# - Git and GitHub CLI versions
# - Environment variables (sensitive data automatically redacted)
# - Configuration file status and validation results
# - Timestamp and runtime information

Note: JSON log format (--log-format json) is a planned feature. The diagnose command provides JSON output for system information.

Environment Variables

Variable	Description	Example
`NO_COLOR`	Disable colored output	`1`

Note: Environment variables for log level and format are planned features not yet implemented.

For more detailed information, see the comprehensive logging guide and troubleshooting runbook.

📊 Coverage System

🚀 Coverage System

Self-hosted coverage solution - Complete data privacy, zero external dependencies, and enterprise-grade features.

🔗 View Dashboard

📊 Quick Setup

⚡ Quick Setup

Enable in 2 steps:

# 1. Enable in .github/.env.shared
ENABLE_INTERNAL_COVERAGE=true
COVERAGE_FAIL_UNDER=80

# 2. Set GitHub Pages source to "GitHub Actions"
# Repository Settings → Pages → Source → "GitHub Actions"

That's it! Push any commit and get:

✅ Professional coverage badges
✅ Interactive dashboard
✅ PR comments with analysis
✅ GitHub Pages deployment

🎯 Complete Feature List & Advanced Configuration

Core Features

Professional Coverage Badges

GitHub-style badges with multiple themes (flat, flat-square, for-the-badge)
Real-time updates on every push and pull request
Branch-specific badges for master and PR branches
PR-specific badges for pull request analysis

Interactive Coverage Dashboard

Modern, responsive UI with dark/light theme support
Real-time metrics with animated progress indicators
Historical trend showing trend from last push
Responsive design that works on desktop and mobile
Zero external dependencies - fully self-contained

Intelligent PR Coverage Comments

Coverage analysis comparing base vs PR branches
File-level breakdown showing coverage changes
Smart anti-spam logic to prevent comment noise on multiple pushes
Comprehensive PR comments with detailed coverage analysis

Analytics & Insights

Google Analytics integration for detailed usage tracking
Historical trend tracking with basic trend analysis
Coverage history stored in JSON format
Retention policies for automatic data cleanup

GitHub Pages Deployment

Automatic GitHub Pages integration with organized storage
PR-specific deployments with isolated coverage reports
Automatic cleanup of expired PR data
Simple CLI with 3 core commands (complete, comment, history)

Advanced Configuration

The coverage system includes 45+ configuration options for complete customization:

🎨 Badge & Theme Configuration

COVERAGE_BADGE_STYLE=flat                # flat, flat-square, for-the-badge
COVERAGE_BADGE_LOGO=                     # Logo: go, github, custom URL (empty for no logo)
COVERAGE_REPORT_THEME=github-dark        # Dashboard theme
COVERAGE_THRESHOLD_EXCELLENT=90          # Green badge threshold
COVERAGE_THRESHOLD_GOOD=80               # Yellow-green threshold

📊 Analytics & Reporting

COVERAGE_ENABLE_TREND_ANALYSIS=true      # Historical trend tracking
COVERAGE_ENABLE_PACKAGE_BREAKDOWN=true   # Package-level coverage
COVERAGE_HISTORY_RETENTION_DAYS=90       # Data retention period
COVERAGE_CLEANUP_PR_AFTER_DAYS=7         # PR cleanup schedule

🔔 PR Comment Configuration

COVERAGE_PR_COMMENT_ENABLED=true         # Enable PR comments
COVERAGE_PR_COMMENT_SHOW_TREE=true       # Show file tree in PR comments
COVERAGE_PR_COMMENT_SHOW_MISSING=true    # Highlight uncovered lines
COVERAGE_PR_COMMENT_BEHAVIOR=update      # Comment behavior: new, update, delete-and-new

GitHub Pages URLs

Main Branch Coverage

Coverage Badge: https://mrz1836.github.io/go-broadcast/coverage.svg
Coverage Dashboard: https://mrz1836.github.io/go-broadcast/
Coverage Report: https://mrz1836.github.io/go-broadcast/coverage.html

Branch-Specific Coverage

Branch Badge: https://mrz1836.github.io/go-broadcast/coverage/branch/{branch-name}/coverage.svg
Branch Dashboard: https://mrz1836.github.io/go-broadcast/coverage/branch/{branch-name}/
Branch Report: https://mrz1836.github.io/go-broadcast/coverage/branch/{branch-name}/coverage.html

Pull Request Coverage

PR Badge: https://mrz1836.github.io/go-broadcast/coverage/pr/{pr-number}/coverage.svg
PR Coverage Report: https://mrz1836.github.io/go-broadcast/coverage/pr/{pr-number}/
All Branches Index: https://mrz1836.github.io/go-broadcast/branches.html (when deployed from main)

📚 Complete Configuration Guide | 📊 API Documentation | 🎯 Feature Guide

🧪 Examples & Tests

All unit tests and examples run via GitHub Actions and use Go version 1.24.x. View the configuration file.

Run all tests (fast):

make test

Run all tests with race detector (slower):

make test-race

⚡ Performance

Enterprise-grade performance - Designed for high-scale repository management with zero-allocation critical paths.

Performance Highlights

Operation	Performance	Memory
Binary Detection	587M+ ops/sec	Zero allocations
Content Comparison	239M+ ops/sec	Zero allocations
Cache Operations	13.5M+ ops/sec	Minimal memory
Batch Processing	23.8M+ ops/sec	Concurrent safe
Directory Sync	32ms/1000 files	Linear scaling
Exclusion Engine	107ns/op	Zero allocations

Quick Benchmarks

# Run all benchmarks
make bench

# Benchmark specific components
go test -bench=. -benchmem ./internal/git
go test -bench=. -benchmem ./internal/worker

# Try the profiling demo
go run ./cmd/profile_demo

📊 Complete Benchmark Results & Profiling Tools

Performance Analysis Tools

🔬 100+ Benchmarks covering all major components
📊 CPU & Memory Profiling with detailed analysis
📈 Performance Reports in HTML, JSON, and Markdown
🔍 Goroutine Analysis for concurrency debugging
⚡ Zero-Allocation operations in critical paths

Complete Performance Results

The following benchmarks were run on Apple M1 Max (updated January 2025):

Benchmark	Operations	ns/op	B/op	allocs/op
Core Algorithms
BinaryDetection (Small Text)	5,852,616	204.5	0	0
BinaryDetection (Large Text)	179,217	6,606	0	0
BinaryDetection (Small Binary)	335,143,730	3.6	0	0
BinaryDetection (Large Binary)	587,204,924	2.0	0	0
DiffOptimized (Identical)	239,319,295	5.0	0	0
DiffOptimized (Different)	4,035,818	297.2	240	10
DiffOptimized (Large Similar)	250,452	4,711	5,492	7
BatchProcessor	23,842,558	54.3	25	1
Cache Operations
Cache Set	6,067,380	177.4	48	4
Cache Get (Hit)	11,481,175	103.8	7	1
Cache Get (Miss)	13,565,466	89.4	32	2
Cache GetOrLoad	11,330,936	106.2	16	1
Performance Profiling
CaptureMemStats	58,352	20,476	0	0
CaptureMemoryStats	3,475	302,402	107	4
MeasureOperation	4,032	316,467	107	4

Performance Characteristics

go-broadcast is designed for efficiency:

Binary detection executes 587M+ operations/second with zero allocations for binary files
Content comparison performs 239M+ operations/second for identical files with zero allocations
Cache operations handle 13.5M+ get operations/second with minimal memory usage
Batch processing manages 23.8M+ operations/second for concurrent tasks
Memory profiling captures detailed statistics at 58K+ operations/second
Performance monitoring measures operations at 3K+ captures/second with comprehensive metrics
Zero-allocation paths optimized algorithms avoid memory allocation in critical operations
Concurrent operations sync multiple repositories simultaneously (configurable concurrency)
GitHub API optimization reduces API calls through intelligent state discovery
Memory efficiency most core operations use minimal allocations
Test coverage maintained at >85% across core packages with comprehensive error handling

Performance varies based on GitHub API rate limits, network conditions, and repository sizes.

Profiling Documentation

📚 Complete Guides:

Benchmarking Guide - Complete benchmarking reference
Profiling Guide - Advanced profiling techniques
Performance Optimization - Best practices and tips

🛠️ Code Standards

Read more about this Go project's code standards.

🤖 AI Compliance

This project documents expectations for AI assistants using a few dedicated files:

AGENTS.md — canonical rules for coding style, workflows, and pull requests used by Codex.
CLAUDE.md — quick checklist for the Claude agent.
.cursorrules — machine-readable subset of the policies for Cursor and similar tools.
sweep.yaml — rules for Sweep, a tool for code review and pull request management.

Edit AGENTS.md first when adjusting these policies, and keep the other files in sync within the same pull request.

👥 Maintainers


MrZ

🤝 Contributing

View the contributing guidelines and please follow the code of conduct.

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬. You can also support this project by becoming a sponsor on GitHub 👏 or by making a bitcoin donation to ensure this journey continues indefinitely! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 431 Commits
.github		.github
.make		.make
.vscode		.vscode
assets		assets
cmd		cmd
docs		docs
examples		examples
internal		internal
plans		plans
scripts		scripts
test		test
.cursorrules		.cursorrules
.devcontainer.json		.devcontainer.json
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitpod.yml		.gitpod.yml
.golangci.json		.golangci.json
.goreleaser.yml		.goreleaser.yml
.pre-commit-config.yaml		.pre-commit-config.yaml
CITATION.cff		CITATION.cff
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum

Uh oh!

License

mrz1836/go-broadcast

Folders and files

Latest commit

History

Repository files navigation