gitgym 0.1.0

An interactive CLI platform for learning git, inspired by Rustlings.

gitgym

An interactive CLI for learning git through hands-on exercises, inspired by Rustlings. No quizzes — you practice real git commands in real repositories inside a safe, sandboxed workspace.

Installation

pip install gitgym

Or with uv:

uv tool install gitgym

Requirements: Python 3.12+ and git. macOS and Linux only (Windows is not currently supported).

Quick Start

gitgym list              # see all 32 exercises
gitgym next              # set up the next exercise
cd ~/.gitgym/exercises/01_basics/01_init   # cd into the printed path
# ... run git commands to solve the exercise ...
gitgym verify            # check your work

Recommended Setup

Open two terminal windows (or tabs) side by side:

Terminal 1 (work)	Terminal 2 (control)
cd into the exercise directory	gitgym describe — read the goal
Run git commands to solve the exercise	gitgym hint — get a hint
Edit files, stage, commit, branch, etc.	gitgym verify — check your work
	gitgym watch — live feedback

This keeps your git work separate from the gitgym CLI, just like a real workflow.

Commands

Command	Description
gitgym list	List all exercises grouped by topic with completion status
gitgym start [exercise]	Set up an exercise (defaults to next incomplete)
gitgym next	Alias for gitgym start with no argument
gitgym describe	Print the current exercise's description and goal
gitgym verify	Check if the current exercise's goal state is met
gitgym watch	Auto re-verify on changes (Ctrl+C to stop)
gitgym hint	Show the next progressive hint
gitgym reset [exercise]	Reset an exercise to its initial state
gitgym reset --all	Reset all exercises and clear progress
gitgym progress	Show overall progress summary
gitgym clean	Remove all gitgym data from your system

Exercise names are shown in gitgym list (e.g. init, staging, amend). Use these names with gitgym start and gitgym reset.

Exercises

32 exercises across 9 topics, from beginner to advanced:

Topic	Exercises
Basics	init, staging, status, first_commit, gitignore
Committing	amend, multi_commit, diff
Branching	create_branch, switch_branches, delete_branch
Merging	fast_forward, three_way_merge, merge_conflict
History	log_basics, log_graph, blame, show
Undoing Changes	restore_file, unstage, revert, reset_soft, reset_mixed
Rebase	basic_rebase, interactive_rebase, rebase_conflict
Stashing	stash_basics, stash_pop_apply
Advanced	cherry_pick, bisect, tags, aliases

Features

Progressive hints — Each exercise has multiple hints revealed one at a time:

$ gitgym hint
Hint 1/3: Look at the `git init` command.

$ gitgym hint
Hint 2/3: Run `git init` inside the exercise directory.

Watch mode — gitgym watch polls the exercise directory and re-verifies automatically whenever you make changes. No need to switch terminals to run verify.

Progress tracking — Your progress is saved locally in ~/.gitgym/progress.json. Close your terminal and pick up where you left off. Run gitgym progress to see a per-topic breakdown.

Cleanup — When you're done, run gitgym clean to remove all exercise data from your system.

Platform Support

gitgym works on macOS and Linux. Windows is not currently supported because exercises use bash shell scripts. Windows users can use WSL as a workaround.

Contributing

Exercises follow a simple structure — each one is a directory with three files:

• exercise.toml — metadata, description, goal, and hints
• setup.sh — creates the initial repo state
• verify.sh — checks if the goal is met (exit 0 = pass)

See the exercises/ directory for examples.