gogit

gogit

Generic, dependency-light Git ergonomics for Go, by shelling out to the git CLI: repository discovery, commit-log parsing with trailers (Co-authored-by) and change stats, AI authorship detection, conventional commit parsing, parallel multi-repo execution, calendar-date filtering, branch/origin metadata, remote-URL normalization, tag dates, and exposure queries (which refs and tagged releases contain a commit or path, every file ever committed, and ignored local files). The base layer for higher-level tools — including the bundled gitscan CLI and the OmniDevX telemetry collectors — in the same way gogithub underlies GitHub integrations.

repo, _ := gogit.Open("/path/to/repo")
commits, _ := repo.Log(ctx, gogit.LogOptions{
    Since:        weekStart,
    IncludeStats: true,
    Reverse:      true,
})
for _, c := range commits {
    attr := gogit.AnalyzeAuthorship(c)
    fmt.Println(c.Hash, c.Author.Email, attr.Tools, c.Insertions)
}

Library Features

Renamed from gitscan (the CLI lives on at cmd/gitscan).

Exposure Queries

Four Repo methods answer how far a commit or file has travelled — the follow-up question once a scan finds something that should not have been committed:

refs, _ := repo.RefsContaining(ctx, "a1b2c3d")        // branches, remotes, tags containing a commit
tags, _ := repo.TagsWithPath(ctx, "config/local.env")  // tagged releases whose tree has the path
added, _ := repo.FilesEverAdded(ctx)                   // every path ever committed, incl. deleted
ignored, _ := repo.IgnoredFiles(ctx)                   // untracked, ignored local paths

A tag can be downstream of the commit that added a file without containing the file (if it was deleted before tagging); TagsWithPath is the check that distinguishes "only in history" from "shipped in a release." See the docs for details.

gitgrep Package

github.com/grokify/gogit/gitgrep is a policy-free primitive for searching a repository's content and history: callers supply patterns and get matches back, with no built-in notion of what a match means, so it's a general-purpose building block rather than a leak/secret scanner itself. It shells out to native git (git grep, the pickaxe, and streamed git log -p patches) — the fastest and most portable approach.

matches, err := gitgrep.GrepTree(ctx, repoPath, gitgrep.Options{
    Patterns: []gitgrep.Pattern{{Value: "Acme Corp", IgnoreCase: true}},
})

Match.Text and Patch.Hunk are returned verbatim; redacting them before display or logging is the caller's responsibility. See the gitgrep design note for the full API, git-command mapping, and caveats (tracked-content-only, exhaustive-history cost, regex dialect).

gitscan CLI

A CLI tool to scan multiple Git repositories and identify repos that need attention. Helps prioritize which repos to update, commit, and push.

Installation

Homebrew (macOS/Linux)

brew tap grokify/tap
brew install gitscan

Go Install

go install github.com/grokify/gogit/cmd/gitscan@latest

Build from Source

git clone https://github.com/grokify/gogit.git
cd gogit
go build -o gitscan ./cmd/gitscan

Usage

gitscan [directory]              # Scan for issues (defaults to current dir)
gitscan since <duration> [dir]   # Filter by modification time
gitscan dep <module> [dir]       # Filter by dependency
gitscan order [dir]              # Show repos in dependency order
gitscan pending [path...]        # List unpushed commits, across one or many repos
gitscan pushed [count] [dir]     # List the most recent pushed commits
gitscan grep -e <pattern> [dir]  # Search content or history for one or more patterns

The scan directory is a positional argument that defaults to the current directory; there is no -d/--dir flag.

Root Command (Issue Scanning)

Scan repos for uncommitted changes, replace directives, and module mismatches:

gitscan ~/go/src/github.com/grokify

The directory to scan is the (optional) positional argument, defaulting to the current directory.

Examples

# Scan all repos in a directory
gitscan ~/go/src/github.com/grokify

# Output as markdown table (compact view)
gitscan -f table ~/go/src/github.com/grokify

# Show all repos including clean ones
gitscan --show-clean ~/projects

Since Subcommand

Filter repos by modification time, with optional dependency filtering:

gitscan since <duration> [directory]

Duration formats: 7d (days), 2w (weeks), 1m (months), 24h (hours). directory defaults to the current directory.

Since Examples

# Repos modified in last 7 days
gitscan since 7d ~/go/src/github.com/grokify

