# Quick Start

## Install

```bash
# Zero-install (recommended)
uvx gitscope summarize HEAD~1..HEAD

# Or install permanently
pip install gitscope
```

## Basic usage

```bash
# Summarize last commit
gitscope summarize HEAD~1..HEAD

# Summarize a PR range
gitscope summarize main..feature-branch

# Pipe a diff
git diff main | gitscope summarize

# Choose output tier
gitscope summarize HEAD~1..HEAD --format oneliner
gitscope summarize HEAD~1..HEAD --format short
gitscope summarize HEAD~1..HEAD --format json
```

## Example output

### `--format oneliner`

```
Replace API key auth with OAuth2 PKCE; 2 breaking changes in auth client
```

### `--format short`

```
Removes authenticate(apiKey), adds authenticateOAuth(config) with PKCE.
refreshToken now returns TokenPair instead of string. 1 new dep: oauth4webapi.
```

### `--format json`

```json
{
  "schema_version": "1.0",
  "meta": {
    "ref_range": "abc1234..def5678",
    "stats": { "files": 3, "additions": 340, "deletions": 89 },
    "warnings": [],
    "timing_ms": 187.4
  },
  "files": [
    {
      "path": "src/auth/client.ts",
      "language": "typescript",
      "change_type": "modified",
      "changes": [
        {
          "kind": "function_removed",
          "name": "authenticate",
          "signature": "authenticate(apiKey: string): Promise<Session>",
          "line": 45,
          "breaking": true
        },
        {
          "kind": "function_added",
          "name": "authenticateOAuth",
          "signature": "authenticateOAuth(config: OAuthConfig): Promise<Session>",
          "line": 47,
          "breaking": false
        }
      ]
    }
  ],
  "summary": {
    "change_types": { "feature": 1, "refactor": 2 },
    "breaking_changes": [
      {
        "kind": "function_removed",
        "name": "authenticate",
        "signature": "authenticate(apiKey: string): Promise<Session>",
        "breaking": true
      }
    ],
    "focus": [
      "authenticate() removed — callers need migration to authenticateOAuth()",
      "refreshToken() return type changed from string to TokenPair"
    ]
  },
  "tiered": {
    "oneliner": "Replace API key auth with OAuth2 PKCE; 2 breaking changes in auth client",
    "short": "Removes authenticate(apiKey), adds authenticateOAuth(config) with PKCE. refreshToken now returns TokenPair. 1 new dep: oauth4webapi.",
    "detailed": "..."
  }
}
```

## What you get

GitScope tells you **what changed structurally**: which functions were added, removed, or modified — with their signatures. It flags breaking changes and generates tiered summaries at different token budgets.

It does **not** tell you *why* something changed or whether it's good. That's the reviewer's job. GitScope gives the map; you navigate it.
