@a4ayush/gitquest/README.md

A git wrapper for game-style save/load points.

# GitQuest
<p align="center">
  <a href="https://www.npmjs.com/package/@a4ayush/gitquest">
    <img src="https://img.shields.io/npm/v/@a4ayush/gitquest.svg" alt="npm version">
  </a>
  <a href="https://github.com/a4ayush/gitquest/blob/main/LICENSE">
    <img src="https://img.shields.io/npm/l/@a4ayush/gitquest.svg" alt="license">
  </a>
  <a href="https://nodejs.org/">
    <img src="https://img.shields.io/node/v/@a4ayush/gitquest.svg" alt="node version">
  </a>
</p>

<p align="center">
  <img src="img/gq-header.png" alt="GitQuest header showing terminal UI">
</p>

<p align="center">
  <em>A friendly, game-like CLI for everyday version control checkpoints.</em>
</p>

---

GitQuest turns common Git workflows into a calm, guided experience. Think quick save points, safe discards, and an interactive history browser — all wrapped in a chill UX.

### 💡 Why GitQuest?
GitQuest turns version control into a calm, intentional habit.  
Instead of memorizing Git commands, you focus on flow — saving progress like checkpoints, syncing safely, and staying mindful of your creative rhythm.

## 📥 Installation and Quickstart

Requires **Node.js v18 or higher**.

### - Install globally from npm:

```bash
npm install -g @a4ayush/gitquest
```

Then, run `gq` in any git repository to launch the interactive experience:

```bash
gq
```

### - For local development and testing:

```bash
# from the project root
npm install
npm link
# now you can use `gq` locally
gq
```

## 💥 One-Shot Commands

All examples use the `gq` shorthand alias, but using the full `gitquest` command works just as well. They are completely interchangeable.

### `gq save`

Commits all changes, pushes to origin, and shows your save stats and streaks.

```bash
gq save "Your commit message"
```

<img src="img/gq-save.png" alt="GitQuest Save" width="400">

### `gq discard`

Resets the working tree and cleans untracked files. When not forced, it prompts for confirmation.

```bash
gq discard
gq discard --force
```

<img src="img/gq-discard.png" alt="GitQuest Discard" width="400">

### `gq sync`

Pulls remote changes and reports whether you’re up to date.

```bash
gq sync
```

<img src="img/gq-sync.png" alt="GitQuest Sync" width="400">

### `gq help`

Prints the usage and basic help message.

```bash
gq help
```

## ⚠️ Safety notes

⚠️ **Warning:** Commands like `gq discard --force` or branch resets in history are irreversible. Always make sure you’ve committed any work you want to keep.

- `gq discard --force` is a destructive and irreversible action. Use it with caution.
- The `reset` action in the history browser will overwrite the remote history. It requires explicit confirmation and should only be used when you fully understand the consequences.

## 🐞 Reporting bugs

If you encounter any issues, please open an issue on GitHub:
[https://github.com/a4ayush/gitquest/issues](https://github.com/a4ayush/gitquest/issues)

When reporting, please include:
- Your Node.js and npm versions.
- The minimal steps to reproduce the bug.
- The state of your repository if relevant (e.g., clean, dirty, behind remote).

## ⚖️ License and Credits

- **License**: MIT © [Ayush Saxena](https://github.com/a4ayush) (See the [LICENSE](LICENSE) file for details)
- **Author**: [Ayush Saxena](https://github.com/a4ayush)
- **Contributors**: [Orion](https://orionaix.com/) (AI collaborator)
- **Powered by**: `@clack/prompts`, `chalk`, and `simple-git`.

---

*“May your branches stay clean and your streaks stay alive.”*