# Repos modified in last 7 days AND depending on a module
gitscan since 7d --dep github.com/grokify/mogo ~/go/src/github.com/grokify

Dep Subcommand

Filter repos by dependency on a specific module:

gitscan dep <module> [directory]

Dep Examples

# Find repos depending on a module
gitscan dep github.com/grokify/mogo ~/go/src/github.com/grokify

# Include nested go.mod files (monorepos)
gitscan dep github.com/grokify/mogo -r ~/go/src/github.com/grokify

# Only repos that require the module themselves, not just transitively
gitscan dep github.com/google/go-github/v88 ~/go/src/github.com/grokify --direct-only

# Match any major version of a module in one pass
gitscan dep github.com/google/go-github ~/go/src/github.com/grokify --prefix --direct-only

Pending Subcommand

Report commits that are ahead of their upstream — not yet pushed — across one or more repositories. Useful for pre-push review, for a morning sweep of everything you have waiting to push, or for feeding an agent a structured list of what's about to go out.

gitscan pending [path...]

Each path is either a git repository (reported directly) or a directory whose repositories are discovered (one level deep by default; use --depth to go deeper) and each reported in turn. Pass several paths — e.g. one per GitHub org you manage — to sweep them together. With no path, the current directory is used.

By default the baseline for "pending" is each branch's push target — its configured upstream, or the matching remote-tracking branch (e.g. origin/main). A branch that has never been pushed under its own name — the common case right after git checkout -b — falls back to the remote's default branch (e.g. origin/main), so only commits unique to the branch are reported rather than its parent branch's entire history. Only when the remote has no default branch to fall back to (nothing has ever been pushed to it) are all local commits reported as pending. Use --since-commit to list commits after a specific hash instead; that applies to a single repository only.

The output shape is invariant in the number of repositories: a single repo is just a fleet of one. In a multi-repo sweep, repositories with nothing pending are omitted from the table/markdown views (the summary still counts them), and progress is shown on stderr so stdout stays clean for piping and JSON.

Timestamps are RFC 3339 with an explicit UTC offset (Z for exact UTC, otherwise numeric, e.g. -07:00). By default each commit keeps its own recorded timezone; --tz utc or --tz local converts every timestamp to one consistent zone.

Pending Examples

# Unpushed commits in the current repo
gitscan pending

# ...in another repo
gitscan pending ~/go/src/github.com/me/repo

# Sweep every repo across several orgs you manage
gitscan pending ~/go/src/github.com/{myorg,myuser}

# Commits after a specific hash (single repo)
gitscan pending --since-commit abc1234

# Copy-pasteable markdown table (e.g. for a PR description)
gitscan pending --format markdown

# Machine-readable output for agents
gitscan pending --format json

# Normalize all timestamps to UTC (or --tz local for this machine's timezone)
gitscan pending --tz utc

Pending Output

Table format (default; aligned columns via text/tabwriter, meant to be read directly in a terminal). A multi-repo sweep prints one section per repo with pending work, then a summary:

Repo: /Users/me/go/src/github.com/myorg/service-a (branch: main)
Pending commits (not yet pushed to @{upstream}): 2

#  HASH     DAY  TIMESTAMP                  MESSAGE
1  1fbde76  Mon  2026-09-07T12:16:02-07:00  feat: add b
2  af0101e  Mon  2026-09-07T12:16:05-07:00  feat: add c

Repo: /Users/me/go/src/github.com/myorg/service-b (branch: feat/new-thing)
Pending commits (no upstream configured; all local commits unpushed): 1

#  HASH     DAY  TIMESTAMP                  MESSAGE
1  9c1d2e0  Tue  2026-09-08T09:03:11-07:00  feat: initial import

Summary: 42 repos scanned, 2 with unpushed commits, 3 commits total

The header always names the current branch, since "no upstream configured" on a fresh feature branch is easy to misread as unpushed work on main without it.

Markdown format (--format markdown; valid GitHub-flavored markdown, e.g. for pasting into a PR description or issue):

| # | Hash | Day | Timestamp | Message |
|---|------|-----|-----------|---------|
| 1 | 1fbde76 | Mon | 2026-09-07T12:16:02-07:00 | feat: add b |
| 2 | af0101e | Mon | 2026-09-07T12:16:05-07:00 | feat: add c |

JSON format (--format json) is always a repos array plus a summary, whether one repository or many — so consumers never branch on repo count:

