Metadata-Version: 2.4
Name: repoview
Version: 1.3.0
Summary: Turn any codebase into LLM-ready context — in seconds.
Author-email: Your Name <you@example.com>
License: MIT
Project-URL: Homepage, https://github.com/yourname/repoview
Keywords: llm,context,code,ai,cli,developer-tools,chatgpt,claude
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: pathspec>=0.12.1
Requires-Dist: questionary>=2.0.1
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Requires-Dist: pyperclip>=1.8.2
Requires-Dist: watchdog>=4.0.0
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pytest; extra == "dev"

# repoview

> Turn any codebase into LLM-ready context — in seconds.

`repoview` scans your project, intelligently processes every file, and generates a single `.txt` file you can paste directly into Claude, ChatGPT, Gemini, or any LLM. It respects your `.gitignore`, summarises large files to fit within token limits, and remembers your settings between runs so updates are near-instant.

---

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [How It Works](#how-it-works)
- [Interactive Wizard](#interactive-wizard)
- [CLI Reference](#cli-reference)
- [Watch Mode](#watch-mode)
- [Smart Diff / Incremental Updates](#smart-diff--incremental-updates)
- [File Classification](#file-classification)
- [Token Budget & Trimming](#token-budget--trimming)
- [Cache System](#cache-system)
- [Output File Format](#output-file-format)
- [Publishing a New Version](#publishing-a-new-version)
- [Requirements](#requirements)

---

## Installation

```bash
pip install repoview
```

That's it. The `repoview` command is now available anywhere in your terminal.

---

## Quick Start

```bash
# Navigate to your project and run
cd my-project
repoview

# Or pass the path directly
repoview "C:\Users\Prateek\Desktop\my-project"
repoview ~/projects/my-project
```

The interactive wizard will guide you through everything. When it's done, a `.txt` file is ready to paste into any LLM.

---

## How It Works

```
repoview <path>
      │
      ▼
  Scan project          ← counts files, detects test files, finds .gitignore
      │
      ▼
  Check cache           ← was this project run before?
      │                    yes → show diff, offer incremental update
      │                    no  → continue to wizard
      ▼
  Ask questions         ← only the ones relevant to your project
      │                    skip docs? skip tests? respect .gitignore?
      │                    output name? output location?
      ▼
  Classify files        ← essential / code / config / general / metadata
      │
      ▼
  Token budget check    ← if over budget: summarise → omit (lowest priority first)
      │
      ▼
  Write output file     ← structured .txt with directory tree + all file contents
      │
      ▼
  Save cache            ← stored in ~/.repoview/cache/ for next run
      │
      ▼
  Post-completion menu  ← copy text / copy file / open folder / run again / exit
```

---

## Interactive Wizard

Running `repoview` or `repoview <path>` launches the interactive wizard. Every question is conditional — you only see questions that are relevant to your specific project.

### Source Selection

The wizard's first prompt accepts any of:

```
◆  Project path, ZIP file, or GitHub URL:
   › ./my-project              ← local folder
   › ./archive.zip             ← zip file
   › facebook/react            ← GitHub shorthand
   › https://github.com/...    ← full GitHub URL
```

**Local folder** — standard behaviour, walks the directory tree.

**ZIP file** — extracts to a temp folder and processes identically to a folder. Useful for downloaded archives or backups.

**GitHub URL** — fetches branch list, lets you choose interactively, downloads the repo zip, extracts, and processes it. Temp folder cleaned up automatically.

---

### Scan Preview

Before any questions, repoview scans your project and shows:

```
  Scanning my-project…

  ╭─────────────────────────────────────────╮
  │  Files found      147                   │
  │  Total size       3.1 MB                │
  │  Est. tokens      ~218,000              │
  │  Top types        .ts 43  .tsx 28  ...  │
  │  .gitignore       found (24 rules)      │
  │  Test files       31 detected           │
  ╰─────────────────────────────────────────╯
```

This gives you the information you need to make good decisions in the questions that follow.

### Diff Check (if previous run exists)

If you have run repoview on this project before, it checks for changes before asking any questions:

```
  Changes since last run  (2h ago)

    ✎  src/auth.ts              (modified)
    +  src/middleware/rate-limit.ts  (new)
    -  src/old-utils.ts         (deleted)

  ❯  ⚡ Update changed files only    (fast)
     🔄 Regenerate full context      (slower, same settings)
     ⚙️  Regenerate with new settings
```

Choosing **Update changed files only** skips all questions and updates only the affected parts of the output file in a fraction of the time.

### Q1 — Skip Documentation Files?

Always shown. Asks whether to exclude `.md`, `.txt`, `.rst`, and `.mdx` files.

- **Default: Yes (skip)**
- Recommended when giving context for code understanding, bug fixes, or feature work
- Choose No if you want the LLM to understand your README, changelogs, or written docs

### Q2 — Skip Test Files? *(only shown if test files are detected)*

Shown only when the scan finds files matching test patterns:
`test_*.py` · `*.test.js` · `*.test.ts` · `*.spec.ts` · `*.spec.js` · `*_test.go` · `conftest.py` · files inside `/tests/`, `/__tests__/`, `/spec/` directories.

- **Default: Yes (skip)**
- Recommended for feature/bug context where test files add noise
- Choose No if you want the LLM to understand your test coverage or debug failing tests

### Q3 — Respect `.gitignore`? *(only shown if `.gitignore` exists)*

Shown only when a `.gitignore` file is found in the project root.

- **Default: Yes (respect)**
- Respecting it excludes `node_modules`, `.env`, `dist`, `build`, etc.
- Choose No only if you specifically need something that is gitignored (e.g. a local config file)

Note: Even when ignoring `.gitignore`, repoview always excludes `node_modules`, `.git`, `__pycache__`, `venv`, and other standard directories that would be useless noise.

### Q4 — Output File Name

```
Output file name:  my-project-context.txt  [Enter to confirm]
```

- **Default: `<foldername>-context.txt`**
- You can type any name. `.txt` is added automatically if you omit it.

### Q5 — Output Location

```
  ❯  Inside the project folder   /path/to/my-project/my-project-context.txt
     Next to the project folder  /path/to/my-project-context.txt
     Custom path…
```

- **Default: Inside the project folder**

### Confirmation Summary

Before generating, a summary is shown:

```
  ╭─ Ready to generate ──────────────────────╮
  │  Source    my-project/                   │
  │  Output    my-project-context.txt        │
  │  Skipping  ✔ Docs   ✔ Tests             │
  │  Gitignore ✔ respected                   │
  ╰──────────────────────────────────────────╯

  Generate context file?  [Y/n]
```

### Result

```
  ✔ Done in 3.8s

  ╭──────────────────────────────────────────────────╮
  │  Output     my-project-context.txt               │
  │  Tokens     ████████████░░░░  142k / 800k  (18%) │
  │  Full        98 files                            │
  │  Summarised  12 files                            │
  │  Skipped     37 files                            │
  │  Omitted      0 files                            │
  ╰──────────────────────────────────────────────────╯
```

### Post-Completion Menu

```
  ❯  📋  Copy text to clipboard    (paste directly into Claude / ChatGPT)
     📄  Copy file to clipboard    (paste the file itself)
     📁  Open output folder        (opens in Explorer / Finder)
     🔁  Run again                 (same project, change settings)
     ❌  Exit
```

**Copy text** — reads the entire output file and puts it in your clipboard as plain text. Paste directly into any LLM chat window.

**Copy file** — copies the `.txt` file itself to clipboard (not the text inside it).
- Windows: uses PowerShell `Set-Clipboard -Path`
- Mac: uses `osascript`
- Linux: falls back to copying text (file clipboard not widely supported on Linux)

**Open output folder** — opens the containing folder in your file manager.

**Run again** — restarts the wizard for the same project. Useful for trying different skip settings.

---

## CLI Reference

### `repoview [PATH]`

Launches the interactive wizard. If `PATH` is omitted, uses the current directory.

```bash
repoview
repoview ./my-project
repoview "C:\Users\Prateek\Desktop\my-project"
```

---

### `--quick` / `-q`

Skips all questions. Uses sensible defaults and runs immediately.

```bash
repoview --quick
repoview --quick ./my-project
repoview -q ./my-project
```

Defaults used in quick mode:

| Setting | Default |
|---------|---------|
| Skip docs | Yes |
| Skip tests | Yes (if any are found) |
| Respect `.gitignore` | Yes (if `.gitignore` exists) |
| Output filename | `<foldername>-context.txt` |
| Output location | Inside the project folder |

After generating, the post-completion menu is shown as normal.

---

### `--watch` / `-w`

Starts watch mode. Monitors your project for file changes and automatically updates the context file after every save.

```bash
repoview --watch
repoview --watch ./my-project
repoview -w ./my-project
```

Full details in the [Watch Mode](#watch-mode) section below.

---

### `--focus <path>` / `-f`

Focus mode — generate context for a **specific folder or file** only. Everything else appears in the directory tree but has no file content. Essential files (`README.md`, `package.json`, etc.) are always included regardless.

```bash
# Focus on a subfolder
repoview --focus src/auth ./my-project
repoview --focus src/api/users

# Focus on a specific file
repoview --focus src/auth/index.ts ./my-project

# Focus + watch (the killer combo)
repoview --watch --focus src/auth ./my-project
```

**Why this is useful:**

Normal run on a large project = 147 files, 142,000 tokens. You're only fixing a bug in `src/auth/` — the AI has to find the relevant parts itself.

Focus run = 8 files full content, 18,000 tokens, full project tree still visible. The AI sees exactly what you're working on, plus understands how it fits into the broader project.

**What focus mode asks:**

The wizard is shorter — no skip docs/tests questions (irrelevant when focused):

1. Respect `.gitignore`? *(only if `.gitignore` exists)*
2. Output filename? *(default: `<project>-<focus-slug>-context.txt`)*
3. Output location?

**Output file behaviour:**

- Files **inside** the focus path → full content (always, never trimmed)
- Essential files (`README.md`, `package.json`, etc.) → full content (always)
- Everything **outside** the focus path → tree entry only, no content block

**`--watch --focus` combined:**

```bash
repoview --watch --focus src/auth ./my-project
```

Watch mode uses the same focus settings. Every save inside `src/auth/` updates the context instantly. Changes outside the focus path are detected but produce no output changes (structure-only files have no content to update).

---

### `--reset` / `-r`

Deletes the saved cache for a project and runs the wizard fresh. Use this when your settings are wrong and you want to start over — different skip choices, different output location, etc.

```bash
repoview --reset
repoview --reset ./my-project
repoview -r ./my-project
```

What it does:
1. Deletes `~/.repoview/cache/<project-hash>.json`
2. Launches the full interactive wizard
3. Saves the new cache on completion

Common workflow when settings need changing:

```bash
repoview --reset ./my-project    # clear cache + wizard
repoview --watch ./my-project    # now watch with new settings
```

---

### GitHub URL support

Pass any GitHub URL or shorthand directly as the path argument. repoview will fetch the available branches, let you pick one interactively, download the repo as a zip, and process it exactly like a local folder.

```bash
rv https://github.com/facebook/react
rv github.com/facebook/react
rv facebook/react
rv https://github.com/facebook/react/tree/canary
```

**Branch selection:**

```
  GitHub repository:  facebook/react

  Fetching branches…

◆  Select branch for facebook/react:
   ❯  main        (default)
      canary
      experimental
      0.14-stable
      ✏️  Enter branch manually…
```

If the URL already includes a branch (`/tree/canary`), it is pre-selected in the list. If the GitHub API is unreachable, falls back to a text input with `main` as default.

**Works with all flags:**

```bash
rv --quick facebook/react                  # instant, no questions
rv --quick --copy facebook/react           # download + generate + copy
rv --focus src/compiler facebook/react     # focused context
rv --info facebook/react                   # stats without generating
```

The downloaded repo is extracted to a temp folder, processed, then the temp folder is deleted automatically.

---

### `rv` alias

`rv` is a shorter alias for `repoview` — both are installed and identical.

```bash
rv ./my-project     # same as: repoview ./my-project
rv facebook/react   # same as: repoview facebook/react
```

---

### `--copy` / `-c`

After generating the context file, automatically copy its full text to clipboard. Combine with `--quick` for a completely silent, zero-interaction workflow.

```bash
# Generate with all defaults + copy to clipboard, no questions at all
repoview --quick --copy ./my-project

# Interactive wizard + auto-copy when done
repoview --copy ./my-project
```

If `pyperclip` is not installed, a warning is shown and the rest of the run completes normally.

---

### `--info` / `-i`

Show a full breakdown of a project without generating anything. Useful for checking what repoview would do before committing to a run.

```bash
repoview --info
repoview --info ./my-project
repoview -i ./my-project
```

Output includes:

- **Overview** — file count, total size, estimated tokens, whether it fits the budget
- **File types** — top 12 extensions with count and category (code / config / docs / other)
- **Skip / filter info** — how many doc files, test files, and what .gitignore contains
- **Cache status** — when the project was last run, where the output file is, what settings were used

Example:

```
╭─ Overview ────────────────────────────────────────╮
│  Project       /path/to/my-project                │
│  Files         147                                │
│  Total size    3.1 MB                             │
│  Est. tokens   ~218,000  (before filtering)       │
│  Token budget  800,000  — fits comfortably        │
╰───────────────────────────────────────────────────╯

╭─ File Types ──────────────────────────────────────╮
│  .ts      43    code                              │
│  .tsx     28    code                              │
│  .json    19    config                            │
│  .md      12    docs                              │
│  .css      8    code                              │
╰───────────────────────────────────────────────────╯

╭─ Skip / Filter Info ──────────────────────────────╮
│  Docs (.md .txt …)   12 files — skipped by default│
│  Test files          31 files — skipped by default│
│  .gitignore          found  24 rules              │
╰───────────────────────────────────────────────────╯

╭─ Cache Status ────────────────────────────────────╮
│  Last run      2h ago  (2025-03-16T14:32:11)      │
│  Output file   my-project-context.txt  exists     │
│  Settings      docs skipped • gitignore respected │
│  Cached files  147                                │
╰───────────────────────────────────────────────────╯
```

Nothing is written to disk. No questions asked.

---

### `--version` / `-v`

Prints the installed version and exits.

```bash
repoview --version
# repoview v1.0.0
```

---

### `--help`

Prints usage information and exits.

```bash
repoview --help
```

---

## Watch Mode

Watch mode keeps your context file permanently up to date as you work. Every time you hit save in your editor, the context file is updated automatically — usually in under a second.

```bash
repoview --watch ./my-project
```

### First Run Behaviour

If no previous context exists for the project, the **interactive wizard runs first** so you can choose exactly what to include, where to save, and what to skip. Watch mode starts automatically after generation completes.

```
  First time setup
  No previous context found for this project.
  The wizard will run once so you can choose your settings.
  Watch mode will start automatically after generation.

  [wizard questions run here — same as normal repoview]

  ✔ Generation complete — starting watch mode

  ╭─────────────────────────────────────────────────────╮
  │  👁  Watching  my-project/                          │
  │  Output    →  my-project-context.txt                │
  │  Settings  →  docs skipped  •  gitignore respected  │
  │  Press Ctrl+C to stop                               │
  ╰─────────────────────────────────────────────────────╯
```

If a previous context **already exists** (cache found), the wizard is skipped entirely and watch starts immediately using the saved settings.

### During Watch

Every time you save a file, repoview detects the change and updates the context file automatically:

```
  14:32:11  src/auth.ts changed
  14:32:11  ✔ Updated in 0.3s  143,201 tokens  (+0 ✎1 -0)

  14:35:44  src/api/users.ts + 2 more changed
  14:35:46  ✔ Updated in 0.6s  144,890 tokens  (+2 ✎1 -0)
```

The `(+0 ✎1 -0)` notation means: 0 files added, 1 file updated, 0 files deleted.

### Debounce

When multiple files change in quick succession (e.g. a `git checkout`, running `npm install`, or your editor saving multiple buffers at once), repoview waits **2 seconds** after the last change before running the update. This prevents it from running dozens of times unnecessarily.

### What Gets Ignored in Watch Mode

- The output `.txt` file itself — prevents an infinite loop
- `~/.repoview/cache/` files
- `node_modules/`, `.git/`, `__pycache__/`, `venv/`, and all other standard excluded directories
- Binary files (images, fonts, compiled files, etc.)

### Stopping Watch Mode

Press `Ctrl+C` at any time. A summary panel is shown with the exact commands to resume or change settings:

```
  ╭──────────────────────────────────────────────────────────╮
  │  Watch stopped.                                          │
  │                                                          │
  │  Settings used:  docs skipped  •  gitignore respected    │
  │  Output:         /path/to/my-project-context.txt         │
  │                                                          │
  │  To resume watching with the same settings:              │
  │    repoview --watch ./my-project                         │
  │                                                          │
  │  To change settings, reset the cache first:              │
  │    repoview --reset ./my-project                         │
  │    repoview --watch ./my-project                         │
  ╰──────────────────────────────────────────────────────────╯
```

### Requirements for Watch Mode

`watchdog` is installed automatically with repoview. If for some reason it's missing:

```bash
pip install watchdog
```

---

## Smart Diff / Incremental Updates

Every time repoview successfully generates a context file, it saves a cache entry at `~/.repoview/cache/`. The next time you run `repoview` on the same project, it checks this cache and shows you exactly what changed — then lets you choose how to update.

### How the Diff Works

repoview uses a two-step check to determine what changed since the last run:

1. **Fast path — modification time (`mtime`)**: If a file's `mtime` is unchanged, it hasn't changed. This check takes microseconds and covers the vast majority of files.

2. **Hash verification — SHA1**: If `mtime` changed, repoview computes a SHA1 hash of the file's content. If the hash matches the cached hash, the file was touched (e.g. by a tool) but the content is actually the same — it's treated as unchanged.

3. **True change**: If both `mtime` and hash differ, the file is marked as modified and will be reprocessed.

This design means even on a 1,000-file project, the diff check completes in well under a second.

### What Incremental Update Does

Instead of rewriting the entire output file, the incremental updater surgically patches only the changed sections:

- **Modified files** → reprocesses the file and replaces its block in the output file
- **New files** → processes the file and inserts its block at the correct position (sorted by priority)
- **Deleted files** → removes their block from the output file entirely
- **Unchanged files** → not touched, not re-read from disk

After patching, two things are updated:
- The **directory tree** at the top of the output file is rebuilt to reflect the current folder structure
- The **token count** in the footer is recalculated and updated

### Automatic Update

No prompt, no choices. repoview just does the right thing:

| Situation | What happens |
|-----------|-------------|
| Cache exists, output file exists, files changed | Incremental update — only changed files reprocessed |
| Cache exists, output file exists, nothing changed | Skips straight to post-completion menu |
| Cache missing or output file deleted | Full generation runs automatically |
| Incremental update fails (e.g. output was manually edited) | Falls back to full generation automatically |

Incremental update typically completes in **0.1s–1s** regardless of project size, because unchanged files are never touched.

---

## File Classification

repoview assigns every file a priority level which controls both the order files appear in the output and how aggressively they are trimmed when the token budget is tight.

| Priority | Level | What's included |
|----------|-------|-----------------|
| 0 | **Focus** | Files inside `--focus` path — always full content, never summarised or omitted |
| 1 | **Essential** | `README.md` · `package.json` · `requirements.txt` · `Dockerfile` · `pyproject.toml` · `manage.py` · `main.py` · `app.py` · `go.mod` · `tsconfig.json` · `docker-compose.yml` · `vite.config.ts` · `.env.example` · `cargo.toml` · and other project-definition files |
| 2 | **Important Code** | `.py` `.js` `.ts` `.tsx` `.jsx` `.go` `.rs` `.java` `.cs` `.cpp` `.c` `.h` `.rb` `.php` `.swift` `.kt` `.vue` `.svelte` `.sql` `.graphql` `.proto` `.sol` `.scss` `.css` `.html` |
| 3 | **Config & Support** | `.json` `.yml` `.yaml` `.toml` `.ini` `.env` `.sh` `.bat` `.ps1` `.tf` `.tfvars` `.xml` `.conf` `.cfg` |
| 4 | **General Code** | Less common languages: `.lua` `.dart` `.scala` `.hs` `.ex` `.erl` `.clj` `.r` `.tex` `.fs` `.gd` and others |
| 5 | **General Text** | Files with unrecognised extensions that appear to be text |
| 10 | **Metadata only** | Binary files, images, fonts, compiled files, lock files, `.log` `.cache` `.tmp` — never read, only noted as `[metadata-only or empty file]` |

Files you choose to skip (docs, tests) are treated as **Metadata only** regardless of extension.

### Always-Excluded Directories

These directories are never walked, regardless of `.gitignore` settings:

`.git` · `node_modules` · `vendor` · `venv` · `env` · `__pycache__` · `target` · `build` · `dist` · `out` · `bin` · `obj` · `.vscode` · `.idea` · `.gradle` · `.pytest_cache` · `coverage` · `.mypy_cache` · `.tox` · `.next` · `.nuxt` · `.svelte-kit` · `storybook-static`

---

## Token Budget & Trimming

The default token budget is **800,000 tokens**, suitable for Claude 3.5 Sonnet and most large-context models. repoview uses `tiktoken` with the `cl100k_base` encoding — the same tokenizer used by GPT-4 and Claude — so the count is accurate.

### What Happens When the Budget is Exceeded

repoview trims in two passes, always preserving higher-priority files first.

**Pass 1 — Full content → Summary**

Lower-priority files are replaced with a summary instead of their full content. The summary type depends on the file:

- **Python files**: imports, class names, function signatures extracted via AST (Python's abstract syntax tree). Accurate and fast.
- **Other code files**: function and class signatures extracted via regex patterns. Works across JS, TS, Go, Java, C++, and most other languages.
- **Text and config files**: first 3,000 characters as a preview, with a note of the full token count.

Focus files (priority 0) and essential files (priority 1) are **never** summarised.

**Pass 2 — Summary → Omitted**

If still over budget after summarising everything possible, the lowest-priority files are removed entirely:

```
[Omitted to fit token budget: path/to/large-file.ts]
```

Focus files and essential files are **never** omitted.

The result display shows exactly what happened:

```
  Full        98 files    ← complete content included
  Summarised  12 files    ← signatures/preview only
  Skipped     37 files    ← metadata note (binary, gitignored, or your skip choice)
  Omitted      0 files    ← removed entirely to fit budget
```

---

## Cache System

### Location

```
~/.repoview/
└── cache/
    ├── a3f9c2b1d4e8f012.json    ← project A
    ├── bc1234567890abcd.json    ← project B
    └── ...
```

Each project gets its own cache file named by a 16-character SHA1 hash of the project's absolute path. **Your project folder is never modified.** No hidden files, no `.repoview` directory in your repo.

### Cache File Contents

```json
{
  "version": 1,
  "project_path": "/abs/path/to/project",
  "generated_at": "2025-03-16T14:32:11",
  "output_path": "/abs/path/to/project/project-context.txt",
  "settings": {
    "skip_docs": true,
    "skip_tests": true,
    "respect_gitignore": true
  },
  "files": {
    "src/auth.ts": {
      "mtime": 1710598331.4,
      "hash": "a3f9c2b1...",
      "decision": "full",
      "tokens": 847
    },
    "src/big-file.ts": {
      "mtime": 1710598290.1,
      "hash": "bc123456...",
      "decision": "summary",
      "tokens": 312
    }
  }
}
```

### Cache Reliability

- Written **atomically** via a temp file + rename — a crash or power cut during write never corrupts the cache
- If the cache is missing, corrupt, or from an older schema version, repoview treats it as if no cache exists and runs a full generation
- If the output `.txt` file has been deleted but the cache exists, repoview detects this and runs a full generation automatically

---

## Output File Format

The generated `.txt` file has a consistent, human-readable structure:

```
repoview context — my-project
Generated by: repoview

Directory structure:
└── my-project/
    ├── src/
    │   ├── auth.ts
    │   └── api/
    │       └── users.ts
    ├── package.json
    └── README.md

────────────────────────────────────────────────────────────

── FILE: package.json [1823B | prio:1 | full] ──
{
  "name": "my-project",
  ...full content...
}
── END: package.json ──

── FILE: src/auth.ts [4201B | prio:2 | full] ──
...full content...
── END: src/auth.ts ──

── FILE: src/large-file.ts [98420B | prio:2 | summary] ──
[Code summary: large-file.ts]
  imports: express, zod, prisma
  class AuthController(BaseController)
  class TokenService
  def generateToken(payload) -> string
  def verifyToken(token) -> Payload | null
  ... [8,431 tokens full]
── END: src/large-file.ts ──

────────────────────────────────────────────────────────────
repoview | tokens used: 142,847 / 800,000
full: 98  summary: 12  metadata: 37  omitted: 0
```

Each file block header includes the file size in bytes, its priority level, and the decision made (full / summary / metadata / omitted). This metadata helps the LLM understand which files are complete and which were trimmed.

---

## Publishing a New Version

```bash
# 1. Bump the version in TWO places:

# repoview/__init__.py
__version__ = "1.1.0"

# pyproject.toml
version = "1.1.0"

# 2. Remove old build artifacts
rm -rf dist/ build/ *.egg-info

# 3. Build the package
python -m build

# 4. Upload to PyPI
twine upload dist/*
```

### Versioning convention

| Change type | Example |
|-------------|---------|
| Bug fix | `1.0.0 → 1.0.1` |
| New feature, backward compatible | `1.0.0 → 1.1.0` |
| Breaking change | `1.0.0 → 2.0.0` |

### Automate version bumping

```bash
pip install bump2version
bump2version patch   # 1.0.0 → 1.0.1  (updates both files automatically)
bump2version minor   # 1.0.0 → 1.1.0
bump2version major   # 1.0.0 → 2.0.0
```

### Save PyPI credentials

Create `~/.pypirc` so you don't type your password every release:

```ini
[pypi]
username = __token__
password = pypi-AgENdGVzdC5weXBpLm9yZwI...
```

Get your API token at: https://pypi.org/manage/account/token/

---

## Requirements

| Package | Version | Purpose |
|---------|---------|---------|
| `tiktoken` | ≥ 0.7.0 | Accurate token counting using the same tokenizer as GPT-4 / Claude |
| `pathspec` | ≥ 0.12.1 | `.gitignore` pattern matching |
| `questionary` | ≥ 2.0.1 | Interactive terminal prompts |
| `rich` | ≥ 13.0.0 | Coloured output, progress bars, panels, tables |
| `typer` | ≥ 0.12.0 | CLI argument parsing |
| `pyperclip` | ≥ 1.8.2 | Cross-platform clipboard support |
| `watchdog` | ≥ 4.0.0 | File system events for `--watch` mode (Windows, Mac, Linux) |

**Python 3.9 or higher required.**

All dependencies are installed automatically when you run `pip install repoview`.

---

## License

MIT
