GAViN — Git Visual Novel for VS Code

GAViN (Git As Visual Novel) is a visual Git GUI and learning tool for Visual Studio Code. It turns everyday Git commands into an animated command center with branch maps, commit history, repository-specific XP, achievements, and safety warnings.

MIT License · Source code · Report an issue

Why use GAViN?

• See local and remote Git branches, HEAD, upstream tracking, recent commits, and changed files in one view.
• Run common Git workflows such as status, fetch, pull, push, stage, commit, switch, merge, rebase, and stash.
• Learn Git through an included walkthrough and commands that display the exact Git operation being run.
• Earn persistent XP and achievements independently for each repository.
• Review explicit warnings before commands that can delete work or rewrite history.
• Keep access to the full Git CLI through the built-in terminal panel.

Quick start

1. Open a folder containing a Git repository in VS Code.
2. Launch GAViN in any of these ways:
   • Click GAViN beside the Git branch in the bottom status bar.
   • Run Git Visual Novel: GAViN : Git As Visual Novel: Begin Adventure from the Command Palette.
   • Click the GAViN action in the Source Control title bar.
3. Start with git status to inspect the repository.
4. Explore the Branches, Changes, Commits, Badges, and Terminal tabs.

Run Git Visual Novel: Open Tutorial from the Command Palette at any time to reopen the guided walkthrough.

Two-minute tutorial

1. Inspect the repository

Select git status --short --branch. This reads the current branch and working-tree state without modifying files.

2. Review changes

Open the Changes tab. Each file shows its index and working-tree status so you can see what is staged and unstaged.

3. Create a checkpoint

Enter a commit message and use the commit quest. GAViN stages the current changes and then creates the commit. Successful commands award XP to the current repository.

4. Explore branches

Use the Branches tab to inspect local and remote branches. Select a branch card and choose switch, merge, or rebase. Commands that rewrite history display a confirmation first.

5. Track progress

Open Badges to see unlocked achievements and total XP. Progress is stored by canonical Git repository root, so work in one repository does not affect another repository's level.

Safety model

Git commands are spawned directly without a system shell. Known destructive operations—such as hard reset, forced push, branch deletion, worktree restoration, and history rewriting—show a modal warning containing the exact command before execution.

Warnings are an assistance layer, not a substitute for backups and careful review.

Install from a VSIX

Build the extension:

npm ci
npm test
npm run package

Then install the generated package:

code --install-extension GAViN-0.1.0.vsix --force

You can also run Extensions: Install from VSIX... from the VS Code Command Palette.

Develop locally

1. Open this repository in VS Code.
2. Press F5.
3. An Extension Development Host window opens with GAViN loaded.
4. Open a Git repository in that window and launch GAViN from the status bar.

Useful commands:

npm run compile
npm test
npm run package

The package uses the project-local @vscode/vsce; a global vsce installation is not required.

Publishing

The recommended publishing path uses Microsoft Entra ID workload identity federation and an Azure managed identity. The publishing pipeline should run:

npx vsce publish --azure-credential

Do not store Marketplace PATs or Azure client secrets in this repository.

Deprecation warning

GAViN's runtime and packaged VSIX do not call Node.js url.parse(). If Node prints DEP0169 while running a packaging or editor command, use --trace-deprecation on that command to identify the external tool that emitted it. The project packages with --no-dependencies, so publishing dependencies are not shipped to extension users.

License

MIT