GoMajor

A fast, color-coded CLI tool designed to help you keep your Go dependencies up-to-date. GoMajor parses your go.mod files and queries the Go Module Proxy to proactively discover both minor updates (🟢 Green) and major upgrades (🟡 Yellow).

💡 Why GoMajor?

Standard commands like go list -m -u all are great for finding minor updates, but they completely miss new major versions. Because Go treats different major versions (e.g., github.com/foo/bar vs github.com/foo/bar/v2) as entirely separate modules, standard tools won't notify you when a library releases a new major version.

GoMajor bridges this gap, ensuring you never miss a critical major release again.

✨ Key Features

• 🚀 Discover Major Upgrades: Finds new major versions (v2, v3+) that standard Go tools miss.
• 🌐 Remote Scanning: Check dependencies directly from remote GitHub repositories without cloning.
• 🎨 Clear Visuals: Color-coded terminal output for quick identification of update types.
• ⚙️ Multi-Source Config: Check multiple local projects and remote repositories at once using a yaml config.
• 📊 CI/CD Ready: Export dependency reports to structured JSON or YAML formats.

---

Quick Start

Installation

# Install instantly
go install github.com/chimanjain/gomajor@latest

# Or build from source
git clone https://github.com/chimanjain/gomajor.git && cd gomajor && go build -o gomajor

Basic CLI Usage

# Check direct dependencies in the current directory
gomajor

# Check all (including indirect) dependencies for a specific file
gomajor -f /path/to/go.mod --all

# Disable minor or major checks explicitly
gomajor --minor=false
gomajor --major=false

# Check remote GitHub repositories directly
gomajor -g owner/repo,github.com/owner/repo2

# Check dependencies and save results directly to a structured report
gomajor -o report.json

---

Configuration & Flags

CLI Flags

Flag	Shorthand	Description	Default	Example
--file	-f	Path to target go.mod file	"" (auto-detect)	gomajor -f ./sub/go.mod
--all	-a	Check indirect dependencies too	false	gomajor -a
--max-probe	-m	Max subsequent major versions to probe	5	gomajor -m 10
--minor		Toggle minor version updates checking	true	gomajor --minor=false
--major		Toggle major version upgrades checking	true	gomajor --major=false
--config	-c	Path to multi-source YAML config file	"gomajor.yaml"	gomajor -c my-config.yaml
--github	-g	Direct comma-separated GitHub repositories	""	gomajor -g owner/repo
--output	-o	Save results to a structured YAML or JSON report file	""	gomajor -o report.json
--json		Format reports and stdout data in JSON	false	gomajor --json
--no-color		Suppress ANSI colored terminal formatting	false	gomajor --no-color

Multi-Source Checking (gomajor.yaml)

Define multiple local directories and remote GitHub repositories to analyze in a single run:

local:
  - "/path/to/project1/go.mod"
github:
  - "owner/repo"
  - "https://github.com/owner/repo2/blob/develop/go.mod"
output: "gomajor-report.json" # Supports both .yaml and .json formats
minor: true
major: true

GitHub Actions Integration

You can integrate GoMajor into your CI/CD pipelines to automatically audit direct and indirect dependencies for both minor updates and major upgrades.

Add the following workflow file to .github/workflows/gomajor-dependency-audit.yml:

name: GoMajor Dependency Audit
permissions:
  contents: read
on:
  pull_request:
    branches: [main]

jobs:
  gomajor-dependency-audit:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v6

      - name: Set up Go
        uses: actions/setup-go@v6
        with:
          go-version: "1.26"

      - name: Install GoMajor
        run: go install github.com/chimanjain/gomajor@latest

      - name: Run Dependency Audit
        run: gomajor

Environment Variables

GoMajor respects the standard Go module proxy env:

• GOPROXY: Specifies the Go module proxy URL (defaults to https://proxy.golang.org).

---

Output Examples

Terminal Format (Default)

https://raw.githubusercontent.com/spf13/cobra/main/go.mod (github)
  MODULE               CURRENT   MINOR     MAJOR         NEW PATH
  go.yaml.in/yaml/v3   v3.0.4    -         v4.0.0-rc.4   go.yaml.in/yaml/v4

YAML Report Format

results:
  - source: https://raw.githubusercontent.com/spf13/cobra/main/go.mod
    source_type: github
    dependencies:
      - module: go.yaml.in/yaml/v3
        current_version: v3.0.4
        latest_major_version: v4.0.0-rc.4
        latest_major_path: go.yaml.in/yaml/v4
        has_update: true

JSON Report Format

{
  "results": [
    {
      "source": "https://raw.githubusercontent.com/spf13/cobra/main/go.mod",
      "source_type": "github",
      "dependencies": [
        {
          "module": "go.yaml.in/yaml/v3",
          "current_version": "v3.0.4",
          "latest_major_version": "v4.0.0-rc.4",
          "latest_major_path": "go.yaml.in/yaml/v4",
          "has_update": true
        }
      ]
    }
  ]
}

---

Development & Architecture

Testing

go test -cover ./...

Architecture

• checker: Core engine for querying the Go Module Proxy.
• utils: Centralized, zero-dependency package for Go module path parsing, version path formatting, and proxy path escaping.
• cmd: Decoupled CLI architecture built with Cobra:
  • runner.go: Core execution flow routing and concurrent proxy checking.
  • formatter.go / types.go: Output visualization and reporting structures.
  • github.go / root.go: Remote path parsing and Cobra commands bootstrapping.