GitKV 🗄️

A Redis-like KV store where Git commit history is the database.

📌 Overview

GitKV is a Redis-like Key-Value store that uses Git commits as the storage engine. Instead of a traditional database file, every SET, GET, DELETE, LIST, or MAP operation creates a new immutable event commit in Git.

State is reconstructed by replaying the commit history, enabling:

• 🔄 Full rollback to any point in time.
• 📡 Real-time event streaming via WebSockets.
• 📣 Pub/Sub channels.
• 🌎 Syncing DB through GitHub remote.
• 💥 No files, no DB—Git is the entire database.

Perfect for distributed, versioned, time-traveling state management or learning event-sourcing concepts.

---

🏛 Architecture

graph TD;
    CLI[CLI / REPL] --> REST[REST API];
    REST --> Backend[Express Backend];
    Backend -->|State = Replay Event Log| Log[Git Commit Log];
    Log -->|git push/pull| Remote[GitHub Remote Repo];
    WS[WebSocket Clients] -->|Monitor/Subscribe| Backend;
    Backend -->|Updates| WS;

Loading

Simplified Data Flow

- CLI / REPL sends commands via HTTP REST
- Express backend converts commands to JSON event commits
- Each operation = a new immutable Git commit
- State is reconstructed by replaying Git history
- WebSockets notify clients with real-time updates
- Remote Git sync enables replication across machines

---

✨ Features

Feature	Status
Key-Value strings	✔
Lists (LPUSH / RPUSH / POP)	✔
Maps / Hashes	✔
History viewer	✔
Rollback to commit	✔
Live monitor via WebSockets	✔
Pub/Sub channels	✔
GitHub remote sync	✔
REPL with autocomplete	✔

---

🚀 Quick Start

1. Backend Setup

npm install
npm start

2. CLI Setup

cd cli
npm install
npm install ws chalk@4
npm link

3. Start REPL

kv-shell

---

🧠 Command Reference

🧵 Strings

kv set <key> <value>
kv update <key> <value>
kv get <key>
kv delete <key>
kv exists <key>
kv keys
kv flush

📦 Lists

kv list lpush <key> <value>
kv list rpush <key> <value>
kv list lpop <key>
kv list rpop <key>
kv list get <key>

🗂 Maps (Hashes)

kv map hset <key> <field> <value>
kv map hget <key> <field>
kv map hkeys <key>
kv map hdel <key> <field>

📜 History & Rollback

kv history
kv rollback <commitId>

📡 Live Monitor & Pub/Sub

kv monitor
kv subscribe <channel>
kv publish <channel> <message>

🌎 Git Remote Sync

kv remote add <repo-url>
kv sync
kv pull

---

🖥 REPL Usage (kv-shell)

kv-shell
> set name Shreyash
OK
> get name
"Shreyash"
> monitor
Entering monitoring mode...

---

🤯 Example Workflow

Terminal 1

kv-shell
kv monitor

Terminal 2

kv set name Shreyash
kv publish chat "Hello from KV"

Real-time message instantly appears in monitoring terminal.

---

🧱 Technology Stack

Component	Tech
Backend	Node.js + Express
Storage	Git Commit Log
Messaging	EventEmitter + WebSockets
CLI	Node (commander, chalk, ws)
Sync	Git / GitHub remote
Architecture	Event-Sourced + Immutable Log

---

💡 Why GitKV?

• Git-powered database = persistence + replication + audit trail.
• Time travel debugging & rollback.
• Real-time pub/sub.
• Single source of truth.
• Awesome practical Event-Sourcing example.

---

🤝 Contributing

Contributions welcome! Submit a PR.

---

📄 License

MIT License

---

🧑‍💻 Author

Shreyash Ghanekar