{
  "repos": [
    {
      "repo": "/Users/me/go/src/github.com/myorg/service-a",
      "branch": "main",
      "mode": "unpushed",
      "ref": "@{upstream}",
      "count": 2,
      "commits": [
        {
          "hash": "1fbde76e3b4c9ff29974e52b2e67bcece53ddaf6",
          "weekday": "Mon",
          "date": "2026-09-07",
          "time": "12:16:02",
          "timestamp": "2026-09-07T12:16:02-07:00",
          "message": "feat: add b"
        }
      ]
    }
  ],
  "summary": {
    "reposScanned": 42,
    "reposWithCommits": 2,
    "commitsTotal": 3
  }
}

The mode field is one of unpushed (ahead of the push baseline in ref — the branch's own push target, or the remote's default branch as a fallback), unpushed-all (no baseline resolved at all — every local commit is pending), or since-commit (commits after the ref hash).

Pushed Subcommand

The counterpart to pending: list the most recent commits already pushed on a repository's current branch — those reachable from its push target (upstream or matching remote-tracking branch) — newest first. Together, pending and pushed show the recent commits on either side of what has reached the remote.

gitscan pushed [count] [directory]

count is the number of commits to show and defaults to 10; directory defaults to the current directory. Either positional may be given in either order (the numeric one is the count). When the branch has no push target, nothing is reported as pushed.

Pushed Examples

# Last 10 pushed commits in the current repo
gitscan pushed

# Last 25 pushed commits
gitscan pushed 25

# ...in another repo (count and directory in either order)
gitscan pushed 25 ~/go/src/github.com/me/repo

# Machine-readable output for agents
gitscan pushed --format json

Pushed Output

Repo: /Users/me/go/src/github.com/me/repo (branch: main)
Pushed commits (most recent first, from @{upstream}): 3

#  HASH     DAY  TIMESTAMP                  MESSAGE
1  90da58c  Mon  2026-09-07T20:41:29-07:00  fix(release): target the current repo name in goreleaser config
2  882488a  Mon  2026-09-07T19:43:37-07:00  docs: update changelog for the full commit range
3  d5f5fa1  Mon  2026-09-07T18:12:04-07:00  feat(cmd): show RFC3339 timestamps with weekday

pushed shares pending's markdown and json formats (the same invariant repos + summary envelope, with mode set to pushed).

Grep Subcommand

Search a single repository's content or history for one or more patterns, backed by the gitgrep package.

gitscan grep -e <pattern> [-e <pattern>...] [directory]

By default the working tree is searched (tracked files). directory defaults to the current directory and must be a git repository.

Grep Examples

# Working tree, case-insensitive
gitscan grep -e "Acme Corp" -i ./

# Staged (index) content — a pre-commit surface
gitscan grep -e ExampleCo --staged

# Extended regex
gitscan grep -e "SECRET-[0-9]+" -E

# Which commit introduced a term
gitscan grep -e "Acme Corp" --history

# Machine-readable output for agents
gitscan grep -e ACME --json

Order Subcommand

Show repos in topological dependency order - dependencies first, then dependents. Helps determine the correct order to update and release Go modules.

gitscan order [directory]

directory is a positional argument that defaults to the current directory.

Order Examples

# Show all repos in dependency order
gitscan order ~/go/src/github.com/grokify

# Repos modified in last 7 days, in dependency order
gitscan order -s 7d ~/go/src/github.com/grokify

# Include transitive dependents (repos depending on modified repos)
gitscan order -s 7d -t ~/go/src/github.com/grokify

# Only show repos that need to be pushed
gitscan order -s 7d -t -u ~/go/src/github.com/grokify

Order Output

Update order (dependencies first):
----------------------------------
  1. mogo                  2026-02-08 12:28
  2. gogithub              2026-02-07 08:09 (depends on: mogo)
  3. goauth                2026-02-09 19:38 (depends on: mogo)
  4. gogoogle              2026-02-09 17:31 (depends on: goauth, mogo)
  5. go-aha                2026-02-09 02:15 (depends on: goauth, gogoogle, mogo)

Total: 5 repos in dependency order

Checks Performed

For each direct subdirectory, gitscan checks:

1. Uncommitted Changes - Detects modified, added, or deleted files using git status --porcelain

