Metadata-Version: 2.4
Name: repo-time-machine
Version: 0.1.0
Summary: Watch any Git repository evolve, commit by commit. Interactive HTML timeline generator.
Author: repo-time-machine contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/user/repo-time-machine
Project-URL: Repository, https://github.com/user/repo-time-machine
Project-URL: Issues, https://github.com/user/repo-time-machine/issues
Keywords: git,visualization,timeline,repository,history
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <h1 align="center"><strong>Repo Time Machine</strong></h1>
  <p align="center"><em>Watch any Git repository being built, commit by commit.</em></p>
</p>

<p align="center">
  <a href="https://pypi.org/project/repo-time-machine/"><img src="https://img.shields.io/pypi/v/repo-time-machine" alt="PyPI"></a>
  <a href="https://pypi.org/project/repo-time-machine/"><img src="https://img.shields.io/pypi/pyversions/repo-time-machine" alt="Python Version"></a>
  <a href="https://github.com/user/repo-time-machine/blob/main/LICENSE"><img src="https://img.shields.io/github/license/user/repo-time-machine" alt="License"></a>
</p>

---

Ever wondered what a repository looked like five years ago?

**Repo Time Machine** turns Git history into an interactive timeline. Drag through time — or hit play — and watch files, contributors, languages, and project structure evolve.

![Repo Time Machine Demo](assets/demo.gif)

## What it does

Point it at any Git repository — local or public GitHub — and it generates a **self-contained HTML file** with:

- Interactive timeline slider
- Playback controls (0.5x to 5x speed)
- File tree at each point in history
- Language breakdown over time
- Repository growth chart
- Auto-detected milestones (first commit, tests, CI, Docker, etc.)
- Interesting statistics

No server needed. Just open the HTML file in a browser.

## Installation

```bash
pip install repo-time-machine
```

Requires **Python 3.10+** and **Git**.

## Usage

### Analyze a local repository

```bash
repo-time-machine .
repo-time-machine /path/to/repo
```

### Analyze a public GitHub repository

```bash
repo-time-machine https://github.com/pallets/flask
```

### Open in browser automatically

```bash
repo-time-machine https://github.com/user/repo --open
```

### Options

```bash
repo-time-machine . --output timeline.html    # Custom output file
repo-time-machine . --max-commits 500         # Limit commits analyzed
repo-time-machine . --sample 200              # Control snapshot count
repo-time-machine . --verbose                 # Show progress
repo-time-machine --version                   # Show version
```

## Features

### Interactive Timeline
Drag the slider to travel through the repository's history. The file tree, commit details, language breakdown, and statistics all update in real-time.

### Playback Mode
Hit **Play** and watch the repository build itself. Control speed from 0.5x to 5x.

### File Tree
See the complete directory structure at any point in time. Directories are collapsible.

### Language Detection
Automatic language breakdown based on file extensions. Supports 40+ languages.

### Growth Chart
SVG chart showing file count growth over the repository's lifetime.

### Milestone Detection
Automatically identifies interesting moments:
- 🚀 First commit
- 👥 First outside contributor
- 🧪 Tests introduced
- ⚙️ CI introduced
- 🐳 Docker added
- 🔥 Biggest commit
- 🗑️ Biggest deletion
- 📦 Dependency file added
- 📦 Commit #100, #1000, etc.

### Statistics
- Repository age
- Total commits and contributors
- Most active contributor
- Busiest day
- Most changed file
- Biggest commit and deletion

## Performance

Repo Time Machine handles large repositories efficiently:

| Commits | Behavior |
|---------|----------|
| ≤ 1,000 | Analyze every commit |
| 1,001–10,000 | Sample ~1,000 commits |
| > 10,000 | Sample ~1,500 commits |

Milestone commits are always preserved regardless of sampling.

Example output:
```
Cloning repository...
Found 8,421 commits
Analyzing commit stats...
Detecting milestones...
Sampling 1,000 commits for visualization
Generating timeline...
Created repo-time-machine.html
```

## Privacy & Security

- **100% local** — no data leaves your machine
- **No accounts** — no authentication required
- **No telemetry** — no analytics or tracking
- **Safe cloning** — repository code is never executed
- Only Git metadata and file listings are inspected

## Examples

```bash
# Analyze Flask
repo-time-machine https://github.com/pallets/flask --open

# Analyze React
repo-time-machine https://github.com/facebook/react --sample 500

# Analyze your own project
cd my-project
repo-time-machine . --open
```

## Contributing

Contributions welcome!

```bash
git clone https://github.com/user/repo-time-machine.git
cd repo-time-machine
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
```

Run tests:
```bash
pytest
```

## Roadmap

- [ ] Cumulative additions/deletions chart
- [ ] Contributor activity timeline
- [ ] File heatmap (most-changed files)
- [ ] Branch comparison
- [ ] Export to video/GIF
- [ ] Custom milestone patterns

## License

MIT — see [LICENSE](LICENSE).
""  
