gitquest 0.2.0

Turn your git commit history into a playable ASCII dungeon roguelike.

gitquest 🗡️

Your commits. Your dungeon. Your legend. Turn any git repository's history into a procedurally generated, playable ASCII dungeon roguelike — right in your terminal.

gitquest reads your repo's real commit history and deterministically builds a dungeon from it. Each commit becomes a room. Bug-fix commits spawn bugs. Merge commits become mini-bosses. The languages you've coded fill your skill tree. Clear every room from the repo's first commit to HEAD, then flex your career on a shareable stats card.

Same repo + same seed = the same dungeon, every time. Reproducible and shareable.

---

✨ Demo

   ____ _ _    ___                  _
  / ___(_) |_ / _ \ _   _  ___  ___| |_
 | |  _| | __| | | | | | |/ _ \/ __| __|
 | |_| | | |_| |_| | |_| |  __/\__ \ |_
  \____|_|\__|\__\_\\__,_|\___||___/\__|

      Your commits. Your dungeon. Your legend.

┌───────────────────────────────── Room 2/5 ──────────────────────────────────┐
│ fix: bug in output handling                                                  │
│ 33b27d3 · +2/-0 · a tight crawlspace of tangled diffs                        │
│ 🧙 You meet Ada Lovelace, an ally from this commit.                          │
└──────────────────────────────────────────────────────────────────────────────┘
🧠 Skill XP: +1 Python, +1 JavaScript
┌────────────────────────────── A Bug appears! ───────────────────────────────┐
│                          (>_<)                                               │
│                          Off-by-One                                          │
│                          HP 11  ·  ATK 4  ·  DEF 0                           │
└──────────────────────────────────────────────────────────────────────────────┘
Attack  Defend  Item(0)  Run
Your move (a): » Hero hits Off-by-One for 6 damage.
✔ Off-by-One defeated! (+10 XP, +6 gold)

And the grand finale — the shareable flex card:

┌───────────────────────────────── flex card ─────────────────────────────────┐
│                    ⚔  GITQUEST CAREER CARD  ⚔                                │
│                    my-repo   seed 17391773614721965407                       │
│                                                                              │
│     RANK: Senior Crusader                                                    │
│     SCORE: 2310                                                              │
│     STATUS: VICTORIOUS                                                        │
│                                                                              │
│     CAREER STATS                                                             │
│       Level   11              Gold   642                                     │
│       Kills   148           Bosses   12                                      │
│     SKILL TREE                                                               │
│   Python      ██████████████████ 220                                         │
│   TypeScript  ███████████░░░░░░░ 130                                         │
│     Specialization: Python  ·  6 skill paths explored                        │
└──────────────────────────────────────────────────────────────────────────────┘

---

🚀 Install

The zero-friction way (isolated, recommended):

pipx install gitquest

Or with pip:

pip install gitquest

From source:

git clone https://github.com/jithin-jz/gitquest
cd gitquest
pip install .

---

🎮 Play

Two commands — works on any machine, even with no repo around:

pip install gitquest
gitquest

If you run gitquest inside a git repository, it builds the dungeon from your commit history. If you run it anywhere else, it automatically launches a built-in demo dungeon so you can play right away.

python -m gitquest works too. Want your own repo? cd into it first, or pass --path:

cd path/to/your/repo && gitquest
gitquest --path ../some-other-repo
gitquest --demo            # force the built-in demo dungeon

Combat controls

During a fight, type one key + Enter: a attack · d defend · i item · r run.

Flags

Flag	Description
--path <repo>	Play on another repository (default: current directory).
--seed <n>	Force a specific dungeon seed (default: derived from repo).
--demo	Play the built-in demo dungeon (no git repo required).
--fast	Skip animations and "press Enter" pauses.
--stats-only	Skip gameplay and print just the flex card.
--max-commits	Cap/sample commits for huge repos (default: 300).
--version	Print the version.

Examples:

gitquest --path ../some-other-repo
gitquest --seed 42 --fast
gitquest --stats-only        # instant career card, no fighting

---

🧠 How it works

gitquest maps real repository data onto game mechanics:

Git data	Becomes…
Commit	A room in the dungeon
Lines added/removed	Room size + monster difficulty
Merge commit	A mini-boss room
Files changed	Loot/items in the room
Commit author	An ally/NPC you meet
Languages (by file extension)	Your skill tree / XP categories
Message keywords	Enemy types (fix → Bug, feat → Feature…)
Total repo stats	Your final rank (e.g. Senior Crusader)

Determinism

The dungeon seed is derived from the SHA of the repository's first commit (unless you pass --seed). All procedural generation — monster names, stats, loot rolls, room sizes — flows from that single seed via a random.Random instance with a fixed call order. The result: identical, reproducible dungeons that you and a teammate can compare.

Architecture

gitquest/
  cli.py          # entry point + argument parsing (argparse)
  git_parser.py   # extract & normalize commit data (GitPython + git CLI fallback)
  generator.py    # commit data -> dungeon/rooms/monsters (seeded)
  engine.py       # game loop, state, turn handling
  combat.py       # combat math (pure, rng-driven, testable)
  entities.py     # Player, Monster, Room, Item, Dungeon dataclasses
  renderer.py     # all rich-based rendering
  flexcard.py     # final shareable stats card + ranking
  data/           # monster/item name lists, ranks, ascii art
tests/            # pytest: parser, generator determinism, combat

Everything runs locally and offline — no network calls, ever.

---

🛠️ Development

pip install -e ".[dev]"
pytest

Tests cover history parsing, generator determinism, and combat logic.

Edge cases handled

• Not a git repository → friendly error, no traceback.
• Empty history / no commits → friendly nudge to commit first.
• Huge repos → evenly down-sampled to --max-commits (still deterministic).
• Missing GitPython → automatic fallback to the git CLI.

---

🤝 Contributing

Issues and PRs welcome! Ideas: more monster archetypes, a textual dungeon map, achievements, or exporting the flex card as an image.

📄 License

MIT — see LICENSE.