gre 0.1.14

A super-fast multi-repo git recap for AI agents and speed-obsessed humans.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

![gre](https://raw.githubusercontent.com/tappunk/.github/refs/heads/main/assets/gre.webp)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Crates.io Version](https://img.shields.io/crates/v/gre?color=orange&cacheSeconds=3600)](https://crates.io/crates/gre)
[![GitHub Release](https://img.shields.io/github/v/release/tappunk/gre?color=blue)](https://github.com/tappunk/gre/releases)
[![X Follow](https://img.shields.io/twitter/follow/tappunk?style=social)](https://x.com/tappunk)

# gre

**Parallel git status aggregator for multiple repositories.** Human and JSON output for agent automation.

[Installation](#installation) • [Quick Start](#quick-start) • [Usage](#usage) • [Config](#config) • [Output Formats](#output-formats)

## Features

- **Parallel inspection** — rayon-powered concurrent repo scanning across all configured repositories
- **Action-aware sorting** — repos sorted by priority: conflicts → dirty → behind → ahead → clean
- **Focus line** — shows actionable repos and how many more need attention
- **Machine readable** — stable JSON output with timing stats (elapsed, avg, p95) for automation pipelines
- **Non-interactive** — no prompts, no TUI. Just output. Built for speed and scripts.
- **Configurable** — TOML config with simple path lists or named repo entries
- **Shell agnostic** — works in any terminal, pipe JSON to agents or other tools

## Installation

### Homebrew

```bash
brew install tappunk/gre/gre
```

### Cargo

```bash
cargo install gre
```

## Quick Start

```bash
gre init                     # Create config file
gre                          # Show status across all configured repos
```

## Usage

```bash
gre                          # Show human-readable status
gre --json                   # Output JSON for agents and scripts
gre --config PATH            # Use an explicit config file
gre --help                   # Show help
gre init                     # Create default config
gre init --force             # Overwrite existing config
```

## Config

Default path: `~/.config/gre/config.toml`

### Simple — just paths

```toml
paths = [
  "~/code/gre",
  "~/code/muthr",
  "~/code/utmd",
]
```

### Named — when you want a different label than the directory

```toml
[[repos]]
name = "gre"
path = "~/code/gre"

[[repos]]
name = "muthr"
path = "~/code/muthr"
```

## Output Formats

### Human Output

gre sorts repos by action priority: conflicts → dirty → behind → ahead → clean. The summary line includes timing (elapsed, average) and a focus line showing which repos need attention.

```
repos:3  dirty:1  behind:1  ahead:1  time:12ms  avg:4.00ms  focus:gre:commit-or-stash,muthr:pull,utmd:none
repo  branch  +sync  state  next  last_commit  path
gre   main     +1 -0  dirty s:0 u:2 ?:0 c:0  commit-or-stash  8a3b2f1 tune output (2 hours ago)  ~/code/gre
```

**Next action values:**

- `resolve-conflicts` — has merge conflicts
- `commit` — has staged changes ready to commit
- `commit-or-stash` — has unstaged or untracked changes
- `pull` — behind remote
- `push` — ahead of remote
- `sync` — ahead and behind
- `none` — clean

### JSON Output

`--json` returns a stable schema for automation and agent pipelines:

```json
{
  "schema_version": "2",
  "summary": {
    "configured_total": 2,
    "succeeded_total": 2,
    "failed_total": 0,
    "dirty": 1,
    "behind": 0,
    "ahead": 1,
    "elapsed_ms": 42,
    "avg_repo_ms": 21.0,
    "p95_repo_ms": 38.2
  },
  "repos": [
    {
      "name": "gre",
      "path": "/Users/user/src/gre",
      "branch": "main",
      "ahead": 1,
      "behind": 0,
      "staged": 0,
      "unstaged": 2,
      "untracked": 0,
      "conflicts": 0,
      "clean": false,
      "last_hash": "8a3b2f1",
      "last_subject": "tune output",
      "last_relative": "2 hours ago"
    }
  ]
}
```

`configured_total` equals `succeeded_total + failed_total`. Repo fields include `path`, `clean`, `last_hash`, `last_subject`, and `last_relative`.

**Note:** gre does not fetch remotes. Run `git fetch` in your repos before running gre to refresh tracking refs.