Need help with githug?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

6.3K Stars 939 Forks MIT License 382 Commits 19 Opened issues


Git your game on!

Services available


Need anything else?

Contributors list


Git Your Game On

Build Status Code Climate


Githug is designed to give you a practical way of learning git. It has a series of levels, each requiring you to use git commands to arrive at a correct answer.

Playing Githug

Githug should work on Linux, OS X and Windows.


Githug requires Ruby 1.8.7 or higher.

You can check which version of Ruby is installed with the following command:

ruby --version

If ruby is not installed, follow the installation instructions on


To install Githug, run

gem install githug

If you get a complaint about permissions, you can rerun the command with

sudo gem install githug

Starting the Game

After the gem is installed change directory to the location where you want the game-related assets to be stored. Then run


You will be prompted to create a directory.

No githug directory found, do you wish to create one? [yn]


(yes) to continue,
(no) to cancel and quit Githug.


Githug has 4 game commands:

  • play - The default command, checks your solution for the current level
  • hint - Gives you a hint (if available) for the current level
  • reset - Reset the current level or reset the level to a given name or path
  • levels - List all the levels

Change Log

The change log is available on the wiki. Change log


To suggest a level or create a level that has been suggested, check out the wiki.

Get yourself on the contributors list by doing the following:

  • Fork the repository
  • Make a level in the levels directory (covered below)
  • Add your level to the LEVELS array inside
    in a position that makes sense (the "commit" level after the "add" and "init" levels for example)
  • Make sure your level works (covered below)
  • Submit a pull request

Todo List

  • A follow-up to the level, more information on a specific command, etc.
  • More levels!

Writing Levels

Githug has a DSL for writing levels. Here is an example:

difficulty 1
description "There is a file in your folder called README, you should add it to your staging area"

setup do repo.init FileUtils.touch("README") end

solution do return false unless repo.status.files.keys.include?("README") return false if repo.status.files["README"].untracked

true end

hint do puts "You can type git in your shell to get a list of available git commands" end

are required.

You can include multiple hints like this:

hints [
  "You can type `git` in your shell to get a list of available git commands",
  "Check the man for `git add`"]

By default,

will remove all files from the game folder. You do not need to include a setup method if you don't want an initial git repository (if you are testing
git init
or only checking an answer.)

You can call

to initialize an empty repository.

All methods called on

are sent to the grit gem if the method does not exist, and you can use that for most git related commands (
, etc.).

Another method exists called

and it is used like so:
setup do

This will copy the contents of a repository specified in the levels folder for your level. For example, if your level is called "merge" then it will copy the contents of the "merge" folder. It is recommended that you perform the following steps:

  • mkdir "yourlevel"
  • cd "yourlevel"
  • git init
  • some git stuff
  • important rename ".git" to ".githug" so that it isn't treated as a submodule
  • cd "../"
  • git add "yourlevel"

After doing this, your level should be able to copy the contents from that git repository and use those for your level. See the "blame" level for an example of this.

Testing Levels

The easiest way to test a level is:

  • Change into your git_hug repository
  • Run
    githug reset PATH_TO_YOUR_LEVEL
  • Solve the level
  • Run
    githug test PATH_TO_YOUR_LEVEL

Please note that the

githug test
command can be run as
githug test --errors
to get an error stack trace from your solve method.

It would be ideal if you add an integration test for your level. These tests live in

and must be run in order. If you add a level but do not add a test, please add a simple
test case similar to the

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.