https://github.com/DeerYang/git-gamify
A command-line tool that turns your Git workflow into a fun RPG. Level up, unlock achievements, and make every commit rewarding.
https://github.com/DeerYang/git-gamify
Last synced: 3 months ago
JSON representation
A command-line tool that turns your Git workflow into a fun RPG. Level up, unlock achievements, and make every commit rewarding.
- Host: GitHub
- URL: https://github.com/DeerYang/git-gamify
- Owner: DeerYang
- License: mit
- Created: 2025-07-21T12:06:40.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2026-03-13T07:22:20.000Z (4 months ago)
- Last Synced: 2026-03-13T17:37:35.012Z (4 months ago)
- Language: Python
- Size: 123 KB
- Stars: 24
- Watchers: 0
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
- awesome-cli-apps-in-a-csv - Git-Gamify - A command-line tool that turns your Git workflow into a fun RPG loop where you cand earn XP, level up and unlock achievements from real Git usage. (<a name="productivity"></a>Productivity)
- awesome-cli-apps - Git-Gamify - A command-line tool that turns your Git workflow into a fun RPG loop where you cand earn XP, level up and unlock achievements from real Git usage. (<a name="productivity"></a>Productivity)
README
Git-Gamify
Turn your daily Git workflow into a lightweight RPG loop.
Earn XP, level up, and unlock achievements from real Git usage.
---
## What Is Git-Gamify
Git-Gamify wraps your normal `git` usage (`commit`, `push`) and adds a game layer:
- XP and level progression
- achievement unlocks
- reward messages on level up
- profile/stat display commands
The core goal is to keep your existing Git habits intact while adding immediate feedback and motivation.
## Features
- Progressive XP system for commits and pushes
- Daily decay/cap mechanics to avoid farming
- Streak and behavior-based achievements
- Local profile persistence per Git identity (`user.email`)
- Multi-language support (`en`, `zh`)
- Rich terminal UI output
## Installation
Requirements:
- Python 3.8+
- Git
Install from PyPI:
```bash
pip install git-gamify
```
Or install this repo in editable mode:
```bash
pip install -e .
```
## Quick Start
1. Add shell wrapper so your normal `git` command is routed through Git-Gamify.
2. Restart terminal.
3. Use Git as usual (`git commit`, `git push`).
4. Check progress with `gg profile`.
## Shell Setup
### PowerShell (Required)
Edit your profile:
```powershell
notepad $PROFILE
```
Add:
```powershell
function git {
gg git @args
}
```
Restart PowerShell.
### Bash / Zsh (Required)
Add to `~/.bashrc` or `~/.zshrc`:
```bash
function git() {
gg git "$@"
}
```
Reload shell (`source ~/.bashrc` / `source ~/.zshrc`) or restart terminal.
## Autocompletion
### CLI Completion for `gg`
Run once:
```powershell
gg --install-completion powershell
```
(`bash` and `zsh` are also supported via Typer installer.)
### PowerShell: Keep Both `gg` and Wrapped `git` Completion
When `git` is wrapped as a PowerShell function, default `git` completion can disappear because completion was attached to native `git.exe`, not your function.
Use this profile setup:
```powershell
Import-Module PSReadLine
Import-Module posh-git
$GitPromptSettings.EnablePromptStatus = $false
function git {
gg git @args
}
Set-PSReadLineKeyHandler -Chord Tab -Function MenuComplete
# gg completion
$scriptblock = {
param($wordToComplete, $commandAst, $cursorPosition)
$Env:_GG_COMPLETE = "complete_powershell"
$Env:_TYPER_COMPLETE_ARGS = $commandAst.ToString()
$Env:_TYPER_COMPLETE_WORD_TO_COMPLETE = $wordToComplete
gg | ForEach-Object {
$commandArray = $_ -Split ":::"
$command = $commandArray[0]
$helpString = $commandArray[1]
[System.Management.Automation.CompletionResult]::new(
$command, $command, "ParameterValue", $helpString
)
}
$Env:_GG_COMPLETE = ""
$Env:_TYPER_COMPLETE_ARGS = ""
$Env:_TYPER_COMPLETE_WORD_TO_COMPLETE = ""
}
Register-ArgumentCompleter -Native -CommandName gg -ScriptBlock $scriptblock
# bridge completion for wrapped git function
Register-ArgumentCompleter -CommandName git -ScriptBlock {
param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)
$line = $commandAst.ToString()
$lastWord = $wordToComplete
GitTabExpansion $line $lastWord | ForEach-Object {
[System.Management.Automation.CompletionResult]::new($_, $_, "ParameterValue", $_)
}
}
```
Notes:
- `Import-Module posh-git` is required for `GitTabExpansion`.
- If startup throws `cannot find 'gg'`, ensure `gg` is installed in the active Python environment and available in `PATH`.
- `main`/branch text in prompt is from `posh-git` prompt feature, not Git-Gamify runtime.
## Commands
### `gg profile`
Show user profile, level progress, and unlocked achievements.
```bash
gg profile
```
Options:
- `gg profile --stats` or `gg profile -s`
- `gg profile --reset`
### `gg config`
Read or update config values.
```bash
gg config --get language
gg config --set language=zh
gg config --set language=en
```
### `gg doctor`
Print local diagnostics (environment, git, and project status) for troubleshooting.
```bash
gg doctor
```
### `gg help`
Show internal command help.
```bash
gg help
```
## Data Storage
User data is stored locally under:
- Windows: `%USERPROFILE%\.git-gamify`
- Unix-like: `~/.git-gamify`
Profiles are keyed by a hash of your Git `user.email`.
## Development
Create and use a virtual environment:
```powershell
py -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
pip install pytest
pytest -q -p no:cacheprovider
```
## License
MIT License.