2. Replace Directives - Parses go.mod for replace directives (both single-line and block format), which may indicate local development dependencies that shouldn't be committed

3. Module Name Mismatch - Compares the module name in go.mod with the directory name to identify renamed or copied repos

4. Unpushed Commits - Detects commits that haven't been pushed to remote (with -u flag)

Output Format

During scanning, a progress bar shows real-time status:

Scanning: /Users/you/go/src/github.com/grokify
Found 584 directories to scan

[████████████████░░░░░░░░░░░░░░░░░░░░░░░░]  42% (245/584) my-current-repo

List Format (default)

Repos are shown in a numbered list with issues and internal dependencies:

  1. mogo                  2026-02-08 12:28
  2. gogithub              2026-02-07 08:09 (depends on: mogo)
  3. my-service            2026-02-10 15:30 [uncommitted, replace:2]

Summary: 100 repos scanned, 25 modified within 7d

Table Format (-f table)

Compact markdown table with one repo per row:

| # | Repository | Uncommitted | Replace | Mismatch | Git | go.mod |
|---|------------|-------------|---------|----------|-----|--------|
| 1 | omnistorage |  |  | X | Y | Y |
| 2 | omnistorage-github | X |  |  | Y | - |
| 3 | structured-changelog | X |  |  | Y | Y |
| 5 | structured-roadmap |  | 5 |  | - | Y |

Column legend:

• Uncommitted: X = has uncommitted changes
• Replace: number of replace directives in go.mod
• Mismatch: X = module name doesn't match directory
• Git: Y = is a git repo, - = not a git repo
• go.mod: Y = has go.mod, - = no go.mod

Finding Dependents

When making breaking changes to a library, find all local repos that depend on it:

# Find repos depending on a module
gitscan dep github.com/grokify/gogithub ~/go/src/github.com/grokify

# Include nested go.mod files (monorepos, nested modules)
gitscan dep github.com/grokify/gogithub -r ~/go/src/github.com/grokify

# Find recently modified repos that depend on a module
gitscan since 7d --dep github.com/grokify/mogo ~/go/src/github.com/grokify

Performance

gitscan uses parallel scanning with a goroutine worker pool (defaults to GOMAXPROCS workers) for fast scanning of large directory trees. Expensive operations like modification time calculation and unpushed commit detection are performed lazily only when needed.

Why the Git CLI, Not go-git

gitscan shells out to the git binary for repository status checks rather than using the pure-Go go-git library:

go-git's main selling point — no dependency on a git binary — doesn't apply here: gitscan's entire job is scanning directories that are already git repositories, so a working git install is a given. Given that, the CLI backend's speed and exact compatibility with real git semantics (ahead/behind counts, detached HEAD, porcelain edge cases) outweigh go-git's portability benefit, so gitscan doesn't carry a second backend to build and keep bug-for-bug identical to the first.

Cold vs. Warm Cache

For a fleet-wide sweep (e.g. gitscan pending across several org directories), the dominant cost is the OS reading each repository's .git metadata, not gitscan's own work. Measured across ~640 repositories:

• First run of the session (cold filesystem cache): ~22s — mostly disk I/O paging in git metadata.
• Subsequent runs (warm cache): ~5.5s — already close to the floor of one git process spawn per repository.

Extra worker parallelism does not help here: the run is bounded by per-repository git startup, not CPU. Reducing the number of git invocations per repository would trim warm runs modestly but has little effect on the cold-cache first run, since that data must be read from disk regardless.

Future: Skip Unchanged Repositories

The highest-leverage speedup for repeated fleet sweeps is to avoid visiting repos that cannot have changed. A --modified-since <duration> prefilter (reusing the duration parsing already used by gitscan since) would stat each repository's .git and skip any untouched within the window before spawning git at all. On a typical day only a handful of a large fleet's repos have recent activity, so this could cut the working set — and the wall time — by 10–50x. This is a planned enhancement, not yet implemented.

Use Cases

• Pre-push audit: Identify repos with uncommitted work before leaving for vacation
• Dependency cleanup: Find repos with local replace directives that need resolution
• Repo hygiene: Detect copied/renamed repos with mismatched module names
• Breaking changes: Find all repos to update before releasing library changes
• Security patches: Locate repos using vulnerable dependencies
• Release ordering: Determine correct order to update and release interdependent modules
• Prioritization: Focus on repos that need immediate attention

License

MIT